Extensions

An extension adds something to the studio: menu entries, an editor for a file type, workspace templates, a bundled tool, or an AI provider.

Managing them

Extensions -> Manage extensions... opens the browser. The list on the left is what the registry at tucan.amlang.net offers, plus anything already installed. Click an entry to see its details on the right.

The detail pane shows the description, the id, which platforms it supports, the permissions it asks for, and -- for registry extensions -- a version picker. The button underneath says what it will do:

• Install -- not installed yet
• Update to <version> -- a different version is selected
• Installed (greyed) -- the selected version is the one you have

Uninstall appears only for something actually installed.

Picking an older version in the dropdown and installing gives you that version; the studio fetches that release's file list rather than the latest one.

What ships where

Extensions install into extensions/<id>/ next to the studio binary. A released package deliberately ships no extensions -- you install what you want -- so a fresh install starts with an empty list and fills it from the registry.

Archives are .lha on AmigaOS and MorphOS and .zip elsewhere, which is why installing needs no extra archiver on any platform.

Permissions

An extension declares what it needs -- running commands, reading or writing the workspace, network access -- and the studio shows that in the detail pane before you install. A script that calls something it did not declare is refused at the point of the call, not silently allowed.

Writing one

Everything for building an extension lives in the Extension DevTools extension, under Extensions once it is installed:

• Create new extension -- scaffolds a folder with a manifest and an example script, and opens it as your workspace
• Manage extension -- edits the manifest of the extension open in the workspace
• Build -- assembles dist/, described below
• My extensions -- what you have published to the registry

The full reference is docs/EXTENSIONS.md, which is copied into every scaffolded extension so it sits next to what you are editing.

The short version: extension.json is the identity (id, name, description) and declares what the extension contributes; version.json is one release (files, permissions, path entries). Scripts are JavaScript with a studio.* bridge for the filesystem, the CLI, HTTP, forms, and AI provider registration.

The folder layout

What an extension ships is decided by where its files sit, not by a list kept somewhere:

my-extension/
  extension.json        the manifest
  shared/               everything platform-independent
  platforms/
    amigaos/            files only AmigaOS gets
    morphos-ppc/
    macos-arm/
  dist/                 produced by Build -- what actually runs

shared/ is for scripts, forms, icons, data: anything that is the same everywhere. platforms/<id>/ is for what is not, which in practice means executables.

What Build does

Build copies the contents of shared/ into dist/, then the contents of platforms/<platform>/ on top, then the manifest. The contents, not the folders themselves: shared/js/app.js becomes dist/js/app.js, and platforms/amigaos/bin/tool becomes dist/bin/tool. Both trees therefore merge into one drawer, which is the drawer a user ends up with.

Platform files are copied second, so where both define the same path the platform's file wins. That is how a shared default gets replaced by a real binary on the platforms that have one.

Which platform it builds for comes from the platforms list on the Platforms tab:

• none listed -- shared/ is all there is, and Build just uses it
• one listed -- that one, no questions
• several -- a window asks which

Once dist/ exists the studio runs your workspace extension from there rather than from the folder you are editing. Menu items then exercise exactly what a user would get, binaries included. The flip side is that an edit does not take effect until you build again.

Build overwrites and never deletes. A file you removed from shared/ stays in dist/ until you clear it out yourself.

A freshly scaffolded extension starts flat, with its manifest and script at the root, and the studio runs it from there. Move the files into shared/ before your first build -- Build looks nowhere else, and on a flat folder it reports that there is nothing to build.

The Manage extension tabs

Info carries what the registry is told -- name, description -- and the permissions, one checkbox each. It is also where you register the extension with the registry. Once it is registered the button becomes Publish new version, which at this stage prints the steps it would take rather than uploading anything.

Platforms is the list above. + adds an id and creates platforms/<id>/ for you. - removes the entry from the manifest and leaves the folder and its files untouched, so nothing you built is ever thrown away by a list edit.

Paths takes one folder per line, relative to the extension root. Those go on the shell path when the extension is installed, which is how a bundled tool becomes runnable by name in the CLI. bin is the usual entry.