@odyn-app/api 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @odyn-app/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The building kit for [Odyn](https://github.com/New-Genre/odyn-extensions) extensions.
+
+Start a new extension, work on it, and publish it:
+
+```bash
+bunx --package @odyn-app/api odyn-extension create "My extension"
+cd my-extension
+bun install
+bun run dev       # rebuilds on every save; Odyn reloads it
+bun run publish   # sends it to Odyn's Marketplace for review
+```
+
+Your extension's entry file:
+
+```ts
+import { defineExtension } from '@odyn-app/api'
+
+defineExtension({
+  commands: {
+    'say-hello': async () => ({ type: 'detail', markdown: 'Hello from my extension.' }),
+  },
+})
+```
+
+- `odyn-extension`: the command-line tool above — `create`, `dev`, `build`, `check`, `pull <id>` and `publish`.
+- `@odyn-app/api`: `defineExtension`, the `odyn` bridge, the manifest types and the manifest checker.
+- `@odyn-app/api/ui`: Odyn's `Button`, `Skeleton`, `SettingRow`, `Orb` and `cn`, for extension pages.
+- `@odyn-app/api/theme.css`: Odyn's colours, fonts and light/dark themes. Add `@import "@odyn-app/api/theme.css";` to a page's stylesheet.
+
+Every extension runs sandboxed, and each call is checked against the permissions the user granted.
+
+**[Read the docs](https://www.odyn.build/docs/extensions)** for what extensions can and can't do, every permission and limit, and the full reference. To publish one to Odyn's Marketplace, see the [contribution guide](https://github.com/New-Genre/odyn-extensions/blob/main/CONTRIBUTING.md).
+
+MIT licence.

package/cli/build.mjs

@@ -0,0 +1,146 @@
+/**
+ * Builds one extension folder. Shared by `odyn-extension build` (an author's
+ * own folder, built in place into `dist/`) and the public repo's release
+ * build (built into a separate folder that becomes the download).
+ *
+ * What gets built, when the extension has it:
+ *   - commands, `src/index.ts`  → `dist/index.js` (one self-contained script)
+ *   - a page, `index.html`      → `dist/panel/`
+ *   - a background helper, `src/helper.ts` → `dist/helper.js`
+ * Every manifest is checked with the same checker Odyn runs on a download,
+ * so a broken one fails here rather than on someone's Mac.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/postcss'
+import { build } from 'vite'
+import { validateManifest } from '../dist/index.js'
+
+const PANEL_DIR = join('dist', 'panel')
+const HELPER_SOURCE = join('src', 'helper.ts')
+const COMMANDS_SOURCE = join('src', 'index.ts')
+/** The Chinese hand-drawn font is 12 MB on its own; Chinese text falls back to a system font. */
+const SKIPPED_FONT_FAMILIES = new Set(['Xiaolai'])
+/** The drawing library's folder, as it appears in the paths of the files a build uses. */
+const DRAWING_LIBRARY_PATH = '/node_modules/@excalidraw/excalidraw/'
+/** The only parts of an extension's `package.json` Odyn reads. */
+const SHIPPED_PACKAGE_KEYS = ['name', 'version', 'private', 'odyn']
+
+/** Reads an extension's `package.json`. */
+export function readPackage(sourceDir) {
+  return JSON.parse(readFileSync(join(sourceDir, 'package.json'), 'utf8'))
+}
+
+/**
+ * Checks an extension folder's manifest. Returns the problems found.
+ * `official` relaxes the rules for extensions made by Odyn.
+ */
+export function checkExtension(sourceDir, { official = false } = {}) {
+  if (!existsSync(join(sourceDir, 'package.json'))) return ['This folder has no package.json.']
+  const pkg = readPackage(sourceDir)
+  if (typeof pkg.odyn !== 'object' || pkg.odyn === null) return ['package.json has no "odyn" section.']
+  const problems = []
+  if (pkg.private !== true) problems.push('"private": true is required, so it is never published to npm by mistake.')
+  const manifest = { ...pkg.odyn, version: pkg.version }
+  problems.push(...validateManifest(manifest, { official }))
+  return problems
+}
+
+/**
+ * Stops the build if a page or helper reaches outside its own folder — an
+ * extension must never quietly bundle another's files. Installed packages
+ * (the kit, React and so on) are fine.
+ */
+function stayInsideFolder(sourceDir, onDrawingLibrary) {
+  return {
+    name: 'odyn-stay-inside-folder',
+    generateBundle() {
+      for (const moduleId of this.getModuleIds()) {
+        const library = moduleId.indexOf(DRAWING_LIBRARY_PATH)
+        if (library !== -1) onDrawingLibrary(moduleId.slice(0, library + DRAWING_LIBRARY_PATH.length))
+        const file = moduleId.split('?')[0]
+        if (!file.startsWith('/') || file.includes('/node_modules/') || !existsSync(file)) continue
+        if (!file.startsWith(`${sourceDir}/`)) {
+          this.error(`${relative(sourceDir, file)} is outside this extension's folder. Extensions may only use their own files and installed packages.`)
+        }
+      }
+    },
+  }
+}
+
+/** Copies the drawing library's fonts in, when the page uses the library. */
+function copyFonts(libraryRoot, panelDir) {
+  const fontsRoot = join(libraryRoot, 'dist', 'prod', 'fonts')
+  if (!existsSync(fontsRoot)) throw new Error(`Drawing fonts not found at ${fontsRoot}`)
+  for (const family of readdirSync(fontsRoot)) {
+    if (SKIPPED_FONT_FAMILIES.has(family)) continue
+    cpSync(join(fontsRoot, family), join(panelDir, 'fonts', family), { recursive: true })
+  }
+}
+
+/**
+ * Builds the extension in `sourceDir`. With no `outputDir` it builds in place
+ * (into `sourceDir/dist`), ready for "Install from folder". With one, it
+ * writes a complete download there: the built files, the agent guide and a
+ * trimmed `package.json`.
+ */
+export async function buildExtension(sourceDir, { outputDir = null, official = false } = {}) {
+  const root = resolve(sourceDir)
+  const problems = checkExtension(root, { official })
+  if (problems.length > 0) throw new Error(problems.join(' '))
+  const pkg = readPackage(root)
+  const inPlace = outputDir === null || resolve(outputDir) === root
+  const target = inPlace ? root : resolve(outputDir)
+  rmSync(inPlace ? join(root, 'dist') : target, { recursive: true, force: true })
+  mkdirSync(join(target, 'dist'), { recursive: true })
+
+  if (existsSync(join(root, 'index.html'))) {
+    const panelDir = join(target, PANEL_DIR)
+    /** Where the drawing library is installed, once the page is seen to use it. */
+    let drawingLibraryRoot = null
+    await build({
+      configFile: false,
+      root,
+      base: './',
+      logLevel: 'warn',
+      plugins: [react(), stayInsideFolder(root, (libraryRoot) => { drawingLibraryRoot = libraryRoot })],
+      // Tailwind reads the extension's own folder (and the kit, which its theme points at).
+      css: { postcss: { plugins: [tailwindcss({ base: root })] } },
+      build: { outDir: panelDir, emptyOutDir: true, sourcemap: false, chunkSizeWarningLimit: 4096 },
+    })
+    if (drawingLibraryRoot !== null) copyFonts(drawingLibraryRoot, panelDir)
+  }
+
+  // Commands and the background helper each run in a page with no module
+  // loader, so everything is bundled into a single plain script.
+  const scripts = [
+    { source: COMMANDS_SOURCE, name: 'OdynExtension', fileName: 'index.js' },
+    { source: HELPER_SOURCE, name: 'OdynHelper', fileName: 'helper.js' },
+  ]
+  for (const script of scripts.filter(({ source }) => existsSync(join(root, source)))) {
+    await build({
+      configFile: false,
+      root,
+      logLevel: 'warn',
+      plugins: [stayInsideFolder(root, () => undefined)],
+      build: {
+        outDir: join(target, 'dist'),
+        emptyOutDir: false,
+        sourcemap: false,
+        minify: false,
+        lib: { entry: join(root, script.source), formats: ['iife'], name: script.name, fileName: () => script.fileName },
+      },
+    })
+  }
+
+  if (!inPlace) {
+    const skillFolder = pkg.odyn?.agent?.skillFolder
+    if (typeof skillFolder === 'string' && existsSync(join(root, skillFolder))) {
+      cpSync(join(root, skillFolder), join(target, skillFolder), { recursive: true })
+    }
+    const shipped = Object.fromEntries(SHIPPED_PACKAGE_KEYS.filter((key) => key in pkg).map((key) => [key, pkg[key]]))
+    writeFileSync(join(target, 'package.json'), `${JSON.stringify(shipped, null, 2)}\n`)
+  }
+  return { id: pkg.odyn.id, version: pkg.version }
+}

package/cli/github.mjs

@@ -0,0 +1,190 @@
+/**
+ * Talking to GitHub for `odyn-extension publish` and `pull`.
+ *
+ * Publishing never clones the public repo. It copies the repo into the
+ * author's own GitHub account (a fork), writes the extension's files there
+ * as one commit and opens a pull request — all through GitHub's web API.
+ */
+import { execFileSync, spawn } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const UPSTREAM_OWNER = 'New-Genre'
+export const UPSTREAM_REPO = 'odyn-extensions'
+export const UPSTREAM_BRANCH = 'main'
+const API = 'https://api.github.com'
+/**
+ * Odyn's GitHub sign-in app (New-Genre's "Odyn extensions" OAuth app, with
+ * device sign-in switched on). Device sign-in — a short code you type on
+ * github.com — needs no secret, so the id is safe to ship. Empty until the
+ * app exists; until then `gh auth login` or `GITHUB_TOKEN` is used.
+ */
+const ODYN_GITHUB_CLIENT_ID = ''
+const GITHUB_CLIENT_ID = process.env.ODYN_GITHUB_CLIENT_ID?.trim() || ODYN_GITHUB_CLIENT_ID
+const TOKEN_FILE = join(homedir(), '.config', 'odyn-extension', 'github.json')
+const FORK_READY_ATTEMPTS = 20
+const FORK_READY_DELAY_MS = 3000
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms))
+
+/** Opens a web page in the user's browser. Best effort. */
+function openInBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  try {
+    spawn(command, args, { stdio: 'ignore', detached: true }).unref()
+  } catch (error) {
+    console.warn(`Couldn't open the browser (${error instanceof Error ? error.message : String(error)}). Open ${url} yourself.`)
+  }
+}
+
+function readSavedToken() {
+  if (!existsSync(TOKEN_FILE)) return null
+  try {
+    const saved = JSON.parse(readFileSync(TOKEN_FILE, 'utf8'))
+    return typeof saved.token === 'string' && saved.token !== '' ? saved.token : null
+  } catch (error) {
+    console.warn(`Ignoring an unreadable saved sign-in: ${error instanceof Error ? error.message : String(error)}`)
+    return null
+  }
+}
+
+function saveToken(token) {
+  mkdirSync(dirname(TOKEN_FILE), { recursive: true })
+  writeFileSync(TOKEN_FILE, `${JSON.stringify({ token })}\n`, { mode: 0o600 })
+  chmodSync(TOKEN_FILE, 0o600)
+}
+
+/** The GitHub CLI's token, when it is installed and signed in. */
+function ghCliToken() {
+  try {
+    const token = execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    return token === '' ? null : token
+  } catch {
+    return null
+  }
+}
+
+/** Signs in through the browser: shows a short code, the user approves it on github.com. */
+async function deviceSignIn() {
+  if (GITHUB_CLIENT_ID === '') {
+    throw new Error('Sign in to GitHub first: install the GitHub CLI and run `gh auth login`, or set GITHUB_TOKEN.')
+  }
+  const start = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, scope: 'public_repo' }),
+  })
+  const code = await start.json()
+  if (!start.ok || typeof code.device_code !== 'string') {
+    throw new Error(`GitHub sign-in couldn't start: ${code.error_description ?? code.error ?? start.status}`)
+  }
+  console.log(`\nSign in to GitHub: enter the code ${code.user_code} at ${code.verification_uri}`)
+  openInBrowser(code.verification_uri)
+  let interval = (code.interval ?? 5) * 1000
+  const deadline = Date.now() + (code.expires_in ?? 900) * 1000
+  while (Date.now() < deadline) {
+    await sleep(interval)
+    const poll = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, device_code: code.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+    })
+    const result = await poll.json()
+    if (typeof result.access_token === 'string') return result.access_token
+    if (result.error === 'slow_down') interval += 5000
+    else if (result.error !== 'authorization_pending') throw new Error(`GitHub sign-in failed: ${result.error_description ?? result.error}`)
+  }
+  throw new Error('GitHub sign-in timed out. Run the command again.')
+}
+
+/**
+ * A GitHub token: `GITHUB_TOKEN`, then a saved sign-in, then the GitHub CLI,
+ * and finally a fresh sign-in through the browser.
+ */
+export async function getToken() {
+  const fromEnv = process.env.GITHUB_TOKEN?.trim()
+  if (fromEnv) return fromEnv
+  const saved = readSavedToken()
+  if (saved) return saved
+  const fromCli = ghCliToken()
+  if (fromCli) return fromCli
+  const fresh = await deviceSignIn()
+  saveToken(fresh)
+  return fresh
+}
+
+/** Forgets the saved sign-in, e.g. after GitHub rejects it. */
+export function forgetToken() {
+  if (existsSync(TOKEN_FILE)) writeFileSync(TOKEN_FILE, '{}\n', { mode: 0o600 })
+}
+
+/** A small GitHub API client. Throws a readable error on any failure. */
+export function githubClient(token) {
+  return async function request(method, path, body) {
+    const response = await fetch(`${API}${path}`, {
+      method,
+      headers: {
+        accept: 'application/vnd.github+json',
+        'x-github-api-version': '2022-11-28',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    if (response.status === 204) return null
+    const text = await response.text()
+    const data = text === '' ? null : JSON.parse(text)
+    if (!response.ok) {
+      const error = new Error(`GitHub said ${response.status} for ${method} ${path}: ${data?.message ?? text}`)
+      error.status = response.status
+      throw error
+    }
+    return data
+  }
+}
+
+/** Every file in the public repo's extension folder, as `{ path, sha }` relative to it. */
+export async function upstreamFiles(request, extensionId) {
+  const branch = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/branches/${UPSTREAM_BRANCH}`)
+  const tree = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/git/trees/${branch.commit.sha}?recursive=1`)
+  const prefix = `extensions/${extensionId}/`
+  const files = tree.tree
+    .filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix))
+    .map((entry) => ({ path: entry.path.slice(prefix.length), sha: entry.sha }))
+  return { commitSha: branch.commit.sha, treeSha: branch.commit.commit.tree.sha, files }
+}
+
+/** Makes sure the user has their own copy of the public repo, up to date. Returns its owner. */
+export async function ensureFork(request, login) {
+  try {
+    await request('GET', `/repos/${login}/${UPSTREAM_REPO}`)
+  } catch (error) {
+    if (error.status !== 404) throw error
+    console.log(`Making your copy of ${UPSTREAM_OWNER}/${UPSTREAM_REPO} on GitHub…`)
+    await request('POST', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/forks`, { default_branch_only: true })
+    for (let attempt = 0; attempt < FORK_READY_ATTEMPTS; attempt += 1) {
+      await sleep(FORK_READY_DELAY_MS)
+      try {
+        await request('GET', `/repos/${login}/${UPSTREAM_REPO}/branches/${UPSTREAM_BRANCH}`)
+        return login
+      } catch (pollError) {
+        if (pollError.status !== 404 && pollError.status !== 409) throw pollError
+      }
+    }
+    throw new Error('GitHub is still making your copy of the repo. Try again in a minute.')
+  }
+  await request('POST', `/repos/${login}/${UPSTREAM_REPO}/merge-upstream`, { branch: UPSTREAM_BRANCH }).catch((error) => {
+    console.warn(`Couldn't bring your copy up to date first (${error.message}). Carrying on.`)
+  })
+  return login
+}
+
+/** Downloads one file of the public repo's main branch. */
+export async function downloadUpstreamFile(path) {
+  const url = `https://raw.githubusercontent.com/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/${UPSTREAM_BRANCH}/${path.split('/').map(encodeURIComponent).join('/')}`
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`Couldn't download ${path} (${response.status}).`)
+  return Buffer.from(await response.arrayBuffer())
+}

package/cli/odyn-extension.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * odyn-extension — make, test and publish Odyn extensions.
+ *
+ *   odyn-extension create <name>   start a new extension in a new folder
+ *   odyn-extension dev             build, then rebuild on every save (Odyn reloads it)
+ *   odyn-extension build           build once into dist/
+ *   odyn-extension check           check the manifest
+ *   odyn-extension pull <id>       download a published extension's source to work on it
+ *   odyn-extension publish         send this extension to the Marketplace as a pull request
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { userInfo } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { buildExtension, checkExtension, readPackage } from './build.mjs'
+import {
+  UPSTREAM_BRANCH,
+  UPSTREAM_OWNER,
+  UPSTREAM_REPO,
+  downloadUpstreamFile,
+  ensureFork,
+  forgetToken,
+  getToken,
+  githubClient,
+  upstreamFiles,
+} from './github.mjs'
+import { starterFiles } from '../dist/index.js'
+
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const KIT_VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf8')).version
+/** Saves that land within this window become one rebuild. */
+const REBUILD_DELAY_MS = 150
+/** Never sent to the public repo: installed packages, build output, local clutter. */
+const UNPUBLISHED = new Set(['node_modules', 'dist', 'build', '.git', '.DS_Store', 'bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'])
+/** A single file bigger than this is refused; the download as a whole is capped by the repo. */
+const MAX_PUBLISHED_FILE_BYTES = 5 * 1024 * 1024
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const USAGE = `odyn-extension — make, test and publish Odyn extensions
+
+  create <name>   start a new extension in a new folder
+  dev             build, then rebuild on every save (Odyn reloads it)
+  build           build once into dist/
+  check           check the manifest
+  pull <id>       download a published extension's source to work on it
+  publish         send this extension to the Marketplace as a pull request
+
+Docs: https://www.odyn.build/docs/extensions`
+
+/** "Standup notes!" → "standup-notes". */
+function toId(name) {
+  return name.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+/** The user's name from git, or their login name. */
+function authorName() {
+  try {
+    const name = execFileSync('git', ['config', 'user.name'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (name !== '') return name
+  } catch {
+    // No git, or no name set — fall back below.
+  }
+  return userInfo().username
+}
+
+function writeFiles(folder, files) {
+  for (const [path, content] of Object.entries(files)) {
+    const target = join(folder, path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, content)
+  }
+}
+
+function create(args) {
+  const name = args.join(' ').trim()
+  if (name === '') throw new Error('Give the extension a name, e.g. `odyn-extension create "Standup notes"`.')
+  const id = toId(name)
+  if (!ID_PATTERN.test(id)) throw new Error(`"${name}" needs at least one letter or digit.`)
+  const folder = resolve(id)
+  if (existsSync(folder) && readdirSync(folder).length > 0) throw new Error(`${folder} already exists and isn't empty.`)
+  const title = name === id ? name.replace(/-/g, ' ').replace(/^./, (letter) => letter.toUpperCase()) : name
+  writeFiles(folder, starterFiles({ id, title, author: authorName(), kitVersion: `^${KIT_VERSION}` }))
+  console.log(`Made ${relative(process.cwd(), folder) || '.'}/
+
+Next:
+  cd ${id}
+  bun install
+  bun run dev
+
+Then in Odyn: Marketplace → Extensions → Install from folder, and pick the folder.`)
+}
+
+/** The extension folder the command was run in. */
+function currentExtension() {
+  const folder = process.cwd()
+  if (!existsSync(join(folder, 'package.json'))) throw new Error('Run this inside an extension folder (one with a package.json).')
+  return folder
+}
+
+async function buildOnce(folder) {
+  const started = Date.now()
+  const { id, version } = await buildExtension(folder)
+  console.log(`Built ${id} ${version} in ${Date.now() - started} ms`)
+}
+
+async function dev() {
+  const folder = currentExtension()
+  await buildOnce(folder)
+  console.log('Watching for changes. Odyn reloads the extension after each build. Press Ctrl+C to stop.')
+  let timer = null
+  let building = false
+  let again = false
+  const rebuild = async () => {
+    if (building) {
+      again = true
+      return
+    }
+    building = true
+    try {
+      await buildOnce(folder)
+    } catch (error) {
+      console.error(`Build failed: ${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      building = false
+      if (again) {
+        again = false
+        void rebuild()
+      }
+    }
+  }
+  watch(folder, { recursive: true }, (_event, file) => {
+    if (typeof file !== 'string') return
+    const top = file.split(sep)[0]
+    if (UNPUBLISHED.has(top)) return
+    if (timer !== null) clearTimeout(timer)
+    timer = setTimeout(() => { timer = null; void rebuild() }, REBUILD_DELAY_MS)
+  })
+}
+
+function check() {
+  const problems = checkExtension(currentExtension())
+  if (problems.length > 0) throw new Error(problems.join('\n'))
+  console.log('The manifest looks good.')
+}
+
+async function pull(args) {
+  const id = args[0]
+  if (!id || !ID_PATTERN.test(id)) throw new Error('Give the extension id, e.g. `odyn-extension pull standup-notes`.')
+  const folder = resolve(id)
+  if (existsSync(folder) && readdirSync(folder).length > 0) throw new Error(`${folder} already exists and isn't empty.`)
+  const request = githubClient(process.env.GITHUB_TOKEN?.trim() || null)
+  const { files } = await upstreamFiles(request, id)
+  if (files.length === 0) throw new Error(`There's no extension called "${id}" in ${UPSTREAM_OWNER}/${UPSTREAM_REPO}.`)
+  for (const file of files) {
+    const target = join(folder, file.path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, await downloadUpstreamFile(`extensions/${id}/${file.path}`))
+  }
+  // Extensions in the repo share its tools; on its own the folder needs the kit
+  // and the usual shortcuts.
+  const pkg = readPackage(folder)
+  const starter = JSON.parse(starterFiles({ id, title: id, author: '', kitVersion: `^${KIT_VERSION}` })['package.json'])
+  pkg.scripts = { ...starter.scripts, ...pkg.scripts }
+  pkg.dependencies = { ...starter.dependencies, ...pkg.dependencies }
+  writeFileSync(join(folder, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+  console.log(`Downloaded ${files.length} files into ${id}/
+
+Next:
+  cd ${id}
+  bun install
+  bun run dev
+
+When you're done, \`bun run publish\` sends your changes for review.`)
+}
+
+/** Every file to publish, relative to the folder, skipping installed packages and build output. */
+function publishableFiles(folder) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (UNPUBLISHED.has(entry.name)) continue
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (entry.isFile()) files.push(relative(folder, path).split(sep).join('/'))
+    }
+  }
+  walk(folder)
+  return files.sort()
+}
+
+async function publish() {
+  const folder = currentExtension()
+  const problems = checkExtension(folder)
+  if (problems.length > 0) throw new Error(`Fix these before publishing:\n${problems.join('\n')}`)
+  // Building first catches mistakes before anyone has to review them.
+  await buildOnce(folder)
+
+  let token = await getToken()
+  let request = githubClient(token)
+  let user
+  try {
+    user = await request('GET', '/user')
+  } catch (error) {
+    if (error.status !== 401) throw error
+    forgetToken()
+    token = await getToken()
+    request = githubClient(token)
+    user = await request('GET', '/user')
+  }
+  const login = user.login
+
+  // The person publishing looks after the extension, unless someone already does.
+  const pkg = readPackage(folder)
+  const id = pkg.odyn.id
+  const upstream = await upstreamFiles(request, id)
+  const isNew = upstream.files.length === 0
+  if (!Array.isArray(pkg.odyn.owners) || pkg.odyn.owners.length === 0) {
+    pkg.odyn.owners = [login]
+    writeFileSync(join(folder, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+    console.log(`Added you (${login}) as the owner in package.json.`)
+  }
+
+  const fork = await ensureFork(request, login)
+  const local = publishableFiles(folder)
+  for (const path of local) {
+    if (statSync(join(folder, path)).size > MAX_PUBLISHED_FILE_BYTES) throw new Error(`${path} is over 5 MB. Leave large files out.`)
+  }
+  const prefix = `extensions/${id}/`
+  const entries = []
+  for (const path of local) {
+    const blob = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/blobs`, {
+      content: readFileSync(join(folder, path)).toString('base64'),
+      encoding: 'base64',
+    })
+    entries.push({ path: `${prefix}${path}`, mode: '100644', type: 'blob', sha: blob.sha })
+  }
+  // Files that were published before but are gone now are removed.
+  const kept = new Set(local)
+  for (const file of upstream.files) {
+    if (!kept.has(file.path)) entries.push({ path: `${prefix}${file.path}`, mode: '100644', type: 'blob', sha: null })
+  }
+  const tree = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/trees`, { base_tree: upstream.treeSha, tree: entries })
+  if (tree.sha === upstream.treeSha) {
+    console.log('Nothing has changed since the published version.')
+    return
+  }
+  const version = pkg.version
+  const message = isNew ? `Add ${pkg.odyn.title} ${version}` : `Update ${pkg.odyn.title} to ${version}`
+  const commit = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/commits`, { message, tree: tree.sha, parents: [upstream.commitSha] })
+  const branch = `extension/${id}`
+  try {
+    await request('PATCH', `/repos/${fork}/${UPSTREAM_REPO}/git/refs/heads/${branch}`, { sha: commit.sha, force: true })
+  } catch (error) {
+    if (error.status !== 404 && error.status !== 422) throw error
+    await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha })
+  }
+
+  const open = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/pulls?state=open&head=${encodeURIComponent(`${fork}:${branch}`)}`)
+  if (open.length > 0) {
+    console.log(`Updated your pull request: ${open[0].html_url}`)
+    return
+  }
+  const body = [
+    isNew ? `Adds **${pkg.odyn.title}** (\`${id}\`) ${version}.` : `Updates **${pkg.odyn.title}** (\`${id}\`) to ${version}.`,
+    '',
+    pkg.odyn.description,
+    '',
+    `Permissions: ${pkg.odyn.permissions.length === 0 ? 'none' : pkg.odyn.permissions.map((permission) => `\`${permission}\``).join(', ')}`,
+    '',
+    `Published with \`odyn-extension publish\` (kit ${KIT_VERSION}).`,
+  ].join('\n')
+  const pr = await request('POST', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/pulls`, {
+    title: message,
+    head: `${fork}:${branch}`,
+    base: UPSTREAM_BRANCH,
+    body,
+    maintainer_can_modify: true,
+  })
+  console.log(`Opened a pull request: ${pr.html_url}
+Once it's reviewed and merged, ${pkg.odyn.title} appears in Odyn's Marketplace.
+To change it later, edit this folder and run \`bun run publish\` again.`)
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2)
+  switch (command) {
+    case 'create': return create(args)
+    case 'dev': return dev()
+    case 'build': return buildOnce(currentExtension())
+    case 'check': return check()
+    case 'pull': return pull(args)
+    case 'publish': return publish()
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(USAGE)
+      return undefined
+    default:
+      throw new Error(`Unknown command "${command}".\n\n${USAGE}`)
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})
+