Merge branch 'main' into blob-skill

tmcw · web-flow · commit 4055a0c4a6db · 2026-06-08T13:30:54.000-04:00
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -0,0 +1,21 @@
+{
+  "name": "valtown",
+  "interface": {
+    "displayName": "Val Town"
+  },
+  "plugins": [
+    {
+      "name": "vals",
+      "source": {
+        "source": "local",
+        "path": "./plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Coding",
+      "description": "Val Town MCP server + platform skills for building and deploying vals."
+    }
+  ]
+}
diff --git a/.changeset/sync-all-plugin-manifests.md b/.changeset/sync-all-plugin-manifests.md
@@ -0,0 +1,5 @@
+---
+"@valtown/skills": patch
+---
+
+Version sync now updates every plugin manifest (Claude, Codex, and Cursor plugin.json plus the Cursor marketplace.json `metadata.version`), not just the Claude manifest — preventing the Codex/Cursor manifests from advertising a stale version on release.
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -3,7 +3,7 @@
   "owner": { "name": "Val Town" },
   "plugins": [
     {
-      "name": "vals",
+      "name": "valtown",
       "source": "./plugin",
       "description": "Val Town MCP server + platform skills for building and deploying vals."
     }
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
@@ -0,0 +1,18 @@
+{
+  "name": "valtown",
+  "owner": {
+    "name": "Val Town",
+    "url": "https://val.town"
+  },
+  "metadata": {
+    "description": "Val Town MCP server + platform skills for building and deploying vals.",
+    "version": "0.1.2"
+  },
+  "plugins": [
+    {
+      "name": "valtown",
+      "source": "./plugin",
+      "description": "Val Town MCP server + platform skills for building and deploying vals."
+    }
+  ]
+}
diff --git a/README.md b/README.md
@@ -1,32 +1,62 @@
-# Claude Code plugin for Val Town
+# Agent plugins for Val Town
 
-Installs the Val Town MCP server and skills for Claude Code.
+Installs the Val Town MCP server and Skills for Claude Code, Codex, and Cursor.
 
-Contains platform guidance for building on [Val Town](https://val.town) — the 
-single source of truth for the "how to write a val" knowledge used by Val Town's 
-own tools (Townie, the MCP server) and by AI coding tools like Claude Code.
-
-Each skill is a short markdown guide covering one platform topic (HTTP vals,
-cron/intervals, SQLite, email, OAuth, React UI, third-party integrations,
-templates).
+Skills are markdown files with platform guidance for building on [Val Town](https://val.town).
+Used by Val Town's own tools (Townie, the MCP server) and by AI coding agents.
+Skills include HTTP vals, crons, SQLite, email, OAuth, frontend, and API integrations.
 
 ## Install
 
-Start a `claude` session, then run:
+Installing the plugin makes platform skills available to your agent and registers
+the hosted Val Town MCP server (`https://api.val.town/v3/mcp`). On first use of
+an MCP tool, the agent runs the OAuth flow in your browser.
+
+1. [Claude Code](#claude-code)
+2. [Codex](#codex)
+3. [Cursor](#cursor)
+
+### Claude Code
+
+Install the Val Town plugin by running:
 
 ```
-/plugin marketplace add val-town/plugins
+claude plugin install valtown@claude-plugins-official
 ```
 
-Then run:
+### Codex
+
+#### `codex` CLI
+
+First, run:
 
 ```
-/plugin install vals@valtown
+codex plugin marketplace add val-town/plugins
 ```
 
-This makes the platform skills available to Claude and registers the hosted
-Val Town MCP server (`https://api.val.town/v3/mcp`). On first use of an MCP tool,
-Claude Code runs the OAuth flow in your browser.
+Then fire up `codex` and run:
+
+```
+/plugins
+```
+
+Search for Val Town, hit install, and it'll take you through the OAuth path.
+
+#### Codex desktop app
+
+1. Click "Plugins" in the sidebar
+2. In the dropdown that says "Built by OpenAI" click "Add more +"
+3. Copy-paste `https://github.com/val-town/plugins` and select "Add marketplace"
+
+### Cursor
+
+In Cursor, run:
+
+```
+/add-plugin valtown
+```
+
+Or in Cursor Settings, copy-paste `https://github.com/val-town/plugins` in the search box and select "Add to Cursor."
 
 ## Contributing
 
@@ -84,3 +114,18 @@ for publishing. See their documentation for more information.
 - Each change in that directory will prompt the `release.yml` GitHub action
   to create a new release PR.
 - Merging a release PR will automatically publish a new version of this module.
+
+### Configuration
+
+#### Claude Code
+
+The official Claude plugin marketplace pulls from [`.plugins/marketplace.json`](./.plugins/marketplace.json).
+
+#### Codex
+
+Codex reads the native marketplace at `.agents/plugins/marketplace.json` (and
+falls back to the Claude `.claude-plugin/marketplace.json` for compatibility).
+
+#### Cursor
+
+Cursor reads `.cursor-plugin/marketplace.json` and the per-plugin `plugin/.cursor-plugin/plugin.json`.
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
@@ -1,13 +1,13 @@
 {
-  "name": "vals",
+  "name": "valtown",
   "displayName": "Val Town",
   "description": "Build and deploy on Val Town. Bundles the Val Town MCP server and platform skills (HTTP vals, cron/intervals, SQLite, email, OAuth, React UI, third-party integrations, templates).",
   "version": "0.1.2",
   "author": {
     "name": "Val Town"
   },
   "homepage": "https://val.town",
-  "repository": "https://github.com/val-town/claude",
+  "repository": "https://github.com/val-town/plugins",
   "license": "MIT",
   "keywords": [
     "val-town",
diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json
@@ -0,0 +1,22 @@
+{
+  "name": "vals",
+  "displayName": "Val Town",
+  "version": "0.1.2",
+  "description": "Build and deploy on Val Town. Bundles the Val Town MCP server and platform skills (HTTP vals, cron/intervals, SQLite, email, OAuth, React UI, third-party integrations, templates).",
+  "author": { "name": "Val Town" },
+  "homepage": "https://val.town",
+  "repository": "https://github.com/val-town/plugins",
+  "license": "MIT",
+  "keywords": ["val-town", "deno", "serverless", "typescript"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Val Town",
+    "shortDescription": "Build and deploy on Val Town",
+    "longDescription": "Bundles the hosted Val Town MCP server and platform skills (HTTP vals, cron/intervals, SQLite, email, OAuth, React UI, third-party integrations, templates) for building and deploying TypeScript on Val Town.",
+    "developerName": "Val Town",
+    "category": "Coding",
+    "websiteURL": "https://val.town",
+    "composerIcon": "./assets/icon.svg"
+  }
+}
diff --git a/plugin/.cursor-plugin/plugin.json b/plugin/.cursor-plugin/plugin.json
@@ -0,0 +1,13 @@
+{
+  "name": "vals",
+  "displayName": "Val Town",
+  "version": "0.1.2",
+  "description": "Build and deploy on Val Town. Bundles the Val Town MCP server and platform skills (HTTP vals, cron/intervals, SQLite, email, OAuth, React UI, third-party integrations, templates).",
+  "author": {
+    "name": "Val Town",
+    "url": "https://val.town"
+  },
+  "license": "MIT",
+  "keywords": ["val-town", "deno", "serverless", "typescript", "cursor", "mcp"],
+  "logo": "assets/icon.svg"
+}
diff --git a/plugin/assets/icon.svg b/plugin/assets/icon.svg
@@ -0,0 +1,6 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="512" height="512" rx="112" fill="#000000"/>
+  <g transform="translate(116,110.75) scale(17.5)">
+    <path d="M11.9016 12.5885C11.4698 12.5885 11.1196 12.4542 10.8511 12.1856C10.5823 11.917 10.4481 11.5578 10.4481 11.1087V7.40896H9.76608L7.25838 11.7493C6.95826 12.2689 6.40374 12.589 5.80374 12.589H4.67214C4.07514 12.589 3.59106 12.1049 3.59106 11.5079V7.40943H1.99964V6.03519H4.25214C4.80654 6.03519 5.25594 6.48459 5.25594 7.03899V11.3733H5.49378L8.2617 6.78219C8.54077 6.3193 9.04155 6.03601 9.58185 6.03519L10.4481 6.03484V4H12.1129V6.03484H13.91V7.40896H12.1129V10.8179C12.1129 11.0822 12.2362 11.2144 12.483 11.2144H13.7514V12.5885H11.9016Z" fill="#FFFFFF"/>
+  </g>
+</svg>
diff --git a/plugin/mcp.json b/plugin/mcp.json
@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "valtown": {
+      "url": "https://api.val.town/v3/mcp"
+    }
+  }
+}
diff --git a/scripts/sync-plugin-version.mjs b/scripts/sync-plugin-version.mjs
@@ -1,36 +1,66 @@
-// Syncs the Claude plugin manifest version to the npm package version.
+// Syncs every plugin manifest version to the npm package version.
 //
-// Changesets only bumps package.json. This keeps
-// plugin/.claude-plugin/plugin.json in lockstep so the published plugin and
-// the npm package never drift. Run as part of the `version` script, so the
-// bump lands in the "Version Packages" PR alongside the changelog.
+// Changesets only bumps package.json. This keeps the Claude, Codex, and Cursor
+// plugin manifests (and the Cursor marketplace manifest) in lockstep so the
+// published plugins and the npm package never drift. Run as part of the
+// `version` script, so the bump lands in the "Version Packages" PR alongside
+// the changelog.
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_FILE = join(ROOT, "package.json");
-const PLUGIN_FILE = join(ROOT, "plugin", ".claude-plugin", "plugin.json");
+
+// Manifests that carry a version which must track the npm package version.
+// `key` is the dotted path to the version field within each JSON file.
+const TARGETS = [
+  { file: join(ROOT, "plugin", ".claude-plugin", "plugin.json"), key: "version" },
+  { file: join(ROOT, "plugin", ".codex-plugin", "plugin.json"), key: "version" },
+  { file: join(ROOT, "plugin", ".cursor-plugin", "plugin.json"), key: "version" },
+  { file: join(ROOT, ".cursor-plugin", "marketplace.json"), key: "metadata.version" },
+];
 
 const { version } = JSON.parse(readFileSync(PKG_FILE, "utf8"));
 if (typeof version !== "string" || version.length === 0) {
   console.error("✗ Could not read version from package.json");
   process.exit(1);
 }
 
-const raw = readFileSync(PLUGIN_FILE, "utf8");
-const plugin = JSON.parse(raw);
+const getAt = (obj, key) => key.split(".").reduce((o, k) => (o == null ? o : o[k]), obj);
+const setAt = (obj, key, value) => {
+  const path = key.split(".");
+  const last = path.pop();
+  const parent = path.reduce((o, k) => (o[k] ??= {}), obj);
+  parent[last] = value;
+};
 
-if (plugin.version === version) {
-  console.log(`✓ Plugin version already in sync (${version})`);
-  process.exit(0);
-}
+let failed = false;
+for (const { file, key } of TARGETS) {
+  const rel = file.slice(ROOT.length + 1);
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    console.error(`✗ Missing manifest: ${rel}`);
+    failed = true;
+    continue;
+  }
+
+  const manifest = JSON.parse(raw);
+  const previous = getAt(manifest, key);
 
-const previous = plugin.version;
-plugin.version = version;
+  if (previous === version) {
+    console.log(`✓ ${rel} already in sync (${version})`);
+    continue;
+  }
+
+  setAt(manifest, key, version);
+  // Preserve trailing newline if the original had one.
+  const trailing = raw.endsWith("\n") ? "\n" : "";
+  writeFileSync(file, JSON.stringify(manifest, null, 2) + trailing);
+  console.log(`✓ Synced ${rel} ${previous} -> ${version}`);
+}
 
-// Preserve trailing newline if the original had one.
-const trailing = raw.endsWith("\n") ? "\n" : "";
-writeFileSync(PLUGIN_FILE, JSON.stringify(plugin, null, 2) + trailing);
-console.log(`✓ Synced plugin version ${previous} -> ${version}`);
+if (failed) process.exit(1);

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@valtown/skills": patch
 +---
++
 +Version sync now updates every plugin manifest (Claude, Codex, and Cursor plugin.json plus the Cursor marketplace.json `metadata.version`), not just the Claude manifest — preventing the Codex/Cursor manifests from advertising a stale version on release.
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`"owner": { "name": "Val Town" },`
`4`	`4`	`"plugins": [`
`5`	`5`	`{`
`6`		`- "name": "vals",`
	`6`	`+ "name": "valtown",`
`7`	`7`	`"source": "./plugin",`
`8`	`8`	`"description": "Val Town MCP server + platform skills for building and deploying vals."`
`9`	`9`	`}`