create-bridgething 0.14.0 → 0.15.0

package/README.md

@@ -1,13 +1,16 @@
 # create-bridgething
 
-Scaffold a [bridgething](https://github.com/JoeyEamigh/bridgething) webapp for
-the Spotify Car Thing: React, Vite, Tailwind v4, and
-[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client).
+Scaffold a [bridgething](https://github.com/JoeyEamigh/bridgething) app source
+for the Spotify Car Thing: a GitHub repo of webapps (React, Vite, Tailwind v4,
+[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client)) that
+publishes a store catalog to GitHub Pages.
 
 ```sh
-bun create bridgething my-app
+bun create bridgething my-apps
 ```
 
+Run it again inside the source to add another app.
+
 | flag           | what you get                                  |
 | -------------- | --------------------------------------------- |
 | `--launcher`   | A replacement home screen                     |
@@ -18,9 +21,9 @@ bun create bridgething my-app
 
 `--extension` combines with `--launcher`, `--overlay`, or a plain webapp.
 
-The project ships `bun run dev`, `build`, `push` (install on a connected Car
-Thing), `share` (zip for the store), and `update` (bring the device to the
-latest release).
+The source ships `bun run dev`, `push` (install on a connected Car Thing),
+`share` (zip to hand to someone directly), `bump`, `check`, and `submit` (list
+the source in the bridgething store). Pushing to main publishes the catalog.
 
 - Docs: <https://bridgething.com/docs>
 - Source: <https://github.com/JoeyEamigh/bridgething>

package/dist/index.mjs

@@ -133,6 +133,7 @@ const TEMPLATE_DIR = join(PACKAGE_ROOT, "template");
 const SOURCE_TEMPLATE_DIR = join(PACKAGE_ROOT, "template-source");
 const SKILL_IN_APP = join(".claude", "skills", "bridgething");
 const SDK_VERSIONS = readJson(join(PACKAGE_ROOT, "template-versions.json"));
+const OWN = readJson(join(PACKAGE_ROOT, "package.json"));
 const EXTENSION = {
 	dir: "template-extension",
 	manifest: {
@@ -366,7 +367,14 @@ function scaffoldApp(root, spec) {
 function linkAgentGuides(root, appDir) {
 	const rootSkill = join(root, SKILL_IN_APP);
 	const appSkill = join(appDir, SKILL_IN_APP);
-	if (!existsSync(rootSkill)) move(appSkill, rootSkill);
+	if (!existsSync(rootSkill)) {
+		move(appSkill, rootSkill);
+		writeJson(join(rootSkill, ".source.json"), {
+			package: OWN.name,
+			version: OWN.version,
+			fetched_at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
 	linkOrCopy(relative(dirname(appSkill), rootSkill), appSkill, rootSkill);
 	for (const link of [join(root, "AGENTS.md"), join(appDir, "AGENTS.md")]) {
 		if (existsSync(link) || !existsSync(join(dirname(link), "CLAUDE.md"))) continue;
@@ -479,7 +487,7 @@ Done. ${target}
 Fill in the description in apps/${details.app}/public/manifest.json.
 
 Push to ${repoUrl}, then in Settings > Pages set the branch to gh-pages, folder / (root).
-Your catalog ends up at at ${base}/catalog.v1.json, which you can submit to the bridgething store.
+Your catalog ends up at ${base}/catalog.v1.json. Once it loads, "bun run submit" lists it in the bridgething store.
 
   bun run new <slug>   add another app to this source
   bun run bump ${details.app} [version]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bridgething",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "Scaffold a bridgething app source: webapps for the Spotify Car Thing, published as a catalog.v1 on GitHub Pages.",
   "license": "MIT",

package/template/_claude/skills/bridgething/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bridgething
-description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Use for @bridgething/client calls (now-playing, transport, artwork, storage, user settings, networking, every surface), running the dev server and driving the 800x480 screen and its physical controls, pushing the built app to a device or packaging a shareable zip, and writing the desktop-side Deno extension a webapp can ship.
+description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Use for @bridgething/client calls (now-playing, transport, artwork, storage, user settings, networking, every surface), running the dev server and driving the 800x480 screen and its physical controls, pushing the built app to a device, packaging a shareable zip, or publishing and listing it in the bridgething store, and writing the desktop-side Deno extension a webapp can ship.
 ---
 
 # Building a bridgething webapp
@@ -11,8 +11,8 @@ description: Build, run, and ship a bridgething webapp for the Spotify Car Thing
 - Running the app, screenshotting the 800x480 screen, and pressing the physical
   controls locally and over CDP on the device:
   [reference/develop.md](reference/develop.md)
-- Installing onto a connected Car Thing, packaging a zip, and updating the
-  device: [reference/ship.md](reference/ship.md)
+- Installing onto a connected Car Thing, packaging a zip, publishing to the
+  store, and updating the device: [reference/ship.md](reference/ship.md)
 - The desktop-side Deno extension, its `ctx` contract, and its permission model,
   when the project has an `extension/` directory:
   [reference/extension.md](reference/extension.md)

package/template/_claude/skills/bridgething/reference/ship.md

@@ -31,6 +31,26 @@ Anyone with a bridgething Car Thing installs that zip from the companion app.
 
 Raise `version` in `public/manifest.json` before you share an update. Keep `id`.
 
+## Publish to the store
+
+From the repo root, `bun run bump <slug> <major | minor | patch>` moves the
+version, then a push to main runs the publish workflow. It builds every new
+version into `catalog.v1.json` on the `gh-pages` branch. GitHub Pages has to
+serve that branch from `/ (root)` (repo Settings > Pages), and the catalog lands
+at `base_url` from `source.json` plus `/catalog.v1.json`.
+
+Until the source is submitted, the store does not show it, and only people who
+paste that URL into the companion app can install from it. Once the first
+publish is live and the catalog URL loads, ask the user whether they want it in
+the bridgething store. A listing is public, so submit only on a yes:
+
+```bash
+bun run submit   # lists the source, or refreshes an existing listing
+```
+
+The store rechecks every listed source on its own, so later versions appear
+without another submit. Run it again to pick one up right away.
+
 ## Keep the device on the latest bridgething
 
 ```bash

package/template-source/CLAUDE.md

@@ -36,7 +36,7 @@ Now-playing and library data come from the phone's Spotify, so render a placehol
 
 Every surface: `player asset config store doc blob capabilities library audio notifications phone peer geo net hardware bluetooth system time voice lyrics webapp forward`. Each method is an event, a request, or a command.
 
-Methods, types, and examples: `.claude/skills/bridgething/reference/sdk.md`. That skill lives once at the repo root and every app symlinks it, so it is one copy for the whole workspace. `bun run skills` refreshes it from the published `create-bridgething`; `bun run check` says when it is behind.
+Methods, types, and examples: `.claude/skills/bridgething/reference/sdk.md`. That skill lives once at the repo root and every app symlinks it, so it is one copy for the whole workspace. `bun run skills` refreshes it from the published `create-bridgething`; it and `bun run check` say when the skill is behind, when `@bridgething/source` is older than the skill expects, and when `package.json` lacks a script the skill uses.
 
 ## Working on one app
 
@@ -54,7 +54,7 @@ bun run --cwd apps/<slug> update       # brings the device to the latest bridget
 
 An app with a variant or an extension carries its own `apps/<slug>/CLAUDE.md` with the parts specific to it.
 
-Running and driving the app: `.claude/skills/bridgething/reference/develop.md`. Push, zip, update: `.claude/skills/bridgething/reference/ship.md`. The desktop-side Deno extension and its permission model, for an app with an `extension/` directory: `.claude/skills/bridgething/reference/extension.md`.
+Running and driving the app: `.claude/skills/bridgething/reference/develop.md`. Push, zip, publish to the store, update: `.claude/skills/bridgething/reference/ship.md`. The desktop-side Deno extension and its permission model, for an app with an `extension/` directory: `.claude/skills/bridgething/reference/extension.md`.
 
 ## The three files that describe an app
 
@@ -92,6 +92,8 @@ bun run check
 
 Pushing to main publishes. `bun run publish --dry-run` assembles the exact bytes that would be pushed, into `site/`, without pushing.
 
+The store only shows a source that has been submitted to it. Once the first publish is live, ask the user whether they want it in the bridgething store, and run `bun run submit` only on a yes, because a listing is public. The store rechecks listed sources on its own, so a later version needs no second submit.
+
 ## Publishing rules that are not negotiable
 
 - **A published version is immutable.** `published.json` on the `gh-pages` branch records the sha256 clients verify against. Changing an app means a new version, always. `check` fails a pull request that changed an app without bumping it.

package/template-source/README.md

@@ -9,7 +9,7 @@ Webapps for the Spotify Car Thing running [bridgething](https://bridgething.com)
 1. Push this repo to `https://github.com/__REPO_OWNER__/__REPO_NAME__`.
 2. In **Settings > Pages**, set the source to **Deploy from a branch**, branch `gh-pages`, folder `/ (root)`.
 
-The catalog is published to `__BASE_URL__/catalog.v1.json`, which can be submitted to <bridgething.com/apps>
+The catalog is published to `__BASE_URL__/catalog.v1.json`. Once it loads, `bun run submit` lists it in the [bridgething store](https://bridgething.com/apps).
 
 ## Develop
 
@@ -45,7 +45,7 @@ bun run bump __APP_SLUG__ patch -m "Fix the wind direction arrow"
 git commit -am "__APP_SLUG__: fix the wind direction arrow" && git push
 ```
 
-Pushing to main builds the apps and regenerates the catalog.
+Pushing to main builds the apps and regenerates the catalog. The store rechecks listed sources on its own; `bun run submit` refreshes right away.
 
 ## Agent skill
 
@@ -53,5 +53,5 @@ Pushing to main builds the apps and regenerates the catalog.
 
 ```sh
 bun run skills           # refresh it from the published create-bridgething
-bun run skills --check   # check whether it is behind
+bun run skills --check   # check whether it, the toolkit, or the scripts it uses are behind
 ```

package/template-source/package.json

@@ -17,6 +17,7 @@
     "shot": "bridgething-source shot",
     "catalog": "bridgething-source catalog",
     "publish": "bridgething-source publish",
+    "submit": "bridgething-source submit",
     "skills": "bridgething-source skills",
     "format": "prettier --write \"*.json\" \"*.js\""
   },

package/template-versions.json

@@ -1,6 +1,6 @@
 {
   "@bridgething/client": "^0.14.0",
   "@bridgething/extension": "^0.14.0",
-  "@bridgething/source": "^0.14.0",
-  "libbridgething": "0.14.0"
+  "@bridgething/source": "^0.15.0",
+  "libbridgething": "0.14.1"
 }