@ynput/ayon-addon-dev 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,139 @@
+# @ynput/ayon-addon-dev
+
+Tooling for AYON addon frontends. The API itself (slots, `useSlot`, the manifest) is
+`@ynput/ayon-addon`: read `node_modules/@ynput/ayon-addon/AGENTS.md` first.
+
+## Vite: `ayonAddon()`
+
+```ts
+// vite.config.ts
+import react from '@vitejs/plugin-react'
+import { ayonAddon } from '@ynput/ayon-addon-dev/vite'
+
+export default defineConfig({ plugins: [react(), ayonAddon({ name: 'my_addon' })] })
+```
+
+- `name` is the federation remote: the key in the server's `frontend_modules`
+  (`{"my_addon": ["manifest"]}`), and the build goes to `dist/modules/<name>`.
+- It exposes `./manifest` (`src/manifest.ts`, or `manifest`), plus `exposes` if the addon keeps
+  keyword modules for older AYON versions.
+- It shares everything AYON provides (React, the store, the router, toasts, every
+  `@ynput/ayon-frontend-shared` entry) as singletons, and `@ynput/ayon-addon` with `import: false`:
+  the addon never bundles a copy of it.
+
+## CLI: `ayon-addon`
+
+Run in the addon's frontend folder. Every command takes `--json` for scripts and agents.
+
+| 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 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 |
+| `ayon-addon preview <slot> <id> --fixture name [--run] [--prune] [--screenshot file]` | The same from `dev/fixtures/<name>.json`, without a server. `--prune` drops the answers it didn't use |
+| `ayon-addon generate-rest [--schema file] [--hooks]` | The addon's server endpoints as RTK Query endpoints in AYON's api (below) |
+
+`open` and `preview` start the dev shell themselves, or use a running one with `--url
+http://localhost:5174`. They need playwright (`yarn add -D playwright`, `npx playwright install
+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.
+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`.
+
+## Developing without AYON: the dev shell (`dev`, the default)
+
+`ayon-addon dev` serves the addon with Vite's dev server (hot reload) inside a dev shell instead
+of AYON:
+
+- **Real AYON surfaces** from `@ynput/ayon-frontend-shared`: the details panel, the slicer, the
+  Customize panel, and the addon columns' cells and `fetchValues`, in AYON's providers (store, api,
+  contexts). AYON's project list table, with only the addon's items in its menus (AYON's own,
+  such as open, pin and folders, need the app). Plain stand-ins for what lives in the AYON app: the header and the
+  table around the columns (its rows are the picked entities, its right-click menu has the
+  `entityMenuItem` items, and once clicked it takes the `table.shortcut` keys). Pages render alone, without AYON's page tabs.
+- **Developer panel**, in two resizable halves that scroll on their own: the manifest's
+  contributions grouped by the area of AYON they show in (app header, studio, project with its
+  slicer and tables, details panel), then by slot, with the ones AYON would skip and why; below,
+  the context of the one on stage, the only place it is changed: a project switcher, the studio's
+  project selection (also what a studio page's project list shows), an entity picker (AYON's) for
+  the slots about entities, the table page, *Run* for menu items, a few lines of the context the
+  contribution gets (click for all of it), and the preview fixtures.
+- Above the stage, a caption names the contribution, where AYON shows it and its slot.
+- The selection is in the URL
+  (`?slot=…&contribution=…&ctxProject=…&ctxProjects=a,b&ctxEntities=task:<id>,…`).
+- Requests to `/api`, `/graphql`, `/ws` go through the dev server to the AYON server, with the API
+  key when there is one (no login page); without a key the page shows AYON's login.
+- It needs a `@ynput/ayon-frontend-shared` build with the addon SDK (until one is released:
+  `yarn copy-shared <ayon-frontend>` after `yarn build:shared` there).
+
+### Preview: fixtures instead of a server
+
+`?preview=<name>` (or `ayon-addon preview`) renders one contribution with the context and server
+answers of `dev/fixtures/<name>.json`, and no server:
+
+```json
+{
+  "slot": "detailsPanel.tab",
+  "id": "comments",
+  "context": { "projectName": "demo", "entityType": "task", "entities": [{ "id": "…", "entityType": "task", "projectName": "demo" }], "scope": "addon-dev" },
+  "responses": { "graphql GetComments": { "status": 200, "body": { "data": { … } } } }
+}
+```
+
+- Answers are keyed `GET /api/<path>?<query>` or `graphql <OperationName>` (the variables don't
+  count). A request without an answer gets a 404 and fails the preview (`not in the fixture`).
+- The user, the site info, the project list and the cloud status are answered by the shell (an
+  admin "preview" user): fixtures leave them out.
+- Record one from a live server: *Save* in the developer panel, or `ayon-addon open … --save-fixture
+  <name>`; then `ayon-addon preview … --fixture <name> --prune`. A recording holds the server's real
+  data: check it before committing it (project names, users, comment text).
+
+## Server endpoints: `ayon-addon generate-rest`
+
+Addons that add their own server endpoints generate the frontend side from the addon's OpenAPI
+schema (needs `@rtk-query/codegen-openapi` as a dev dependency):
+
+1. Downloads `/api/addons/<name>/<version>/openapi.json` (name and version from `package.py`) from
+   a server with that version installed, to `gen/openapi.json` (gitignore it). AYON's own
+   `/openapi.json` has no addon routes. `--schema <file>` uses a saved schema instead.
+2. Generates `src/api/generated/<name>.ts`: the endpoints injected into AYON's api (one cache with
+   AYON's), without hooks. Operation ids are prefixed with the addon name, so endpoints can't
+   clash with AYON's or another addon's (`timetrackerStartSession`). URLs use the default export
+   of `src/addonVersion.ts`, so they call the running version.
+3. **Never edit the generated file.** Tags, `transformResponse` and optimistic updates go in
+   `src/api/<name>.ts`, which enhances the endpoints and exports their hooks. The first run creates
+   it; later runs list endpoints whose hooks it doesn't export and, in a terminal, offer to add
+   them in a block of their own (`--hooks`: without asking). Hooks of removed endpoints are only
+   reported.
+
+Options in `ayonAddon({ rest: { ... } })`: `queries` (POST endpoints that only read, generated as
+queries), `generated`, `api`, `versionModule`, `schema` (paths).
+
+## Signing in
+
+- People: the AYON login.
+- Agents and CI: `AYON_API_KEY` (a service user's key), sent as `x-api-key`. In the AYON dev
+  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).
+
+## Lint preset
+
+```js
+// eslint.config.js
+import { ayonAddonLint } from '@ynput/ayon-addon-dev/eslint'
+export default defineConfig([..., ...ayonAddonLint])
+```
+
+Flags imports that bypass AYON's copies: `react-router-dom`, `react-router` and `react-toastify`
+(use `@ynput/ayon-addon`), `@ynput/ayon-addon/host`, and a manifest importing
+`@ynput/ayon-addon` instead of `@ynput/ayon-addon/manifest`.

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2025 Ynput s.r.o.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/dist/browse.d.ts

@@ -0,0 +1,59 @@
+export interface BrowseOptions {
+    root: string;
+    slot: string;
+    id: string;
+    /** preview mode: the fixture's name (dev/fixtures/<name>.json) */
+    fixture?: string;
+    project?: string;
+    /** `type:id,type:id` */
+    entities?: string;
+    page?: string;
+    /** a running `ayon-addon dev` */
+    url?: string;
+    screenshot?: string;
+    /** run the menu item (`run` piece) and report what it did */
+    run?: boolean;
+    /** live mode: save what the contribution loaded as dev/fixtures/<name>.json */
+    saveFixture?: string;
+    /** preview: keep only the fixture answers the page used */
+    prune?: boolean;
+    timeout?: number;
+}
+export interface BrowseResult {
+    ok: boolean;
+    mode: 'live' | 'preview';
+    url: string;
+    slot: string;
+    id: string;
+    /** the slot context the contribution got (functions and elements left out) */
+    context?: Record<string, unknown>;
+    /** contributions that crashed or failed to load (AYON's error boxes) */
+    contributionErrors: string[];
+    /** console errors and uncaught exceptions */
+    errors: string[];
+    warnings: string[];
+    toasts: string[];
+    /** with --run: what the item put on the clipboard */
+    clipboard?: string;
+    /** preview: requests the fixture has no answer for */
+    unmatched?: string[];
+    screenshot?: string;
+    savedFixture?: string;
+    /** with --prune: the answers removed from the fixture */
+    pruned?: number;
+}
+export declare const browse: (options: BrowseOptions) => Promise<BrowseResult>;
+export declare const formatBrowse: (result: BrowseResult) => string;
+declare global {
+    interface Window {
+        __AYON_ADDON_SHELL__?: {
+            ready: boolean;
+            unmatched: string[];
+            used: string[];
+            fixture: () => {
+                context: Record<string, unknown>;
+            } | undefined;
+            run: () => Promise<void>;
+        };
+    }
+}

package/dist/browse.js

@@ -0,0 +1,156 @@
+// `ayon-addon open | preview`: the dev shell in a headless browser, for agents and scripts.
+// Starts the standalone dev server unless --url points at a running one, waits until the
+// contribution rendered, and reports what happened (errors, toasts, the context it got).
+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 { STANDALONE_ENV } from './standalone.js';
+// the addon's playwright, else the one next to this package (the ayon-frontend checkout)
+const loadPlaywright = async (root) => {
+    // a CommonJS package: its API is the default export
+    const api = (module) => module.default ?? module;
+    try {
+        return api(await importFromProject(root, 'playwright'));
+    }
+    catch {
+        try {
+            const require = createRequire(import.meta.url);
+            return api(await import(pathToFileURL(require.resolve('playwright')).href));
+        }
+        catch {
+            throw new Error('playwright is not installed: yarn add -D playwright && npx playwright install chromium');
+        }
+    }
+};
+const startServer = async (root) => {
+    const vite = await importFromProject(root, 'vite');
+    process.env[STANDALONE_ENV] = '1';
+    const server = await vite.createServer({
+        root,
+        logLevel: 'error',
+        server: { port: 5180, strictPort: false },
+    });
+    await server.listen();
+    return server;
+};
+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)');
+    }
+    const server = options.url ? undefined : await startServer(options.root);
+    const base = options.url || server.resolvedUrls.local[0];
+    // the shell's URL parameters (shell/src/params.ts)
+    const params = new URLSearchParams({ slot: options.slot, contribution: options.id });
+    if (options.fixture)
+        params.set('preview', options.fixture);
+    if (options.project)
+        params.set('ctxProject', options.project);
+    if (options.entities)
+        params.set('ctxEntities', options.entities);
+    if (options.page)
+        params.set('ctxPage', options.page);
+    const url = `${base.replace(/\/$/, '')}/?${params}`;
+    const { chromium } = await loadPlaywright(options.root);
+    const browser = await chromium.launch();
+    const result = {
+        ok: false,
+        mode,
+        url,
+        slot: options.slot,
+        id: options.id,
+        contributionErrors: [],
+        errors: [],
+        warnings: [],
+        toasts: [],
+    };
+    let ready = false;
+    try {
+        const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+        await context.grantPermissions(['clipboard-read', 'clipboard-write'], { origin: base });
+        const page = await context.newPage();
+        page.on('console', (message) => {
+            const text = message.text();
+            // React's development warnings are console errors, but not failures
+            if (message.type() === 'error' && !text.startsWith('Warning:'))
+                result.errors.push(text);
+            else if (message.type() === 'error' || message.type() === 'warning')
+                result.warnings.push(text);
+        });
+        page.on('pageerror', (error) => result.errors.push(error.stack || error.message));
+        await page.goto(url);
+        const timeout = options.timeout ?? 30000;
+        try {
+            await page.waitForFunction(() => window.__AYON_ADDON_SHELL__?.ready === true, undefined, { timeout });
+        }
+        catch {
+            const text = await page.locator('body').innerText();
+            result.errors.push(`the stage didn't get ready in ${timeout} ms: ${text.slice(0, 300)}`);
+        }
+        // the contribution's own requests and lazy pieces
+        await page.waitForLoadState('networkidle').catch(() => undefined);
+        await page.waitForTimeout(1000);
+        ready = await page.evaluate(() => window.__AYON_ADDON_SHELL__?.ready === true);
+        if (options.run && ready) {
+            await page.evaluate(() => window.__AYON_ADDON_SHELL__.run());
+            await page.waitForTimeout(1000);
+            result.clipboard = await page.evaluate(() => navigator.clipboard.readText()).catch(() => undefined);
+        }
+        const status = await page.evaluate(() => {
+            const shell = window.__AYON_ADDON_SHELL__;
+            return shell && { fixture: shell.fixture(), unmatched: shell.unmatched, used: shell.used };
+        });
+        result.context = status?.fixture?.context;
+        if (mode === 'preview')
+            result.unmatched = status?.unmatched;
+        // without the box's icon name
+        result.contributionErrors = (await page.locator('.ayon-addon-error').allInnerTexts()).map((text) => text.replace(/^error\s+/, ''));
+        result.toasts = await page.locator('.Toastify__toast').allInnerTexts();
+        if (options.prune && options.fixture && status && !status.unmatched.length) {
+            const file = path.join(options.root, 'dev', 'fixtures', `${options.fixture}.json`);
+            const fixture = JSON.parse(readFileSync(file, 'utf8'));
+            const keys = Object.keys(fixture.responses);
+            fixture.responses = Object.fromEntries(keys.filter((key) => status.used.includes(key)).map((key) => [key, fixture.responses[key]]));
+            writeFileSync(file, `${JSON.stringify(fixture, null, 2)}\n`);
+            result.pruned = keys.length - Object.keys(fixture.responses).length;
+        }
+        if (options.saveFixture && status?.fixture) {
+            const file = path.join(options.root, 'dev', 'fixtures', `${options.saveFixture}.json`);
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, `${JSON.stringify(status.fixture, null, 2)}\n`);
+            result.savedFixture = path.relative(options.root, file);
+        }
+        if (options.screenshot) {
+            const file = path.resolve(options.root, options.screenshot);
+            mkdirSync(path.dirname(file), { recursive: true });
+            await page.screenshot({ path: file });
+            result.screenshot = file;
+        }
+    }
+    finally {
+        await browser.close();
+        await server?.close();
+    }
+    // a failed contribution logs an "[addon <name>]" error (ContributionView, runContribution)
+    const addonErrors = result.errors.filter((error) => error.startsWith('[addon '));
+    result.ok =
+        ready &&
+            !!result.context &&
+            result.contributionErrors.length === 0 &&
+            addonErrors.length === 0 &&
+            !(result.unmatched?.length);
+    return result;
+};
+export const formatBrowse = (result) => [
+    `${result.ok ? 'ok' : 'FAILED'}: ${result.slot} ${result.id} (${result.mode}) ${result.url}`,
+    ...result.contributionErrors.map((error) => `  error box: ${error}`),
+    ...result.errors.map((error) => `  console error: ${error.split('\n')[0]}`),
+    ...result.toasts.map((toast) => `  toast: ${toast}`),
+    ...(result.clipboard ? [`  clipboard: ${result.clipboard}`] : []),
+    ...(result.unmatched || []).map((key) => `  not in the fixture: ${key}`),
+    ...(result.savedFixture ? [`  saved ${result.savedFixture}`] : []),
+    ...(result.pruned !== undefined ? [`  pruned ${result.pruned} unused answers from the fixture`] : []),
+    ...(result.screenshot ? [`  screenshot ${result.screenshot}`] : []),
+].join('\n');

package/dist/check.d.ts

@@ -0,0 +1,30 @@
+export interface CheckResult {
+    ok: boolean;
+    addon: {
+        name: string;
+        version: string;
+    };
+    manifest: string;
+    sdkVersion?: string;
+    contributions: {
+        slot: string;
+        id: string;
+        key: string;
+        pieces: Record<string, string | null>;
+    }[];
+    problems: {
+        slot?: string;
+        id?: string;
+        reason: string;
+    }[];
+    types?: {
+        ok: boolean;
+        errors: string[];
+    };
+}
+export declare const checkAddon: ({ root, manifest, types, }?: {
+    root?: string;
+    manifest?: string;
+    types?: boolean;
+}) => Promise<CheckResult>;
+export declare const formatCheck: (result: CheckResult) => string;

package/dist/check.js

@@ -0,0 +1,117 @@
+// `ayon-addon check`: the manifest the way AYON reads it (slots, ids, fields, pieces), that every
+// piece's file exists, and the addon's types.
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { importFromProject, installedVersion, readAddonProject } from './project.js';
+const EXTENSIONS = ['', '.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx', '/index.js'];
+// a piece is `() => import('./File')`: find the file it imports
+const pieceFile = (root, manifestDir, piece) => {
+    if (typeof piece !== 'function')
+        return undefined;
+    const specifier = String(piece).match(/import\(\s*["'`]([^"'`]+)["'`]\s*\)/)?.[1];
+    if (!specifier)
+        return null;
+    const base = specifier.startsWith('@/')
+        ? path.join(root, 'src', specifier.slice(2))
+        : path.resolve(manifestDir, specifier);
+    const found = EXTENSIONS.map((ext) => base + ext).find((file) => existsSync(file));
+    return found ? path.relative(root, found) : `missing: ${specifier}`;
+};
+// bundles the manifest without its pieces (dynamic imports stay imports) and imports it
+const loadManifest = async (root, manifestPath) => {
+    const vite = await importFromProject(root, 'vite');
+    const output = await vite.build({
+        root,
+        configFile: false,
+        logLevel: 'silent',
+        resolve: { alias: { '@': path.join(root, 'src') } },
+        plugins: [
+            {
+                name: 'ayon-addon:check',
+                resolveDynamicImport: (specifier) => typeof specifier === 'string' ? { id: specifier, external: true } : null,
+            },
+        ],
+        build: { ssr: manifestPath, write: false, minify: false, rollupOptions: { output: { format: 'es' } } },
+    });
+    const outputs = (Array.isArray(output) ? output : [output]);
+    const entry = outputs.flatMap((o) => o.output).find((chunk) => chunk.type === 'chunk' && chunk.isEntry);
+    if (!entry?.code)
+        throw new Error(`could not build ${manifestPath}`);
+    const dir = path.join(root, 'node_modules', '.ayon-addon');
+    mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'manifest-check.mjs');
+    writeFileSync(file, entry.code);
+    const module = await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+    return module.default;
+};
+const typeCheck = (root) => {
+    const require = createRequire(path.join(root, 'package.json'));
+    const tsc = require.resolve('typescript/bin/tsc');
+    const result = spawnSync(process.execPath, [tsc, '--noEmit', '-p', path.join(root, 'tsconfig.json')], {
+        cwd: root,
+        encoding: 'utf8',
+    });
+    const errors = `${result.stdout}${result.stderr}`
+        .split('\n')
+        .filter((line) => / error TS\d+/.test(line));
+    return { ok: result.status === 0, errors };
+};
+export const checkAddon = async ({ root = process.cwd(), manifest = 'src/manifest.ts', types = true, } = {}) => {
+    const project = readAddonProject(root);
+    const manifestPath = path.resolve(root, manifest);
+    const result = {
+        ok: true,
+        addon: { name: project.name, version: project.version },
+        manifest,
+        contributions: [],
+        problems: [],
+    };
+    const sdk = await importFromProject(root, '@ynput/ayon-addon/check');
+    result.sdkVersion = installedVersion(root, '@ynput/ayon-addon');
+    let loaded;
+    try {
+        loaded = await loadManifest(root, manifestPath);
+    }
+    catch (error) {
+        result.problems.push({ reason: `the manifest failed to load: ${error.message}` });
+    }
+    if (loaded !== undefined) {
+        const { contributions, skipped } = sdk.checkManifest({ name: project.name, version: project.version, remote: 'check' }, loaded);
+        result.problems.push(...skipped.map(({ slot, id, reason }) => ({ slot, id, reason })));
+        for (const contribution of contributions) {
+            const definition = sdk.SLOTS[contribution.slot];
+            const pieceNames = [...definition.pieces, ...(definition.optionalPieces || [])];
+            const pieces = {};
+            for (const name of pieceNames) {
+                const file = pieceFile(root, path.dirname(manifestPath), contribution[name]);
+                if (file === undefined)
+                    continue;
+                pieces[name] = file;
+                if (file?.startsWith('missing:')) {
+                    result.problems.push({ slot: contribution.slot, id: contribution.id, reason: `${name}: ${file}` });
+                }
+            }
+            result.contributions.push({ slot: contribution.slot, id: contribution.id, key: contribution.key, pieces });
+        }
+    }
+    if (types)
+        result.types = typeCheck(root);
+    result.ok = !result.problems.length && result.types?.ok !== false;
+    return result;
+};
+export const formatCheck = (result) => {
+    const lines = [
+        `${result.addon.name} ${result.addon.version}, ${result.manifest} (@ynput/ayon-addon ${result.sdkVersion})`,
+        ...result.contributions.map((c) => `  ok  ${c.slot.padEnd(30)} ${c.id.padEnd(24)} ${Object.values(c.pieces).filter(Boolean).join(', ')}`),
+        ...result.problems.map((p) => `  !!  ${(p.slot || '').padEnd(30)} ${(p.id || '').padEnd(24)} ${p.reason}`),
+    ];
+    if (result.types) {
+        lines.push(result.types.ok ? '  ok  types' : `  !!  types: ${result.types.errors.length} errors`);
+        lines.push(...result.types.errors.slice(0, 20).map((e) => `      ${e}`));
+    }
+    lines.push(result.ok ? 'check passed' : 'check failed');
+    return lines.join('\n');
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};