@ynput/ayon-addon-dev 0.1.0 → 0.2.0

package/AGENTS.md

@@ -28,7 +28,7 @@ Run in the addon's frontend folder. Every command takes `--json` for scripts and
 | Command | What |
 |---|---|
 | `ayon-addon dev [--port 5174]` | The dev shell (below): the addon in AYON's surfaces, without AYON, with hot reload |
-| `ayon-addon dev --ayon [--port 5173]` | Builds on every change and serves the build with CORS. Prints the AYON URL that loads it: `<server>/?addonDev=<addon>@http://localhost:5173` |
+| `ayon-addon dev --ayon [--port 5173] [--open] [--frontend <url>]` | Builds on every change and serves the build with CORS. Checks what AYON's dev override needs on the server, then prints (`--open`: opens) the AYON URL that loads it: `<server>/?addonDev=<addon>@http://localhost:5173` |
 | `ayon-addon slots` | The slots of the installed `@ynput/ayon-addon`: helper, where, when the code loads |
 | `ayon-addon check [--no-types]` | The manifest as AYON reads it (slots, ids, fields, pieces), that each piece's file exists, and `tsc` |
 | `ayon-addon open <slot> <id> [--project P] [--entities type:id,...] [--page overview\|products\|lists] [--run] [--screenshot file] [--save-fixture name]` | One contribution in the dev shell in a headless browser, against the server. Reports error boxes, console errors, toasts, the context it got, the clipboard after `--run` (menu items). Exit code 1 when it failed |
@@ -41,13 +41,57 @@ chromium`); in the AYON dev workbench the ayon-frontend checkout's copy is used.
 
 ## Developing inside AYON (`dev --ayon`)
 
-1. `ayon-addon dev --ayon` in the addon.
-2. Open the URL it prints. The page loads your addon from the dev server instead of the installed
-   version (also when it isn't installed) and shows a banner. It reloads after every rebuild.
+1. `ayon-addon dev --ayon --open` in the addon (`yarn dev:ayon` in the template and the time tracker).
+2. It checks the server, builds, and opens the URL it prints (without `--open`, open it yourself).
+   The page loads your addon from the dev server instead of the installed version (also when it
+   isn't installed) and shows a banner. It reloads after every rebuild.
 3. `?addonDev=off`, or the banner's close button, goes back to the installed addon.
 
-Only users in developer mode (and service users, for agents) can do this, and only from
-`localhost`.
+- `--frontend http://localhost:3000` puts that page in the URL instead of the server (an
+  ayon-frontend dev server in front of it).
+- `--port` is the addon's dev server port (5173 by default; a port in use stops it with an error).
+- With `--json` it prints one object once the first build is done: `url`, `addon`, `remote`,
+  `buildId`, `open` (the URL), `ok` (no check failed with `error`) and `checks`
+  (`{ id, ok, severity, message, fix }`).
+
+What it checks against the server (`AYON_SERVER_URL` / `AYON_API_KEY`, or the workbench's local
+stack and key), each failure with how to fix it:
+
+| Check | Fails when |
+|---|---|
+| `server` | `/api/info` doesn't answer 200. Nothing else is checked. |
+| `apiKey` | No key: the user and the installed versions can't be checked (warning). |
+| `user` | The key is rejected (error), or the key's user is neither a service user nor in developer mode (warning: a headless browser signed in with it ignores the override). Your own browser user is not known to the CLI: it needs developer mode. |
+| `addonVersion` | The `versionModule` (`src/addonVersion.ts` unless `ayonAddon({ rest })` names another) and `package.py` name different versions (warning): the frontend calls the endpoints of the former. |
+| `addon` | The addon isn't installed in the version the frontend calls, or that version failed to load on the server. The page still loads the frontend from the dev server, but its endpoint calls (`/api/addons/<name>/<version>/...`) answer 404. An error when the addon has a `server/` folder, else a warning. |
+
+The checks never stop the dev server: fix them while it runs.
+
+### Why isn't my addon loading?
+
+The page always says why in the banner at the bottom left (also in the console). What it says, and
+the fix:
+
+- **ignored ... only users in developer mode**: turn on Developer Mode in AYON's header (a user
+  who doesn't have the switch needs Developer turned on by an admin in Studio settings > Users),
+  then reload. Service users (API keys) always may.
+- **ignored ... is not this machine / is not a URL / use ?addonDev=...**: the parameter must be
+  `<addon>@http://localhost:<port>` (or `127.0.0.1`, `[::1]`): a link can't load code from another
+  machine.
+- **could not load ... no answer from**: the dev server isn't running on that port (or was
+  stopped). The page reloads once it answers.
+- **could not load ... has no /ayon-addon.json**: something else runs on that port (the dev shell,
+  `ayon-addon dev` without `--ayon`), or the first build hasn't finished. The page reloads once it
+  answers.
+- **could not load ... serves "x", not "y"**: the name in the URL isn't the addon's name in
+  `package.py`; use the URL the CLI prints.
+- **its manifest failed to load**: the build is broken or the remote didn't start: see the
+  console and the CLI's output; the page reloads after the next build.
+- **The addon loads but its requests answer 404**: the server doesn't have the addon in the
+  version the frontend calls. `ayon-addon dev --ayon` reports it (`addon` check); install that
+  version.
+- **No banner at all**: the page isn't a frontend with the dev override (an older AYON), or
+  `?addonDev=off` cleared it.
 
 ## Developing without AYON: the dev shell (`dev`, the default)
 
@@ -125,6 +169,13 @@ queries), `generated`, `api`, `versionModule`, `schema` (paths).
   workbench the tools find the local stack and its key (`data/local-api-key`) on their own.
 - `AYON_SERVER_URL` points the tools at another server (default `http://localhost:5000`, or the
   workbench's local stack).
+- Both can go in the addon frontend's `.env.local` or `.env` (keep them out of git): every
+  command loads them at start, `.env.local` first. Variables already set in the shell win.
+- With no key, a command stops and says where to get one (Settings → Users → Add Service User).
+  In a terminal, with no env file yet, it walks through writing `.env`: the server (default
+  `http://localhost:5000`), then the key, typed without echo (Enter leaves it for later). A key
+  given there lets the command go on; without one it stops after writing the file. The file
+  comes from `envFileContents` in `addon-dev/src/project.ts`.
 
 ## Lint preset
 

package/dist/browse.js

@@ -5,7 +5,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { createRequire } from 'module';
 import path from 'path';
 import { pathToFileURL } from 'url';
-import { findConnection, importFromProject } from './project.js';
+import { findConnection, importFromProject, keySetupMessage } from './project.js';
 import { STANDALONE_ENV } from './standalone.js';
 // the addon's playwright, else the one next to this package (the ayon-frontend checkout)
 const loadPlaywright = async (root) => {
@@ -38,7 +38,7 @@ const startServer = async (root) => {
 export const browse = async (options) => {
     const mode = options.fixture ? 'preview' : 'live';
     if (mode === 'live' && !options.url && !findConnection(options.root).apiKey) {
-        throw new Error('no API key for the headless browser: set AYON_API_KEY (and AYON_SERVER_URL)');
+        throw new Error(keySetupMessage(options.root));
     }
     const server = options.url ? undefined : await startServer(options.root);
     const base = options.url || server.resolvedUrls.local[0];

package/dist/cli.js

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 // ayon-addon: dev server and checks for AYON addon frontends. Every command prints JSON with --json.
 //   ayon-addon dev [--port 5174]     the dev shell: the addon in AYON's surfaces, hot reload
-//   ayon-addon dev --ayon [--port 5173]   watched build + server for AYON's dev override (?addonDev=)
+//   ayon-addon dev --ayon [--port 5173] [--open] [--frontend <url>]   watched build + server for
+//                                    AYON's dev override (?addonDev=), checks what it needs on the server
 //   ayon-addon slots [--json]        the slots of the installed @ynput/ayon-addon
 //   ayon-addon check [--json] [--no-types]
 //   ayon-addon open <slot> <id>      the dev shell in a headless browser (live server)
 //   ayon-addon preview <slot> <id> --fixture <name>   the same from a fixture, no server
 //   ayon-addon generate-rest         the addon's server endpoints as RTK Query endpoints
+import { spawn } from 'child_process';
 import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { createServer } from 'http';
 import path from 'path';
 import { browse, formatBrowse } from './browse.js';
 import { checkAddon, formatCheck } from './check.js';
-import { findConnection, findPackageDir, importFromProject, readAddonProject } from './project.js';
+import { checkDevRequirements, formatChecks } from './devChecks.js';
+import { findConnection, findPackageDir, importFromProject, loadProjectEnv, readAddonProject, } from './project.js';
 import { generateRest } from './rest.js';
 import { STANDALONE_ENV } from './standalone.js';
 const argv = process.argv.slice(2);
@@ -25,6 +28,7 @@ const option = (name, fallback) => {
 const json = flag('json');
 const print = (value, text) => console.log(json ? JSON.stringify(value, null, 2) : text);
 const root = process.cwd();
+loadProjectEnv(root);
 const CONTENT_TYPES = {
     '.js': 'text/javascript',
     '.mjs': 'text/javascript',
@@ -36,26 +40,45 @@ const CONTENT_TYPES = {
     '.png': 'image/png',
     '.woff2': 'font/woff2',
 };
-// serves the build with CORS: AYON (any origin, also https) loads the remote from here
-const serveDirectory = (dir, port) => createServer((request, response) => {
-    response.setHeader('Access-Control-Allow-Origin', '*');
-    // agents' headless browsers send x-api-key on every request, which makes these preflighted
-    response.setHeader('Access-Control-Allow-Headers', '*');
-    response.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
-    response.setHeader('Access-Control-Allow-Private-Network', 'true');
-    response.setHeader('Cache-Control', 'no-store');
-    if (request.method === 'OPTIONS')
-        return void response.writeHead(204).end();
-    const urlPath = decodeURIComponent((request.url || '/').split('?')[0]);
-    const file = path.join(dir, path.normalize(urlPath).replace(/^(\.\.[/\\])+/, ''));
-    if (!file.startsWith(dir) || !existsSync(file) || !statSync(file).isFile()) {
-        return void response.writeHead(404).end('not found');
-    }
-    response.writeHead(200, {
-        'Content-Type': CONTENT_TYPES[path.extname(file)] || 'application/octet-stream',
+// serves the build with CORS: AYON (any origin, also https) loads the remote from here. `dir()` is
+// undefined until the first build: 404 until then, which the page shows and waits out.
+const serveDirectory = (dir, port) => new Promise((resolve, reject) => {
+    const server = createServer((request, response) => {
+        response.setHeader('Access-Control-Allow-Origin', '*');
+        // agents' headless browsers send x-api-key on every request, which makes these preflighted
+        response.setHeader('Access-Control-Allow-Headers', '*');
+        response.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        response.setHeader('Access-Control-Allow-Private-Network', 'true');
+        response.setHeader('Cache-Control', 'no-store');
+        if (request.method === 'OPTIONS')
+            return void response.writeHead(204).end();
+        const root = dir();
+        const urlPath = decodeURIComponent((request.url || '/').split('?')[0]);
+        const file = root && path.join(root, path.normalize(urlPath).replace(/^(\.\.[/\\])+/, ''));
+        if (!root || !file || !file.startsWith(root) || !existsSync(file) || !statSync(file).isFile()) {
+            return void response.writeHead(404).end('not found');
+        }
+        response.writeHead(200, {
+            'Content-Type': CONTENT_TYPES[path.extname(file)] || 'application/octet-stream',
+        });
+        createReadStream(file).pipe(response);
     });
-    createReadStream(file).pipe(response);
-}).listen(port);
+    server.once('error', (error) => reject(error.code === 'EADDRINUSE'
+        ? new Error(`port ${port} is in use (another \`ayon-addon dev\`?): pick another with --port`)
+        : error));
+    server.listen(port, () => resolve(server));
+});
+// the system's browser
+const openInBrowser = (url) => {
+    const [cmd, ...args] = process.platform === 'darwin'
+        ? ['open', url]
+        : process.platform === 'win32'
+            ? ['cmd', '/c', 'start', '""', url]
+            : ['xdg-open', url];
+    spawn(cmd, args, { stdio: 'ignore', detached: true })
+        .on('error', () => console.error(`could not open a browser: open ${url} yourself`))
+        .unref();
+};
 // the build's dev info (dist/modules/<remote>/ayon-addon.json), written by ayonAddon()
 const findDevInfo = () => {
     const modules = path.join(root, 'dist', 'modules');
@@ -64,7 +87,7 @@ const findDevInfo = () => {
     const file = readdirSync(modules)
         .map((name) => path.join(modules, name, 'ayon-addon.json'))
         .find((candidate) => existsSync(candidate));
-    return file && { dir: path.dirname(file), info: JSON.parse(readFileSync(file, 'utf8')) };
+    return file ? { dir: path.dirname(file), info: JSON.parse(readFileSync(file, 'utf8')) } : undefined;
 };
 // the Vite dev server with the dev shell (ayonAddon()'s standalone plugin)
 const devStandalone = async () => {
@@ -90,21 +113,35 @@ const dev = async () => {
         return devStandalone();
     const port = Number(option('port', '5173'));
     const project = readAddonProject(root);
+    const connection = findConnection(root);
     const vite = await importFromProject(root, 'vite');
+    let built;
+    // listening before the build: a page opened early waits for it instead of failing to connect
+    const server = await serveDirectory(() => built?.dir, port);
+    // what the override needs on the server, checked while the first build runs
+    const versionModule = (await readRestOptions().catch(() => ({}))).versionModule;
+    const checks = checkDevRequirements({ project, connection, versionModule });
     process.env.AYON_ADDON_DEV = '1';
     let served = false;
-    const watcher = (await vite.build({
-        root,
-        mode: 'development',
-        build: { watch: {} },
-        logLevel: 'warn',
-    }));
+    let watcher;
+    try {
+        watcher = (await vite.build({
+            root,
+            mode: 'development',
+            build: { watch: {} },
+            logLevel: 'warn',
+        }));
+    }
+    catch (error) {
+        server.close();
+        throw error;
+    }
     watcher.on('event', (event) => {
         if (event.code === 'ERROR')
             console.error(event.error);
         if (event.code !== 'END')
             return;
-        const built = findDevInfo();
+        built = findDevInfo();
         if (!built) {
             console.error('no ayon-addon.json in dist/modules: is ayonAddon() in vite.config.ts?');
             return;
@@ -115,15 +152,25 @@ const dev = async () => {
             return;
         }
         served = true;
-        serveDirectory(built.dir, port);
+        const { info } = built;
         const url = `http://localhost:${port}`;
-        const open = `${findConnection(root).serverUrl}/?addonDev=${project.name}@${url}`;
-        print({ url, addon: project.name, remote: built.info.remote, buildId: built.info.buildId, open }, [
-            `${project.name} ${project.version}: built, serving ${url} (remote "${built.info.remote}")`,
-            'Open AYON with this addon from here (developer mode on):',
-            `  ${open}`,
-            'The page reloads after every rebuild. ?addonDev=off goes back to the installed addon.',
-        ].join('\n'));
+        // the page that loads it: AYON itself, or a frontend dev server in front of it (--frontend)
+        const page = (option('frontend') || connection.serverUrl).replace(/\/+$/, '');
+        const open = `${page}/?addonDev=${project.name}@${url}`;
+        void checks.then((results) => {
+            const ok = results.every((check) => check.ok || check.severity !== 'error');
+            print({ url, addon: project.name, remote: info.remote, buildId: info.buildId, open, ok, checks: results }, [
+                `${project.name} ${project.version}: built, serving ${url} (remote "${info.remote}")`,
+                `Checks against ${connection.serverUrl}:`,
+                formatChecks(results),
+                'Open AYON with this addon from here (your user needs developer mode on):',
+                `  ${open}`,
+                'The page reloads after every rebuild. If it shows the installed addon, its banner says why.',
+                '?addonDev=off goes back to the installed addon.',
+            ].join('\n'));
+            if (flag('open'))
+                openInBrowser(open);
+        });
     });
 };
 const slots = async () => {
@@ -166,7 +213,7 @@ const generateRestCommand = async () => {
         print(result, '');
 };
 // the arguments that aren't flags or flag values
-const BOOLEAN_FLAGS = ['--json', '--run', '--no-types', '--standalone', '--ayon', '--prune', '--hooks'];
+const BOOLEAN_FLAGS = ['--json', '--run', '--no-types', '--standalone', '--ayon', '--prune', '--hooks', '--open'];
 const positional = () => {
     const values = [];
     for (let i = 1; i < argv.length; i++) {
@@ -207,8 +254,12 @@ const HELP = `ayon-addon: tools for AYON addon frontends (run in the addon's fro
   dev [--port 5174]            the dev shell: the addon's contributions in AYON's surfaces,
                                without AYON, hot reload, a developer panel to pick slot,
                                project, entities
-  dev --ayon [--port 5173]     build on every change and serve it for AYON's dev override:
-                               open AYON with ?addonDev=<addon>@http://localhost:5173
+  dev --ayon [--port 5173] [--open] [--frontend <url>]
+                               build on every change and serve it for AYON's dev override;
+                               checks the server (reachable, the API key's user, the addon
+                               installed in the version the frontend calls) and prints the
+                               URL that loads it, <server or --frontend>/?addonDev=<addon>@
+                               http://localhost:5173 (--open: opens it)
   slots [--json]               the slots of the installed @ynput/ayon-addon
   check [--json] [--no-types]  the manifest as AYON reads it, the pieces' files, the types
   open <slot> <id> [--project <name>] [--entities type:id,...] [--page overview|products|lists]
@@ -226,8 +277,9 @@ const HELP = `ayon-addon: tools for AYON addon frontends (run in the addon's fro
                                their hooks, or offers to add the hooks of new endpoints
                                (--hooks: without asking). Options: ayonAddon({ rest })
 
-Sign-in: AYON_SERVER_URL and AYON_API_KEY; in the AYON dev workbench, the local stack and
-data/local-api-key.`;
+Sign-in: AYON_SERVER_URL and AYON_API_KEY, from the environment or the addon's .env.local or
+.env (in a terminal, a first run walks you through .env); in the AYON dev workbench, the local
+stack and data/local-api-key.`;
 const commands = {
     dev,
     slots,
@@ -243,7 +295,9 @@ if (!run) {
 }
 else {
     run().catch((error) => {
-        console.error(json ? JSON.stringify({ ok: false, error: String(error) }) : error);
+        // the message only: a setup problem needs no stack trace (--json keeps everything)
+        const message = error instanceof Error ? error.message : error;
+        console.error(json ? JSON.stringify({ ok: false, error: String(error) }) : message);
         process.exitCode = 1;
     });
 }

package/dist/devChecks.d.ts

@@ -0,0 +1,24 @@
+import type { AddonProject, AyonConnection } from './project.js';
+export interface DevCheck {
+    id: 'server' | 'apiKey' | 'user' | 'addon' | 'addonVersion';
+    ok: boolean;
+    /** error: the addon won't work in AYON; warning: it may, or it couldn't be checked */
+    severity?: 'error' | 'warning';
+    message: string;
+    /** how to fix it, when it failed */
+    fix?: string;
+}
+interface CheckOptions {
+    project: AddonProject;
+    connection: AyonConnection;
+    /** ayonAddon({ rest: { versionModule } }), relative to the addon's frontend folder */
+    versionModule?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare const readFrontendVersion: (root: string, versionModule?: string) => {
+    file: string;
+    version: string;
+} | undefined;
+export declare const checkDevRequirements: ({ project, connection, versionModule, fetch, }: CheckOptions) => Promise<DevCheck[]>;
+export declare const formatChecks: (checks: DevCheck[]) => string;
+export {};

package/dist/devChecks.js

@@ -0,0 +1,160 @@
+// `ayon-addon dev --ayon`: what AYON's dev override needs that the CLI can check against the server.
+// The page ignores the override (and says why in its banner) when one of these doesn't hold, and an
+// addon whose server version isn't installed loads, but its endpoint calls answer 404.
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+// the version the addon's frontend calls its endpoints with: the default export of its versionModule
+// (src/addonVersion.ts unless configured, see generate-rest)
+export const readFrontendVersion = (root, versionModule = 'src/addonVersion.ts') => {
+    const full = path.resolve(root, versionModule);
+    if (!existsSync(full))
+        return undefined;
+    const version = readFileSync(full, 'utf8').match(/export default\s+["']([^"']+)["']/)?.[1];
+    return version ? { file: versionModule, version } : undefined;
+};
+// the addon has server code: a missing server version breaks its endpoints, not only its settings
+const hasServerCode = (root) => existsSync(path.resolve(root, '..', 'server'));
+const INSTALL_FIX = (name, version) => `install ${name} ${version} on the server: build it (python create_package.py in the addon) and upload the zip in Studio settings > Addons > Upload Addons` +
+    ` (AYON dev workbench: scripts/mani.sh run addon-install -p <repo> SRC=<worktree>)`;
+export const checkDevRequirements = async ({ project, connection, versionModule, fetch = globalThis.fetch, }) => {
+    const { serverUrl, apiKey, apiKeySource } = connection;
+    const checks = [];
+    const headers = apiKey ? { 'x-api-key': apiKey } : {};
+    const get = async (urlPath) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        try {
+            const response = await fetch(`${serverUrl}${urlPath}`, { headers, signal: controller.signal });
+            return { status: response.status, body: response.ok ? await response.json() : undefined };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    // the server
+    try {
+        const { status, body } = await get('/api/info');
+        if (status !== 200) {
+            checks.push({
+                id: 'server',
+                ok: false,
+                severity: 'error',
+                message: `AYON at ${serverUrl} answered ${status} to /api/info`,
+                fix: 'check the server log; set AYON_SERVER_URL if this is the wrong server',
+            });
+            return checks;
+        }
+        const version = body?.version ? ` ${body.version}` : '';
+        checks.push({ id: 'server', ok: true, message: `AYON${version} at ${serverUrl}` });
+    }
+    catch {
+        checks.push({
+            id: 'server',
+            ok: false,
+            severity: 'error',
+            message: `AYON at ${serverUrl} doesn't answer`,
+            fix: 'start the server, or point AYON_SERVER_URL at a running one',
+        });
+        return checks;
+    }
+    if (!apiKey) {
+        checks.push({
+            id: 'apiKey',
+            ok: false,
+            severity: 'warning',
+            message: "no API key: can't check the user or the installed addon versions",
+            fix: "set AYON_API_KEY (a service user's key) to check them",
+        });
+        return checks;
+    }
+    // the key's user: what an agent's headless browser signs in as
+    const me = await get('/api/users/me').catch(() => ({ status: 0, body: undefined }));
+    if (me.status !== 200) {
+        checks.push({
+            id: 'user',
+            ok: false,
+            severity: 'error',
+            message: `the API key from ${apiKeySource} was rejected (${me.status || 'no answer'})`,
+            fix: "set AYON_API_KEY to a valid service user's key",
+        });
+        return checks;
+    }
+    const user = me.body;
+    if (user.data?.isService || user.attrib?.developerMode) {
+        checks.push({
+            id: 'user',
+            ok: true,
+            message: `${user.name} (the key's user) may use the override: ${user.data?.isService ? 'a service user' : 'developer mode is on'}. In a browser, your own user needs developer mode`,
+        });
+    }
+    else {
+        checks.push({
+            id: 'user',
+            ok: false,
+            severity: 'warning',
+            message: `${user.name} (the key's user) is not in developer mode: a page signed in with this key ignores the override`,
+            fix: "turn on developer mode for that user, or use a service user's key",
+        });
+    }
+    // the addon's server side, in the version the frontend calls
+    const frontendVersion = readFrontendVersion(project.root, versionModule);
+    if (frontendVersion && frontendVersion.version !== project.version) {
+        checks.push({
+            id: 'addonVersion',
+            ok: false,
+            severity: 'warning',
+            message: `${frontendVersion.file} says ${frontendVersion.version}, package.py says ${project.version}: the frontend calls the endpoints of ${frontendVersion.version}`,
+            fix: `set both to the same version (packaging writes ${frontendVersion.file} from package.py)`,
+        });
+    }
+    const version = frontendVersion?.version ?? project.version;
+    const addons = await get('/api/addons').catch(() => ({ status: 0, body: undefined }));
+    const addon = addons.body?.addons?.find((item) => item.name === project.name);
+    const severity = hasServerCode(project.root) ? 'error' : 'warning';
+    const effect = `the page loads its frontend from here anyway, but calls to /api/addons/${project.name}/${version}/... answer 404`;
+    if (addons.status !== 200) {
+        checks.push({
+            id: 'addon',
+            ok: false,
+            severity: 'warning',
+            message: `couldn't list the server's addons (${addons.status || 'no answer'})`,
+        });
+    }
+    else if (!addon) {
+        checks.push({
+            id: 'addon',
+            ok: false,
+            severity,
+            message: `${project.name} is not installed on the server: ${effect}`,
+            fix: INSTALL_FIX(project.name, version),
+        });
+    }
+    else if (!addon.versions[version]) {
+        checks.push({
+            id: 'addon',
+            ok: false,
+            severity,
+            message: `${project.name} ${version} is not installed (the server has ${Object.keys(addon.versions).join(', ') || 'none'}): ${effect}`,
+            fix: INSTALL_FIX(project.name, version),
+        });
+    }
+    else if (addon.versions[version].isBroken) {
+        checks.push({
+            id: 'addon',
+            ok: false,
+            severity: 'error',
+            message: `${project.name} ${version} is installed but failed to load on the server: its endpoints don't exist`,
+            fix: 'see the server log for the error in its server code',
+        });
+    }
+    else {
+        checks.push({ id: 'addon', ok: true, message: `${project.name} ${version} is installed on the server` });
+    }
+    return checks;
+};
+export const formatChecks = (checks) => checks
+    .flatMap((check) => [
+    `  ${(check.ok ? 'ok' : check.severity === 'error' ? 'FAIL' : 'warn').padEnd(5)} ${check.message}`,
+    ...(check.fix ? [`        fix: ${check.fix}`] : []),
+])
+    .join('\n');

package/dist/project.d.ts

@@ -13,11 +13,28 @@ export interface AyonConnection {
     /** where the key came from, for messages */
     apiKeySource?: string;
 }
+/**
+ * Loads the addon's `.env.local` and `.env` (AYON_SERVER_URL, AYON_API_KEY, …) into process.env,
+ * so no command needs an `--env-file` or a shell export.
+ */
+export declare const loadProjectEnv: (root?: string) => void;
+export declare const DEFAULT_SERVER_URL = "http://localhost:5000";
 /**
  * AYON_SERVER_URL and AYON_API_KEY win; inside the AYON dev workbench the local stack and its
  * key (data/local-api-key) are the defaults.
  */
 export declare const findConnection: (root?: string) => AyonConnection;
+export declare const envFileContents: (serverUrl: string, apiKey?: string) => string;
+/** The server address as typed (without trailing slashes), or undefined when it isn't http(s) */
+export declare const parseServerUrl: (answer: string) => string | undefined;
+/** What to do when no API key is set: which file to put it in, and where to get the key */
+export declare const keySetupMessage: (root: string) => string;
+/**
+ * Returns the API key, or stops the command when there is none. In a terminal with no env file
+ * yet, it walks through writing one: the server (default http://localhost:5000), then the key,
+ * which can be left empty to add later. A key given there lets the command go on.
+ */
+export declare const requireApiKey: (root: string, apiKey: string | undefined, interactive: boolean) => Promise<string>;
 /**
  * Imports a package the way the addon resolves it, not from where this file lives: a linked
  * @ynput/ayon-addon-dev would otherwise use the ayon-frontend checkout's copies.

package/dist/project.js

@@ -1,8 +1,11 @@
 // What the tools need to know about the addon they run in: its name and version (package.py),
 // where AYON runs, and how to sign in to it.
-import { existsSync, readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { createRequire } from 'module';
 import path from 'path';
+import { createInterface } from 'readline/promises';
+import { Writable } from 'stream';
 import { pathToFileURL } from 'url';
 const pyString = (source, key) => source.match(new RegExp(`^${key}\\s*=\\s*["']([^"']+)["']`, 'm'))?.[1];
 export const readAddonProject = (root = process.cwd()) => {
@@ -32,6 +35,20 @@ const workbenchServerPort = (workbench) => {
     const port = existsSync(env) && readFileSync(env, 'utf8').match(/^SERVER_PORT=(\d+)/m)?.[1];
     return port || '5100';
 };
+// the addon's env files, in order: the first one that sets a variable wins, and the shell wins over both
+const ENV_FILES = ['.env.local', '.env'];
+/**
+ * Loads the addon's `.env.local` and `.env` (AYON_SERVER_URL, AYON_API_KEY, …) into process.env,
+ * so no command needs an `--env-file` or a shell export.
+ */
+export const loadProjectEnv = (root = process.cwd()) => {
+    for (const name of ENV_FILES) {
+        const file = path.join(root, name);
+        if (existsSync(file))
+            process.loadEnvFile(file);
+    }
+};
+export const DEFAULT_SERVER_URL = 'http://localhost:5000';
 /**
  * AYON_SERVER_URL and AYON_API_KEY win; inside the AYON dev workbench the local stack and its
  * key (data/local-api-key) are the defaults.
@@ -40,7 +57,7 @@ export const findConnection = (root = process.cwd()) => {
     const workbench = findWorkbench(root);
     const serverUrl = process.env.AYON_SERVER_URL ||
         process.env.SERVER_URL ||
-        (workbench ? `http://localhost:${workbenchServerPort(workbench)}` : 'http://localhost:5000');
+        (workbench ? `http://localhost:${workbenchServerPort(workbench)}` : DEFAULT_SERVER_URL);
     if (process.env.AYON_API_KEY) {
         return { serverUrl, apiKey: process.env.AYON_API_KEY, apiKeySource: 'AYON_API_KEY' };
     }
@@ -51,6 +68,107 @@ export const findConnection = (root = process.cwd()) => {
     }
     return { serverUrl };
 };
+// the .env that requireApiKey writes: the server, and the key when the user gave one
+export const envFileContents = (serverUrl, apiKey = '') => `# ayon-addon: the AYON server and an API key for this addon's tools.
+# Every ayon-addon command reads this file. A variable set in your shell wins over it, and
+# .env.local (same format) wins over this file. Keep both out of git.
+
+# The AYON server
+AYON_SERVER_URL=${serverUrl}
+
+# A service user's key: Settings → Users → Add Service User → Generate new key.
+# AYON shows the key once, so copy it here.
+AYON_API_KEY=${apiKey}
+`;
+/** The server address as typed (without trailing slashes), or undefined when it isn't http(s) */
+export const parseServerUrl = (answer) => {
+    const address = answer.trim().replace(/\/+$/, '');
+    try {
+        const { protocol } = new URL(address);
+        return protocol === 'http:' || protocol === 'https:' ? address : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+// The setup's questions in one line reader that stays open, so answers typed ahead are not lost
+// between questions. A secret is typed without echo: the reader's output is muted while it's read.
+const openTerminal = () => {
+    let muted = false;
+    const output = new Writable({
+        write: (chunk, _encoding, done) => {
+            if (!muted)
+                process.stdout.write(chunk);
+            done();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output, terminal: true });
+    return {
+        ask: async (question, secret = false) => {
+            if (secret) {
+                process.stdout.write(question);
+                muted = true;
+            }
+            const answer = await rl.question(secret ? '' : question);
+            if (secret) {
+                muted = false;
+                process.stdout.write('\n');
+            }
+            return answer.trim();
+        },
+        close: () => rl.close(),
+    };
+};
+/** What to do when no API key is set: which file to put it in, and where to get the key */
+export const keySetupMessage = (root) => {
+    const files = ENV_FILES.map((name) => path.join(root, name)).filter((file) => existsSync(file));
+    const key = "Set AYON_API_KEY to a service user's key: Settings → Users → Add Service User → Generate new key (AYON shows it once).";
+    const file = path.join(root, '.env');
+    return files.length
+        ? `no API key: AYON_API_KEY is not set in ${files.join(' or ')} or in the shell. ${key}`
+        : `no API key: AYON_API_KEY is not set in the shell or in ${file}. ${key} Set AYON_SERVER_URL too if the server isn't ${DEFAULT_SERVER_URL}. Or run this command in a terminal and ayon-addon asks for them and writes ${file}.`;
+};
+/**
+ * Returns the API key, or stops the command when there is none. In a terminal with no env file
+ * yet, it walks through writing one: the server (default http://localhost:5000), then the key,
+ * which can be left empty to add later. A key given there lets the command go on.
+ */
+export const requireApiKey = async (root, apiKey, interactive) => {
+    if (apiKey)
+        return apiKey;
+    const file = path.join(root, '.env');
+    const hasEnvFile = ENV_FILES.some((name) => existsSync(path.join(root, name)));
+    if (!interactive || hasEnvFile)
+        throw new Error(keySetupMessage(root));
+    const terminal = openTerminal();
+    try {
+        if (/^n/i.test(await terminal.ask(`no API key yet. Set up ${file}? [Y/n] `))) {
+            throw new Error(keySetupMessage(root));
+        }
+        let serverUrl;
+        while (!serverUrl) {
+            const answer = await terminal.ask(`AYON server [${DEFAULT_SERVER_URL}]: `);
+            serverUrl = parseServerUrl(answer || DEFAULT_SERVER_URL);
+            if (!serverUrl)
+                console.log('start the address with http:// or https://');
+        }
+        const key = await terminal.ask('AYON API key (Settings → Users → Add Service User → Generate new key), or Enter to add it later: ', true);
+        writeFileSync(file, envFileContents(serverUrl, key));
+        // git check-ignore: 1 means git doesn't ignore the file (0 ignored, 128 not a repo)
+        const ignored = spawnSync('git', ['check-ignore', '-q', file], { cwd: root }).status !== 1;
+        const warning = ignored ? '' : '. It is not git-ignored: add .env to .gitignore before you commit';
+        if (!key) {
+            throw new Error(`created ${file} with ${serverUrl}: add AYON_API_KEY there, then run the command again${warning}`);
+        }
+        console.log(`created ${file}${warning}`);
+        process.env.AYON_SERVER_URL = serverUrl;
+        process.env.AYON_API_KEY = key;
+        return key;
+    }
+    finally {
+        terminal.close();
+    }
+};
 /**
  * Imports a package the way the addon resolves it, not from where this file lives: a linked
  * @ynput/ayon-addon-dev would otherwise use the ayon-frontend checkout's copies.

package/dist/rest.js

@@ -9,7 +9,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import path from 'path';
 import { createInterface } from 'readline/promises';
-import { findConnection, importFromProject, readAddonProject } from './project.js';
+import { findConnection, importFromProject, readAddonProject, requireApiKey, } from './project.js';
 const camel = (name) => name.replace(/[^A-Za-z0-9]+(.)?/g, (_, next) => (next ? next.toUpperCase() : ''));
 const capitalize = (name) => name.charAt(0).toUpperCase() + name.slice(1);
 const posixRelative = (from, to) => {
@@ -17,10 +17,15 @@ const posixRelative = (from, to) => {
     return relative.startsWith('.') ? relative : `./${relative}`;
 };
 export const hookName = ({ name, type }) => `use${capitalize(name)}${type === 'query' ? 'Query' : 'Mutation'}`;
-const downloadSchema = async (root, addon) => {
-    const { serverUrl, apiKey } = findConnection(root);
+const downloadSchema = async (root, addon, interactive) => {
+    // after the key: the setup may have chosen the server too
+    const apiKey = await requireApiKey(root, findConnection(root).apiKey, interactive);
+    const { serverUrl } = findConnection(root);
     const url = `${serverUrl}/api/addons/${addon.name}/${addon.version}/openapi.json`;
-    const response = await fetch(url, { headers: apiKey ? { 'x-api-key': apiKey } : {} });
+    const response = await fetch(url, { headers: { 'x-api-key': apiKey } });
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`${url} answered ${response.status}: the API key was refused, check AYON_API_KEY in the shell or in the .env files of this folder`);
+    }
     if (!response.ok) {
         throw new Error(`${url} answered ${response.status}: is ${addon.name} ${addon.version} installed there?`);
     }
@@ -89,7 +94,7 @@ export const generateRest = async (options) => {
     let schema = resolve(options.schemaFile || rest.schema || 'gen/openapi.json');
     let url;
     if (!options.schemaFile) {
-        const download = await downloadSchema(root, addon);
+        const download = await downloadSchema(root, addon, options.interactive);
         url = download.url;
         mkdirSync(path.dirname(schema), { recursive: true });
         writeFileSync(schema, JSON.stringify(patchSchema(download.schema, addon.name), null, 2));

package/dist/shell/index.js

@@ -2,13 +2,13 @@ import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import { useCallback, createContext, useContext, useState, useMemo, useEffect, useSyncExternalStore, Component, StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { provideHost, isKnownSlot, getRegistry, contributionTitle, getHost, registerManifest, setManifestsLoading } from "@ynput/ayon-addon/host";
-import { useGetProjectFoldersQuery, useGetCurrentUserQuery, useListProjectsQuery, useGetEntitiesDetailsPanelQuery, useGetProjectQuery, useGetUsersAssigneeQuery, createStandaloneStore } from "@ynput/ayon-frontend-shared/api";
-import { SlicerHost, ProjectPageLayoutHost, JsonViewer, AddonButton, useAddonCustomizeSections, useAddonTableShortcuts, SettingsPanel, AddonDialog, useStudioPageSlotContext, useProjectPageSlotContext, SplitterStyles, LoginPage } from "@ynput/ayon-frontend-shared/components";
-import { useGlobalContext, usePowerpack, useMenuContext, ProjectContextProvider, ProjectFoldersContextProvider, useSettingsPanel, useScopedDetailsPanel, EntityUpdatesProvider, GlobalProvider, PowerpackProvider, MenuProvider, URIProvider, DetailsPanelProvider, PiPProvider, DeleteEntitiesProvider, SettingsPanelProvider } from "@ynput/ayon-frontend-shared/context";
+import { useGetProjectFoldersQuery, useGetCurrentUserQuery, usersApi, useListProjectsQuery, useGetEntitiesDetailsPanelQuery, useGetProjectQuery, useGetUsersAssigneeQuery, createStandaloneStore } from "@ynput/ayon-frontend-shared/api";
+import { AddonMoreMenu, AddonEntityPicker, SlicerHost, ProjectPageLayoutHost, JsonViewer, AddonButton, useAddonCustomizeSections, useAddonTableShortcuts, shortcutEntities, SettingsPanel, AddonDialog, useStudioPageSlotContext, useProjectPageSlotContext, SplitterStyles, LoginPage, AddonServices } from "@ynput/ayon-frontend-shared/components";
+import { useGlobalContext, usePowerpack, useMenuContext, useSettingsPanel, useScopedDetailsPanel, EntityUpdatesProvider, GlobalProvider, PowerpackProvider, MenuProvider, URIProvider, DetailsPanelProvider, PiPProvider, DeleteEntitiesProvider, SettingsPanelProvider, ProjectContextProvider, ProjectFoldersContextProvider } from "@ynput/ayon-frontend-shared/context";
 import { buildProjectsTableData, ProjectsTable, PROJECTS_LIST_MENU_ID, parseProjectFolderRowId } from "@ynput/ayon-frontend-shared/ProjectsTable";
 import { getProjectDisplayName, clearAccessToken, storeAccessToken } from "@ynput/ayon-frontend-shared/util";
 import { Button, Icon, Dropdown, Dialog, InputText } from "@ynput/ayon-react-components";
-import { useContributions, prefetchPiece, runContribution, ContributionView } from "@ynput/ayon-addon";
+import { useContributions, prefetchPiece, runContribution, EntityPicker, ContributionView } from "@ynput/ayon-addon";
 import { useCreateContextMenu, ContextMenuProvider, GlobalContextMenu } from "@ynput/ayon-frontend-shared/ContextMenu";
 import { useDispatch, Provider } from "react-redux";
 import { BrowserRouter, useNavigate, useSearchParams, useParams, useLocation } from "react-router-dom";
@@ -16,7 +16,6 @@ import { ToastContainer } from "react-toastify";
 import { Splitter, SplitterPanel } from "primereact/splitter";
 import { useAddonTableColumns, useAddonEntityMenuItems, AddonColumnDataScope, ProjectDataProvider } from "@ynput/ayon-frontend-shared/ProjectTreeTable";
 import { SLOT_DOCS } from "@ynput/ayon-addon/check";
-import { EntityPickerDialog } from "@ynput/ayon-frontend-shared/EntityPickerDialog";
 import { DetailsPanel } from "@ynput/ayon-frontend-shared/DetailsPanel";
 import { NewEntityProvider } from "@ynput/ayon-frontend-shared/NewEntity";
 import { SlicerProvider, useSlicerContext } from "@ynput/ayon-frontend-shared/Slicer";
@@ -63,23 +62,26 @@ const useShellMenu = (slot, makeContext, applies = () => true) => {
   ) : null;
   return { openContextMenu, dropdown, itemsFor };
 };
+const toAddonUser = (user2) => {
+  if (!user2?.name) return void 0;
+  const data = user2.data || {};
+  const isAdmin = !!data.isAdmin || !!data.isService;
+  return {
+    name: user2.name,
+    fullName: user2.attrib?.fullName || void 0,
+    email: user2.attrib?.email || void 0,
+    isAdmin,
+    isManager: isAdmin || !!data.isManager,
+    isGuest: !!data.isGuest,
+    isService: !!data.isService,
+    isDeveloper: !!user2.attrib?.developerMode || !!data.isService
+  };
+};
 const useUser = () => {
   const { data: user2 } = useGetCurrentUserQuery();
-  return useMemo(() => {
-    if (!user2?.name) return void 0;
-    const data = user2.data || {};
-    const isAdmin = !!data.isAdmin || !!data.isService;
-    return {
-      name: user2.name,
-      fullName: user2.attrib?.fullName || void 0,
-      email: user2.attrib?.email || void 0,
-      isAdmin,
-      isManager: isAdmin || !!data.isManager,
-      isGuest: !!data.isGuest,
-      isDeveloper: !!user2.attrib?.developerMode || !!data.isService
-    };
-  }, [user2]);
+  return useMemo(() => toAddonUser(user2), [user2]);
 };
+const getShellUser = (state) => toAddonUser(usersApi.endpoints.getCurrentUser.select()(state).data);
 const StudioSelectionContext = createContext(null);
 const StudioPageLayout = ({ sidebar, children }) => /* @__PURE__ */ jsxs("div", { style: { display: "flex", width: "100%", height: "100%", minHeight: 0 }, children: [
   sidebar && /* @__PURE__ */ jsx(
@@ -158,7 +160,9 @@ const provideShellHost = () => provideHost({
     ProjectPageLayout: ProjectPageLayoutHost,
     Slicer: SlicerHost,
     StudioPageLayout,
-    ProjectList
+    ProjectList,
+    EntityPicker: AddonEntityPicker,
+    MoreMenu: AddonMoreMenu
   }
 });
 const StudioSelectionProvider = ({
@@ -357,6 +361,11 @@ const SLOT_AREAS = [
     icon: "web_asset",
     sections: [{ slots: [{ slot: "header.item", label: "Items" }] }]
   },
+  {
+    label: "Background (no UI)",
+    icon: "memory",
+    sections: [{ slots: [{ slot: "app.service", label: "Services" }] }]
+  },
   {
     label: "Studio",
     icon: "home",
@@ -406,7 +415,7 @@ const slotPath = (slot) => {
   return ["Other", slot];
 };
 const slotIcon = (slot) => SLOT_AREAS.find((area) => area.sections.some((s) => s.slots.some((x) => x.slot === slot)))?.icon || "extension";
-const NO_PROJECT = ["studio.page", "header.item", "projectList.menuItem"];
+const NO_PROJECT = ["studio.page", "header.item", "projectList.menuItem", "app.service"];
 const PROJECTS = ["studio.page", "projectList.menuItem"];
 const ENTITIES = [
   "detailsPanel.tab",
@@ -681,21 +690,21 @@ const EntitiesPicker = ({ selection, onChange }) => {
         }
       )
     ] }, entity.id)),
-    picking && // the picker reads the project's folders, like on a project page
-    /* @__PURE__ */ jsx(ProjectContextProvider, { projectName, children: /* @__PURE__ */ jsx(ProjectFoldersContextProvider, { projectName, children: /* @__PURE__ */ jsx(
-      EntityPickerDialog,
+    picking && // the one addons get, as the shell's host provides it
+    /* @__PURE__ */ jsx(
+      EntityPicker,
       {
         projectName,
         entityType,
-        isMultiSelect: true,
+        multiSelect: true,
+        initialSelection: entities,
         onClose: () => setPicking(false),
-        onSubmit: (ids) => {
+        onSubmit: (picked) => {
           setPicking(false);
-          const picked = ids.map((id) => ({ id, entityType, projectName }));
           onChange({ ...selection, entityType, entities: picked });
         }
       }
-    ) }) })
+    )
   ] });
 };
 const TablePage = ({ selection, onChange }) => /* @__PURE__ */ jsx(Field, { label: "Table", children: /* @__PURE__ */ jsx(
@@ -941,6 +950,7 @@ const ButtonItem = ({
     }
   );
 };
+const ServiceNote = () => /* @__PURE__ */ jsx("div", { style: { padding: 16, color: "var(--md-sys-color-outline)" }, "data-shell-surface": "service", children: "A service has no UI. It is mounted once for the whole shell, as in AYON, and keeps running while you pick other contributions; a crash shows as a toast. Its context is the shell's project." });
 const ShellTable = ({ page, entities, selected, onSelect }) => {
   const { columns: addonColumns } = useAddonTableColumns(page);
   const columns = useMemo(
@@ -1088,6 +1098,7 @@ const PreviewStage = ({
       const item = contribution;
       return /* @__PURE__ */ jsx("div", { style: { padding: 16 }, children: /* @__PURE__ */ jsx(Button, { icon: item.icon, label: item.label, "data-shell-action": "run", onClick: run }) });
     }
+    if (slot === "app.service") return /* @__PURE__ */ jsx(ServiceNote, {});
     if (slot === "tableColumn") {
       const entities = context.entities || [];
       return /* @__PURE__ */ jsx(
@@ -1199,6 +1210,11 @@ const StudioPageStage = ({ contribution, selection, onChange }) => {
     contribution.key
   );
 };
+const ServiceStage = ({ contribution, selection }) => {
+  const context = useMemo(() => ({ projectName: selection.projectName ?? null }), [selection.projectName]);
+  useReport(contribution, context, true);
+  return /* @__PURE__ */ jsx(ServiceNote, {});
+};
 const HeaderStage = ({ contribution, selection }) => {
   const { contributions } = useContributions("header.item");
   const [context, setContext] = useState();
@@ -1235,7 +1251,7 @@ const DetailsPanelStage = ({ contribution, selection }) => {
     if (isTab) setTab(contribution.key);
   }, [contribution.key, isTab]);
   const context = useMemo(
-    () => isTab ? { projectName, entityType, entities, scope: DETAILS_SCOPE } : { projectName, entityType, selectedEntities: entities },
+    () => isTab ? { projectName, entityType, entities, scope: DETAILS_SCOPE } : { projectName, entityType, entities },
     [isTab, projectName, entityType, entities]
   );
   useReport(contribution, context, !!project && entities.length > 0, !isTab);
@@ -1263,15 +1279,23 @@ const DetailsPanelStage = ({ contribution, selection }) => {
 };
 const SlicerBody = ({ contribution, selection }) => {
   const { rowSelection, sliceType } = useSlicerContext();
-  const context = useMemo(
-    () => ({
+  const context = useMemo(() => {
+    const ids = Object.keys(rowSelection).filter((id) => rowSelection[id]);
+    const entities = sliceType === "hierarchy" ? ids.map(
+      (id) => selection.entities.find((entity) => entity.id === id) ?? {
+        id,
+        entityType: "folder",
+        projectName: selection.projectName
+      }
+    ) : [];
+    return {
       projectName: selection.projectName,
       sliceType,
-      selected: Object.keys(rowSelection).filter((id) => rowSelection[id]).map((id) => ({ id })),
+      selected: ids.map((id) => ({ id })),
+      entities,
       menu: "context"
-    }),
-    [selection.projectName, sliceType, rowSelection]
-  );
+    };
+  }, [selection.projectName, selection.entities, sliceType, rowSelection]);
   useReport(contribution, context, true, true);
   return (
     // positioned: the slicer's Section fills its container (a splitter panel in AYON)
@@ -1324,6 +1348,7 @@ const TableStage = ({ contribution, selection }) => {
       table: page,
       projectName,
       rows,
+      entities: shortcutEntities(page, projectName, rows),
       focused: { rowId: rows[0].id, columnId: "name" },
       cells: rows.map((row) => ({ rowId: row.id, columnId: "name" }))
     };
@@ -1441,6 +1466,8 @@ const Stage = ({
       case "projectTable.toolbarItem":
       case "projectTable.customizeSection":
         return /* @__PURE__ */ jsx(TableStage, { ...props });
+      case "app.service":
+        return /* @__PURE__ */ jsx(ServiceStage, { ...props });
       default:
         return /* @__PURE__ */ jsxs(Hint, { children: [
           "The shell has no stage for ",
@@ -1557,33 +1584,41 @@ const Workbench = ({ options, mode }) => {
   const [selection, setSelection] = useState(readSelection);
   useEffect(() => writeSelection(selection), [selection]);
   useEffect(() => setStatus({ selection, mode }), [selection, mode]);
-  return /* @__PURE__ */ jsxs(Splitter, { className: "ayon-shell", stateKey: "ayon-addon-shell", stateStorage: "local", children: [
-    /* @__PURE__ */ jsx(SplitterPanel, { size: 22, minSize: 12, style: { overflow: "hidden" }, children: /* @__PURE__ */ jsx(StageBoundary, { what: "developer panel", children: /* @__PURE__ */ jsx(DevPanel, { options, mode, selection, onChange: setSelection }) }) }),
-    /* @__PURE__ */ jsxs(SplitterPanel, { size: 78, style: { overflow: "hidden", display: "flex", flexDirection: "column" }, children: [
-      /* @__PURE__ */ jsx(StageCaption, { mode, selection }),
-      /* @__PURE__ */ jsx(
-        ProjectProviders,
-        {
-          projectName: mode === "live" || selection.slot === "tableColumn" ? selection.projectName : void 0,
-          light: mode === "preview",
-          children: /* @__PURE__ */ jsx(StageBoundary, { children: /* @__PURE__ */ jsx(
-            Stage,
-            {
-              mode,
-              selection,
-              onChange: setSelection
-            },
-            selection.projectName || ""
-          ) }, `${selection.projectName}:${selection.slot}:${selection.id}`)
-        }
-      )
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(AddonServices, { projectName: selection.projectName ?? null }),
+    /* @__PURE__ */ jsxs(Splitter, { className: "ayon-shell", stateKey: "ayon-addon-shell", stateStorage: "local", children: [
+      /* @__PURE__ */ jsx(SplitterPanel, { size: 22, minSize: 12, style: { overflow: "hidden" }, children: /* @__PURE__ */ jsx(StageBoundary, { what: "developer panel", children: /* @__PURE__ */ jsx(DevPanel, { options, mode, selection, onChange: setSelection }) }) }),
+      /* @__PURE__ */ jsxs(SplitterPanel, { size: 78, style: { overflow: "hidden", display: "flex", flexDirection: "column" }, children: [
+        /* @__PURE__ */ jsx(StageCaption, { mode, selection }),
+        /* @__PURE__ */ jsx(
+          ProjectProviders,
+          {
+            projectName: mode === "live" || selection.slot === "tableColumn" ? selection.projectName : void 0,
+            light: mode === "preview",
+            children: /* @__PURE__ */ jsx(StageBoundary, { children: /* @__PURE__ */ jsx(
+              Stage,
+              {
+                mode,
+                selection,
+                onChange: setSelection
+              },
+              selection.projectName || ""
+            ) }, `${selection.projectName}:${selection.slot}:${selection.id}`)
+          }
+        )
+      ] })
     ] })
   ] });
 };
 const Shell = ({ options, mode }) => {
   const store = useMemo(() => {
     const standaloneStore = createStandaloneStore();
-    provideHost({ dispatch: standaloneStore.dispatch });
+    provideHost({
+      dispatch: standaloneStore.dispatch,
+      getUser: () => getShellUser(standaloneStore.getState()),
+      // navigateToEntity: the shell has none of AYON's pages, so the link opens in AYON
+      navigate: (to) => window.open(new URL(to, options.serverUrl).href, "_blank", "noopener")
+    });
     return standaloneStore;
   }, []);
   return /* @__PURE__ */ jsxs(Provider, { store, children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ynput/ayon-addon-dev",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Dev tooling for AYON addon frontends: Vite plugin, dev server, CLI, lint preset",
   "repository": {
     "type": "git",
@@ -41,10 +41,10 @@
   },
   "peerDependencies": {
     "@module-federation/vite": ">=1.14",
-    "@ynput/ayon-addon": "^0.1.0",
+    "@ynput/ayon-addon": "0.2.0",
     "vite": ">=6",
-    "@ynput/ayon-frontend-shared": ">=0.7.4",
-    "@ynput/ayon-react-components": "^1.23.0",
+    "@ynput/ayon-frontend-shared": ">=0.7.6",
+    "@ynput/ayon-react-components": "^1.25.0",
     "primereact": ">=9",
     "react": ">=18",
     "react-dom": ">=18",