@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/vercel/object-stores/vercel-blob.mjs

@@ -0,0 +1,147 @@
+/**
+ * @file Vercel Blob share-link store: the Vercel plugin's `ObjectStoreProvider` (provider id `vercel`,
+ * so the share path resolves the saved `vercel` connection), contributing only `createArtifactStore`.
+ * A site owner whose only host is Vercel gets a share download link without setting up S3.
+ *
+ * Wire format mirrors `@vercel/blob`'s `put()` and `del()` (an installed plugin has no npm
+ * dependencies): `PUT {BLOB_API}/?pathname=<key>` and `POST {BLOB_API}/delete { urls }`, both with the
+ * Blob store's read-write token. Every request goes through `kit.fetch` with the redirect guard, so
+ * the token is never forwarded to another host.
+ *
+ * Unguessable without a random suffix: the key already carries the share's 16-letter (~91-bit) token
+ * (`_share/<token>/<name>.tovu.zip`) and anonymous readers cannot list a Blob store. A suffix would
+ * also make the URL underivable from the key, and `delete` (revoke) receives only the key.
+ *
+ * Plain JS by owner decision (2026-09-29), like `targets/vercel.mjs`.
+ */
+
+const BLOB_API = "https://vercel.com/api/blob";
+/** Matches `@vercel/blob` 2.8.2 (`BLOB_API_VERSION = 13`, sent on every API call). */
+const BLOB_API_VERSION = "13";
+/** The smallest edge cache Blob allows, so a revoked link stops serving within about a minute. */
+const BLOB_CACHE_MAX_AGE_SECONDS = "60";
+/** The token is 16 ASCII letters, the shape core's `SHARE_TOKEN` mints (a plugin cannot import core). */
+const SHARE_KEY = /^_share\/[A-Za-z]{16}\/[a-z0-9][a-z0-9-]{0,79}\.tovu\.zip$/;
+/** `vercel_blob_rw_<storeId>_<secret>`: the store id names the public host, as `@vercel/blob` reads it. */
+const BLOB_TOKEN = /^vercel_blob_rw_([A-Za-z0-9]+)_\w+$/;
+
+/**
+ * The Blob store's public origin. `new URL` lowercases the host, as Blob serves it.
+ * @param {{ blobToken: string | undefined, kit: any }} required
+ * @throws {DeployError} The token is missing or not a Blob read-write token; the message never echoes it.
+ * @complexity O(token length).
+ */
+function storeOrigin(required) {
+  const match = BLOB_TOKEN.exec(required.blobToken ?? "");
+  if (!match) throw new required.kit.DeployError("Add a Vercel Blob read-write token to the Vercel connection to get share links.", 400);
+  return new URL(`https://${match[1]}.public.blob.vercel-storage.com`).origin;
+}
+
+/**
+ * One authenticated Blob API call. Errors carry only the operation and HTTP status, never the token,
+ * key or a response body (which may echo either).
+ * @param {{ kit: any, blobToken: string, path: string, op: string, init: RequestInit }} required
+ * @complexity One request.
+ */
+async function blobApi(required) {
+  const { kit, blobToken, path, op, init } = required;
+  const headers = { ...init.headers, authorization: `Bearer ${blobToken}`, "x-api-version": BLOB_API_VERSION };
+  const response = await kit.fetch(`${BLOB_API}${path}`, kit.redirectGuardInit({ ...init, headers }), { timeoutMs: kit.timeouts.UPLOAD });
+  kit.assertNotRedirected(response, "Vercel Blob");
+  if (!response.ok) throw new kit.DeployError(`Vercel Blob ${op} failed (HTTP ${response.status}).`, 502);
+  return response;
+}
+
+/**
+ * @param {{ key: string, kit: any }} required
+ * @throws {DeployError} Not a share artifact key.
+ */
+function requireKey(required) {
+  if (!SHARE_KEY.test(required.key)) throw new required.kit.DeployError("Invalid share artifact key.", 400);
+}
+
+/**
+ * True when Blob stored the object at exactly `origin/key`: no suffix, no other store.
+ * @param {{ returned: unknown, origin: string, key: string }} required
+ */
+function isExactBlobUrl(required) {
+  if (typeof required.returned !== "string") return false;
+  const url = URL.canParse(required.returned) ? new URL(required.returned) : undefined;
+  return url?.origin === required.origin && url.pathname === `/${required.key}` && !url.search;
+}
+
+/**
+ * The share-facing artifact store over one Blob store.
+ * @param {{ blobToken: string, kit: any }} required
+ * @returns {import("@jini-ai/devops/deploy").ArtifactStorePort & { binding: string }}
+ * @complexity O(1) to build; each call is one request.
+ */
+function createBlobArtifactStore(required) {
+  const { blobToken, kit } = required;
+  const origin = storeOrigin(required);
+  // `?download=1` is Blob's attachment URL, so the browser saves the ZIP instead of opening it.
+  const shareUrl = (key) => `${origin}/${key}?download=1`;
+  return {
+    /** Core records this so revoke only deletes through the same Blob store the share was put in. */
+    binding: origin,
+    async upload({ key, bytes }, options = {}) {
+      requireKey({ key, kit });
+      options.signal?.throwIfAborted();
+      const response = await blobApi({ kit, blobToken, op: "upload", path: `/?pathname=${encodeURIComponent(key)}`, init: {
+        method: "PUT", body: bytes, signal: options.signal,
+        // `@vercel/blob` 2.8.2 `put()` always sends the access header; shares are public by design.
+        headers: { "x-vercel-blob-access": "public", "x-content-type": "application/zip", "x-add-random-suffix": "0", "x-allow-overwrite": "1", "x-cache-control-max-age": BLOB_CACHE_MAX_AGE_SECONDS },
+      } });
+      const stored = await response.json().catch(() => ({}));
+      if (!isExactBlobUrl({ returned: stored.url, origin, key })) throw new kit.DeployError("Vercel Blob stored the share under an unexpected address.", 502);
+      return { url: shareUrl(key) };
+    },
+    /** Revoke. Blob's delete is idempotent: an already-absent URL still answers 200. */
+    async delete({ key }, options = {}) {
+      requireKey({ key, kit });
+      await blobApi({ kit, blobToken, op: "delete", path: "/delete", init: {
+        method: "POST", signal: options.signal, headers: { "content-type": "application/json" }, body: JSON.stringify({ urls: [`${origin}/${key}`] }),
+      } });
+    },
+    /**
+     * Anonymous HEAD of the public URL. Blob does not serve the no-store/robots headers the Tovu
+     * delivery contract checks, so this checks what Blob does guarantee: exact size and ZIP type.
+     */
+    async verify({ key, url, present, bytes }, options = {}) {
+      requireKey({ key, kit });
+      if (url !== shareUrl(key)) return false;
+      const response = await kit.fetch(url, { method: "HEAD", redirect: "error", signal: options.signal }, { timeoutMs: kit.timeouts.QUICK });
+      if (!present) return response.status === 404 || response.status === 410;
+      return response.status === 200 && Number(response.headers.get("content-length")) === bytes && /^application\/zip(?:;|$)/i.test(response.headers.get("content-type") ?? "");
+    },
+  };
+}
+
+/** The module contract the host's object-store registry loads (`ObjectStoreProvider`). */
+export default {
+  /** Publishing needs only an API token; sharing requires the separate Blob token.
+   * @param {{ credential: any }} required
+   * @returns {boolean} Whether this connection can supply a Blob artifact store, without I/O.
+   * @complexity O(token length).
+   */
+  acceptsArtifactCredential({ credential }, _optional = {}) {
+    return typeof credential?.blobToken === "string" && BLOB_TOKEN.test(credential.blobToken);
+  },
+  /**
+   * Blob holds share links only; site media stays on its configured store.
+   * @returns {{ status: "rejected", error: { code: "not_configured", message: string } }}
+   */
+  create(_required, _optional = {}) {
+    return { status: "rejected", error: { code: "not_configured", message: "Vercel Blob is used for share links only, not site media." } };
+  },
+
+  /**
+   * @param {{ credential: Record<string, string | undefined> & { token: string }, kit: any }} required
+   *   `credential.blobToken`: the optional Blob read-write token on the Vercel connection.
+   * @param {Record<string, never>} [_optional]
+   * @throws {DeployError} No usable Blob token; the share path then falls back to download-only.
+   */
+  createArtifactStore(required, _optional = {}) {
+    return createBlobArtifactStore({ blobToken: required.credential.blobToken, kit: required.kit });
+  },
+};

package/vercel/plugin.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "vercel",
+  "version": "0.1.0",
+  "description": "Publishes the site's static export to Vercel with the workspace's own saved token. Ships the host code itself (a host loads it only because that host chose to ship this plugin) and the know-how an agent needs: where to get a token, the optional team, Deployment Protection, and what each failure means in plain words.",
+  "author": "Tovu",
+  "license": "Apache-2.0",
+  "extensions": {
+    "tovu": {
+      "displayName": "Vercel",
+      "summary": "Puts your website online on Vercel. The assistant shows you a preview first.",
+      "id": "tovu/vercel",
+      "provides": [
+        "deploy-target:vercel"
+      ],
+      "credentialCards": [
+        {
+          "target": "vercel",
+          "title": "Connect Vercel",
+          "label": "Vercel connection",
+          "category": "hosting",
+          "intro": "Connect Vercel to publish this site as a production deployment.",
+          "usedFor": [
+            "Publishes and updates your live website on Vercel",
+            "Optional: shares site exports as download links from your Vercel Blob store"
+          ],
+          "keyHint": "Create an access token for the personal account or team that owns the project, with permission to create projects and production deployments. Select that team as the token scope when publishing to a team. For share links, also add the read-write token of a Vercel Blob store (optional).",
+          "saveKind": "publish-host",
+          "helpUrl": "https://vercel.com/account/tokens",
+          "helpLabel": "Create a token",
+          "baseUrl": "https://api.vercel.com"
+        }
+      ]
+    }
+  },
+  "keywords": [
+    "vercel",
+    "deploy",
+    "publish",
+    "hosting",
+    "static-site",
+    "static-export",
+    "go-live",
+    "website",
+    "deploy-target:vercel"
+  ]
+}

package/vercel/skills/vercel/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: vercel
+description: Publish the site's static export to Vercel with the workspace's own saved token. Covers the token, the optional team, the project name, how a publish reaches the live address, Deployment Protection, and what each failure means in plain words.
+---
+
+# Vercel
+
+## Connection card
+
+Choose the card yourself from its `usedFor` list. Reuse a saved key or working sign-in for that
+task. Never offer a replacement unless the person asks.
+
+Open the plugin’s **Connect Vercel** card with `credential_save {kind:"plugin-provider",target:"vercel"}`. It links to token creation and explains account/team access. The hosting save flow verifies and seals the token.
+
+The steps are the same for every host: `deployment_get_static_publish_capabilities` shows whether a
+token is saved, `deployment_preview_static_publish` comes first, and `deployment_execute_static_publish`
+publishes once the person confirms. `ok: "partial"` means not reachable yet: never call it failed or live.
+This file is what is particular to Vercel.
+
+- **Token:** an access token from https://vercel.com/account/tokens. Save it with the plugin card above.
+- **Share links (optional):** to share a site export as a download link with no S3, the person adds a
+  Vercel Blob store's read-write token (Vercel > Storage > Blob store > `BLOB_READ_WRITE_TOKEN`) in the
+  card's optional **Blob read-write token** field. They type it into the card, never into the chat.
+  Without it, a share is a private download only. A revoked link can keep serving for up to a minute
+  (Blob's edge cache); if revoke says deletion is not verified yet, retry it after a minute.
+- **Team (optional):** the publish config's `teamId` puts the project under a Vercel team instead of the
+  personal account. Leave it out for a personal account; a blank one is refused.
+- **Project name:** the project name, lowercased with hyphens (up to 80 characters). Publishing again
+  updates the same project.
+- **Security headers:** this plugin writes them into a root `vercel.json`; a `vercel.json` in the site
+  itself is replaced.
+- **Production, every time:** each publish is a production deployment, so it updates the live
+  `<project>.vercel.app` address, not a preview.
+- **Only changed files upload.** Files go up one by one, keyed by their fingerprint. If Vercel says some
+  are missing when the deployment is created, the host sends exactly those and tries once more.
+- **Deployment Protection:** new Vercel projects often require a Vercel login to view. The host detects that
+  and reports the link as protected rather than live.
+
+## Failure messages and what to tell the person
+
+| Message | Meaning | Next step |
+|---|---|---|
+| `Vercel token is required.` | No token in the saved credential. | Open the plugin card above. |
+| `You don't have permission to create a project.` | The token cannot create projects (often the wrong team). | Check the token's scope or the `teamId`. |
+| `Deployment is protected by Vercel. ...` | The site is up but behind Vercel's login. | In Vercel, turn off Deployment Protection for the project, or add a custom domain. |
+| `Vercel deployment failed.` | Vercel refused the build after upload. | Retry once; if it repeats, check the deployment log in the Vercel dashboard. |
+| `... attempted to redirect an authenticated request ...` | Something between the host and Vercel redirected the call; the host refused to send the token on. | Retry later; if it repeats, check the server's network or proxy. |
+| `Vercel returned a non-JSON response.` / `fetch timed out after ...` | Vercel or the network had a hiccup. | Retry in a minute. |