φ extensions

Official extensions for φ. One repo, one folder per extension, each with its own version and changelog — kept together for convenience, not released together.

Local for now. No git remote yet; that's a decision still to be made. Everything here is laid out the way the eventual repo will be, so adopting it is git init and nothing else.

What belongs here

Extensions φ ships as first-party. They are not bundled into the app — each builds to a zip and installs through Settings → Extensions like anything third-party, and shows the same consent card. That's deliberate: if a first-party extension needed a special path, the extension platform wouldn't be real yet.

An extension is not one shape. It can contribute a block (something new on the writing surface), a panel (a tool beside it), a command, an export format, or a connector (linking φ to another service). Those differ in how they run and whether they run at all, which is why every catalogue entry carries kinds — see below. A block-only extension runs no code whatsoever and is as safe to install as a theme; a connector needs a code host φ does not yet provide.

Extension	What it does
tasks	Every unfinished task from every document, in one place

Ground rules

Self-contained. Nothing here may import from the φ checkout or reach into it with a relative path. Each extension has its own build, its own dependencies, and its own copy of anything it needs from φ's tooling (see scripts/). Test it by building with the φ checkout absent — if that fails, the coupling is real.

The only contract with the app is the poiesis.* panel API and the engines.poiesis range in the manifest. Keep that range accurate: your machine always has the newest API, so a stale range won't fail locally — it fails for someone on an older build.

One self-contained HTML file per panel. φ serves a panel over poiesis-panel:// with no route for sibling assets, and the CSP is default-src 'none' — so no <script src>, no stylesheet link, no CDN, no web fonts. Inline everything at build time.

Translated from the start. φ ships English, Spanish and French. A panel can't reach φ's translations, so it carries its own and reads ui.getLocale(). No user-visible string is hard-coded, and dates and plurals go through Intl — not string concatenation, which breaks the moment a language has different plural rules.

No "Poiesis" in user-facing text. The app is branded φ. Code identifiers, file paths and the .poiesis format keep the poiesis name.

Adding an extension

extensions/<name>/
  extension.json     manifest — id, contributions, permissions
  package.json       own version + build scripts
  CHANGELOG.md       own, independent of φ's
  build.mjs          bundles to one dist/panel.html
  src/

cd extensions/<name>
npm install
npm run build      # → dist/panel.html
npm run package    # → dist/<name>.zip, ready to install

During development, macOS lets you install the source folder directly from Settings → Extensions, so there's no need to re-zip on every change. Panels reload when reopened; editor blocks need a relaunch, since the schema is built once at startup.

The library (registry.json)

φ browses this repo through registry.json at the root — the same shape the official theme library uses, adapted for packages rather than data.

{
  "version": 1,
  "extensions": [
    {
      "id": "phi.tasks",              // must match the package's own manifest id
      "name": "Tasks",
      "version": "0.1.0",
      "author": "φ",
      "description": "…",             // one line, shown in the gallery
      "packageUrl": "https://github.com/getpoiesis/extensions/releases/download/tasks-v0.1.0/phi-tasks.zip",
      "sha256": "…",                  // of the package bytes; no checksum, no listing
      "size": 38391,
      "kinds": ["panel"],           // block | panel | command | exporter | connector
      "permissions": [ … ],           // previewed before anything is downloaded
      "engines": "^1.0.0",
      "homepage": "https://github.com/getpoiesis/extensions/tree/main/extensions/tasks"
    }
  ]
}

Being listed makes an extension findable, not trusted. A theme can be sanitized into safety — it is data, reduced to a known id and safe colour values. A package can carry code and cannot be reduced that way. So three independent things have to hold before anything is installed:

1. packageUrl is inside this repo — a raw file or a release asset. A tampered or redirected listing cannot point φ at another host.
2. The downloaded bytes hash to the declared sha256. A mismatch is discarded, not retried.
3. The package then goes through the ordinary install path — manifest validation and the permission consent card — exactly as a file picked from disk would. The gallery never grants anything; the user still approves.

The permissions in the entry are a preview so the gallery can say what an extension will ask for before downloading it. They are sanitized with the same function the manifest uses, so the preview and the consent card cannot disagree.

kinds says what the extension contributes, derived from the package's own contributes so a listing can't claim something the package doesn't provide. The gallery groups by it and uses it to say when this build can't run an entry — better than offering an install that silently does nothing. What runs where is documented once, in φ's docs/extending/extensions.md.

Publishing a new version

1. Bump version in the extension's extension.json and its CHANGELOG.md.
2. npm run package in the extension folder.
3. Attach the zip to a release tagged <name>-v<version>.
4. Update the entry in registry.json — version, packageUrl, sha256, size. Regenerate the checksum with shasum -a 256 dist/<name>.zip.

φ refreshes the library shortly after launch and every six hours, caching it locally so the gallery opens instantly and works offline.

License

MIT — see LICENSE. That covers the extensions in this repo and the tooling around them; φ itself is licensed separately.