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

package/dist/cli.js

@@ -0,0 +1,249 @@
+#!/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 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 { 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 { generateRest } from './rest.js';
+import { STANDALONE_ENV } from './standalone.js';
+const argv = process.argv.slice(2);
+const command = argv[0];
+const flag = (name) => argv.includes(`--${name}`);
+const option = (name, fallback) => {
+    const index = argv.indexOf(`--${name}`);
+    return index >= 0 ? argv[index + 1] : fallback;
+};
+const json = flag('json');
+const print = (value, text) => console.log(json ? JSON.stringify(value, null, 2) : text);
+const root = process.cwd();
+const CONTENT_TYPES = {
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.map': 'application/json',
+    '.html': 'text/html',
+    '.svg': 'image/svg+xml',
+    '.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',
+    });
+    createReadStream(file).pipe(response);
+}).listen(port);
+// the build's dev info (dist/modules/<remote>/ayon-addon.json), written by ayonAddon()
+const findDevInfo = () => {
+    const modules = path.join(root, 'dist', 'modules');
+    if (!existsSync(modules))
+        return undefined;
+    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')) };
+};
+// the Vite dev server with the dev shell (ayonAddon()'s standalone plugin)
+const devStandalone = async () => {
+    const project = readAddonProject(root);
+    const connection = findConnection(root);
+    const vite = await importFromProject(root, 'vite');
+    process.env[STANDALONE_ENV] = '1';
+    const server = await vite.createServer({
+        root,
+        server: { port: Number(option('port', '5174')) },
+    });
+    await server.listen();
+    const url = server.resolvedUrls.local[0];
+    print({ url, addon: project.name, server: connection.serverUrl, signedInWithKey: !!connection.apiKey }, [
+        `${project.name} ${project.version}: dev shell at ${url}`,
+        `AYON: ${connection.serverUrl}, ${connection.apiKey ? `signed in with the key from ${connection.apiKeySource}` : 'sign in on the page'}`,
+        'Preview without a server: ?preview=<fixture> (dev/fixtures/<fixture>.json)',
+    ].join('\n'));
+};
+const dev = async () => {
+    // the dev shell is the default; --standalone is still accepted, as that default
+    if (!flag('ayon'))
+        return devStandalone();
+    const port = Number(option('port', '5173'));
+    const project = readAddonProject(root);
+    const vite = await importFromProject(root, 'vite');
+    process.env.AYON_ADDON_DEV = '1';
+    let served = false;
+    const watcher = (await vite.build({
+        root,
+        mode: 'development',
+        build: { watch: {} },
+        logLevel: 'warn',
+    }));
+    watcher.on('event', (event) => {
+        if (event.code === 'ERROR')
+            console.error(event.error);
+        if (event.code !== 'END')
+            return;
+        const built = findDevInfo();
+        if (!built) {
+            console.error('no ayon-addon.json in dist/modules: is ayonAddon() in vite.config.ts?');
+            return;
+        }
+        if (served) {
+            if (!json)
+                console.log(`rebuilt (build ${built.info.buildId})`);
+            return;
+        }
+        served = true;
+        serveDirectory(built.dir, port);
+        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'));
+    });
+};
+const slots = async () => {
+    const pkgDir = findPackageDir(root, '@ynput/ayon-addon');
+    if (!pkgDir)
+        throw new Error('@ynput/ayon-addon is not installed here');
+    const data = JSON.parse(readFileSync(path.join(pkgDir, 'dist', 'slots.json'), 'utf8'));
+    const text = [
+        `@ynput/ayon-addon ${data.version}: ${data.slots.length} slots (details: node_modules/@ynput/ayon-addon/AGENTS.md)`,
+        ...data.slots.map((s) => `  ${s.name.padEnd(30)} ${s.helper.padEnd(28)} ${s.loads.padEnd(18)} ${s.where}`),
+    ].join('\n');
+    print(data, text);
+};
+const check = async () => {
+    const result = await checkAddon({ root, manifest: option('manifest'), types: !flag('no-types') });
+    print(result, formatCheck(result));
+    process.exitCode = result.ok ? 0 : 1;
+};
+// ayonAddon({ rest }) in the addon's vite.config.ts
+const readRestOptions = async () => {
+    const vite = await importFromProject(root, 'vite');
+    const loaded = await vite.loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, root);
+    const flatten = async (plugins) => {
+        const value = await plugins;
+        return Array.isArray(value) ? (await Promise.all(value.map(flatten))).flat() : [value];
+    };
+    const plugin = (await flatten(loaded?.config.plugins ?? [])).find((item) => item?.name === 'ayon-addon');
+    return plugin?.api?.options?.rest ?? {};
+};
+const generateRestCommand = async () => {
+    const result = await generateRest({
+        root,
+        rest: await readRestOptions(),
+        schemaFile: option('schema'),
+        hooks: flag('hooks'),
+        interactive: !json && !!process.stdin.isTTY,
+        log: (line) => !json && console.log(line),
+    });
+    if (json)
+        print(result, '');
+};
+// the arguments that aren't flags or flag values
+const BOOLEAN_FLAGS = ['--json', '--run', '--no-types', '--standalone', '--ayon', '--prune', '--hooks'];
+const positional = () => {
+    const values = [];
+    for (let i = 1; i < argv.length; i++) {
+        if (!argv[i].startsWith('--'))
+            values.push(argv[i]);
+        else if (!BOOLEAN_FLAGS.includes(argv[i]))
+            i++;
+    }
+    return values;
+};
+const browseCommand = (mode) => async () => {
+    const [slot, id] = positional();
+    if (!slot || !id)
+        throw new Error(`usage: ayon-addon ${command} <slot> <id> (see ayon-addon help)`);
+    const fixture = option('fixture');
+    if (mode === 'preview' && !fixture)
+        throw new Error('preview needs --fixture <name>');
+    const result = await browse({
+        root,
+        slot,
+        id,
+        fixture: mode === 'preview' ? fixture : undefined,
+        project: option('project'),
+        entities: option('entities'),
+        page: option('page'),
+        url: option('url'),
+        screenshot: option('screenshot'),
+        run: flag('run'),
+        saveFixture: option('save-fixture'),
+        prune: flag('prune'),
+        timeout: option('timeout') ? Number(option('timeout')) : undefined,
+    });
+    print(result, formatBrowse(result));
+    process.exitCode = result.ok ? 0 : 1;
+};
+const HELP = `ayon-addon: tools for AYON addon frontends (run in the addon's frontend folder)
+
+  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
+  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]
+       [--run] [--screenshot <file>] [--save-fixture <name>] [--url <dev shell>] [--json]
+                               render one contribution in the dev shell, headless, and report
+                               errors, toasts, its context (and the clipboard with --run)
+  preview <slot> <id> --fixture <name> [--run] [--prune] [--screenshot <file>] [--json]
+                               the same from dev/fixtures/<name>.json, without a server;
+                               --prune drops the answers the preview didn't use
+  generate-rest [--schema <file>] [--hooks] [--json]
+                               the addon's server endpoints (its OpenAPI schema, downloaded
+                               from a server with this version installed) as RTK Query
+                               endpoints in AYON's api: src/api/generated/<name>.ts, never
+                               edited. Creates src/api/<name>.ts to enhance them and export
+                               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.`;
+const commands = {
+    dev,
+    slots,
+    check,
+    open: browseCommand('live'),
+    preview: browseCommand('preview'),
+    'generate-rest': generateRestCommand,
+};
+const run = commands[command];
+if (!run) {
+    console.log(HELP);
+    process.exitCode = command && command !== 'help' ? 1 : 0;
+}
+else {
+    run().catch((error) => {
+        console.error(json ? JSON.stringify({ ok: false, error: String(error) }) : error);
+        process.exitCode = 1;
+    });
+}

package/dist/eslint.d.ts

@@ -0,0 +1,13 @@
+export declare const ayonAddonLint: {
+    name: string;
+    files: string[];
+    rules: {
+        'no-restricted-imports': (string | {
+            paths: {
+                name: string;
+                message: string;
+            }[];
+        })[];
+    };
+}[];
+export default ayonAddonLint;

package/dist/eslint.js

@@ -0,0 +1,47 @@
+// Lint preset for addon frontends: imports that would bypass AYON's own copies.
+//   import { ayonAddonLint } from '@ynput/ayon-addon-dev/eslint'
+//   export default defineConfig([..., ...ayonAddonLint])
+const viaAddonApi = (name, what) => ({
+    name,
+    message: `Import ${what} from @ynput/ayon-addon: it is AYON's copy, so it works in every slot.`,
+});
+export const ayonAddonLint = [
+    {
+        name: 'ayon-addon/imports',
+        files: ['**/*.{ts,tsx,js,jsx}'],
+        rules: {
+            'no-restricted-imports': [
+                'error',
+                {
+                    paths: [
+                        viaAddonApi('react-router-dom', 'the router hooks and Link'),
+                        viaAddonApi('react-router', 'the router hooks and Link'),
+                        viaAddonApi('react-toastify', 'toast'),
+                        {
+                            name: '@ynput/ayon-addon/host',
+                            message: '@ynput/ayon-addon/host is for AYON itself, not for addons.',
+                        },
+                    ],
+                },
+            ],
+        },
+    },
+    {
+        name: 'ayon-addon/manifest',
+        files: ['**/manifest.{ts,tsx,js}'],
+        rules: {
+            'no-restricted-imports': [
+                'error',
+                {
+                    paths: [
+                        {
+                            name: '@ynput/ayon-addon',
+                            message: 'The manifest imports from @ynput/ayon-addon/manifest (bundled into the addon), so it loads on older AYON versions too.',
+                        },
+                    ],
+                },
+            ],
+        },
+    },
+];
+export default ayonAddonLint;

package/dist/project.d.ts

@@ -0,0 +1,28 @@
+export interface AddonProject {
+    /** the frontend folder (where package.json and vite.config.ts are) */
+    root: string;
+    /** addon name and version from the addon's package.py (one folder up), else package.json */
+    name: string;
+    version: string;
+}
+export declare const readAddonProject: (root?: string) => AddonProject;
+export interface AyonConnection {
+    serverUrl: string;
+    /** sent as x-api-key: the app runs as that (service) user, without a login page */
+    apiKey?: string;
+    /** where the key came from, for messages */
+    apiKeySource?: string;
+}
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare const importFromProject: <T>(root: string, specifier: string) => Promise<T>;
+/** Where a package is installed for the addon (node_modules lookup, no exports needed). */
+export declare const findPackageDir: (root: string, pkgName: string) => string | undefined;
+export declare const installedVersion: (root: string, pkgName: string) => string | undefined;

package/dist/project.js

@@ -0,0 +1,97 @@
+// 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 { createRequire } from 'module';
+import path from 'path';
+import { pathToFileURL } from 'url';
+const pyString = (source, key) => source.match(new RegExp(`^${key}\\s*=\\s*["']([^"']+)["']`, 'm'))?.[1];
+export const readAddonProject = (root = process.cwd()) => {
+    const packagePy = path.resolve(root, '..', 'package.py');
+    if (existsSync(packagePy)) {
+        const source = readFileSync(packagePy, 'utf8');
+        const name = pyString(source, 'name');
+        const version = pyString(source, 'version');
+        if (name && version)
+            return { root, name, version };
+    }
+    const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return { root, name: pkg.name, version: pkg.version };
+};
+// the AYON dev workbench keeps the local stack's service key in data/local-api-key
+const findWorkbench = (from) => {
+    let dir = path.resolve(from);
+    while (dir !== path.dirname(dir)) {
+        if (existsSync(path.join(dir, 'data', 'local-api-key')) && existsSync(path.join(dir, 'mani.yaml')))
+            return dir;
+        dir = path.dirname(dir);
+    }
+    return undefined;
+};
+const workbenchServerPort = (workbench) => {
+    const env = path.join(workbench, '.env');
+    const port = existsSync(env) && readFileSync(env, 'utf8').match(/^SERVER_PORT=(\d+)/m)?.[1];
+    return port || '5100';
+};
+/**
+ * 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 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');
+    if (process.env.AYON_API_KEY) {
+        return { serverUrl, apiKey: process.env.AYON_API_KEY, apiKeySource: 'AYON_API_KEY' };
+    }
+    // another server named explicitly: never send it the local stack's key
+    if (workbench && !process.env.AYON_SERVER_URL && !process.env.SERVER_URL) {
+        const keyFile = path.join(workbench, 'data', 'local-api-key');
+        return { serverUrl, apiKey: readFileSync(keyFile, 'utf8').trim(), apiKeySource: keyFile };
+    }
+    return { serverUrl };
+};
+/**
+ * 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.
+ */
+export const importFromProject = async (root, specifier) => {
+    const require = createRequire(path.join(root, 'package.json'));
+    let resolved;
+    try {
+        resolved = require.resolve(specifier);
+    }
+    catch {
+        // ESM-only packages: read their package.json
+        const [scope, name, ...rest] = specifier.split('/');
+        const pkgName = scope.startsWith('@') ? `${scope}/${name}` : scope;
+        const sub = (scope.startsWith('@') ? rest : [name, ...rest]).filter(Boolean).join('/');
+        let dir = root;
+        while (!existsSync(path.join(dir, 'node_modules', pkgName, 'package.json'))) {
+            if (dir === path.dirname(dir))
+                throw new Error(`${specifier} is not installed in ${root}`);
+            dir = path.dirname(dir);
+        }
+        const pkgDir = path.join(dir, 'node_modules', pkgName);
+        const pkg = JSON.parse(readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+        const entry = pkg.exports?.[sub ? `./${sub}` : '.'];
+        const target = typeof entry === 'string' ? entry : entry?.import ?? entry?.default ?? pkg.module ?? pkg.main;
+        resolved = path.join(pkgDir, target);
+    }
+    return import(pathToFileURL(resolved).href);
+};
+/** Where a package is installed for the addon (node_modules lookup, no exports needed). */
+export const findPackageDir = (root, pkgName) => {
+    let dir = root;
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.join(dir, 'node_modules', pkgName);
+        if (existsSync(path.join(candidate, 'package.json')))
+            return candidate;
+        dir = path.dirname(dir);
+    }
+    return undefined;
+};
+export const installedVersion = (root, pkgName) => {
+    const dir = findPackageDir(root, pkgName);
+    return dir && JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
+};

package/dist/rest.d.ts

@@ -0,0 +1,47 @@
+/** `rest` in ayonAddon(): where `ayon-addon generate-rest` writes, and what it can't tell itself. */
+export interface RestOptions {
+    /** the generated endpoints, never edited (default src/api/generated/<name>.ts) */
+    generated?: string;
+    /** the file that enhances them and exports their hooks (default src/api/<name>.ts) */
+    api?: string;
+    /** the module whose default export is the addon version (default src/addonVersion.ts) */
+    versionModule?: string;
+    /** the downloaded schema (default gen/openapi.json) */
+    schema?: string;
+    /** endpoints that are POST but only read, generated as queries: `timetrackerQueryTimeLogs` */
+    queries?: string[];
+}
+export interface GenerateRestOptions {
+    root: string;
+    rest: RestOptions;
+    /** generate from this schema file instead of downloading it */
+    schemaFile?: string;
+    /** add missing hooks without asking */
+    hooks?: boolean;
+    /** may ask in the terminal */
+    interactive: boolean;
+    log: (line: string) => void;
+}
+export interface GenerateRestResult {
+    url?: string;
+    schema: string;
+    generated: string;
+    api: string;
+    endpoints: {
+        name: string;
+        type: 'query' | 'mutation';
+    }[];
+    /** the enhanced api file was created */
+    created: boolean;
+    /** hooks added to the enhanced api file */
+    addedHooks: string[];
+    /** hooks of endpoints the enhanced api file doesn't export */
+    missingHooks: string[];
+    /** hooks the enhanced api file exports for endpoints that are gone */
+    staleHooks: string[];
+}
+export declare const hookName: ({ name, type }: {
+    name: string;
+    type: "query" | "mutation";
+}) => string;
+export declare const generateRest: (options: GenerateRestOptions) => Promise<GenerateRestResult>;

package/dist/rest.js

@@ -0,0 +1,181 @@
+// `ayon-addon generate-rest`: the addon's server endpoints as RTK Query endpoints injected into
+// AYON's api (they share its cache), from the OpenAPI schema of the installed addon.
+//   1. downloads /api/addons/<name>/<version>/openapi.json (AYON's own /openapi.json has no addon
+//      routes) to gen/openapi.json, with operation ids prefixed by the addon name
+//   2. generates the endpoints with @rtk-query/codegen-openapi, without hooks
+//   3. puts addonVersion in the URLs, so they call the version that is running
+//   4. creates the file that enhances them (tags, optimistic updates) and exports their hooks, or
+//      adds the hooks of new endpoints to it. The generated file is never edited by hand.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+import { createInterface } from 'readline/promises';
+import { findConnection, importFromProject, readAddonProject } 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) => {
+    const relative = path.relative(path.dirname(from), to).replace(/\\/g, '/').replace(/\.tsx?$/, '');
+    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 url = `${serverUrl}/api/addons/${addon.name}/${addon.version}/openapi.json`;
+    const response = await fetch(url, { headers: apiKey ? { 'x-api-key': apiKey } : {} });
+    if (!response.ok) {
+        throw new Error(`${url} answered ${response.status}: is ${addon.name} ${addon.version} installed there?`);
+    }
+    return { url, schema: (await response.json()) };
+};
+// Every addon injects into AYON's one api: prefixed operation ids (timetrackerStartSession) can't
+// clash with AYON's or another addon's endpoints.
+const patchSchema = (schema, prefix) => {
+    for (const operations of Object.values(schema.paths)) {
+        for (const operation of Object.values(operations)) {
+            if (operation.operationId && !operation.operationId.startsWith(`${prefix}_`))
+                operation.operationId = `${prefix}_${operation.operationId}`;
+            // optional headers are typed string | null, which fetch's headers don't take: a header is
+            // either sent or not (AYON's own schema types them as string)
+            for (const parameter of operation.parameters ?? []) {
+                const types = parameter.in === 'header' ? parameter.schema?.anyOf : undefined;
+                if (types?.some((type) => type.type === 'null')) {
+                    const rest = { ...parameter.schema };
+                    delete rest.anyOf;
+                    parameter.schema = { ...rest, ...types.find((type) => type.type !== 'null') };
+                }
+            }
+        }
+    }
+    return schema;
+};
+const readEndpoints = (source) => [...source.matchAll(/^\s*(\w+): build\.(query|mutation)</gm)].map(([, name, type]) => ({
+    name,
+    type: type,
+}));
+const apiFileContent = (addonName, apiExport, generatedExport, generatedImport, hooks) => `// ${addonName}'s server endpoints. They are generated into ${generatedImport}.ts by
+// \`ayon-addon generate-rest\`: never edit that file, change them here instead (cache tags,
+// transformResponse, optimistic updates). generate-rest offers to add the hooks of new endpoints.
+import { ${generatedExport} } from "${generatedImport}";
+
+export const ${apiExport} = ${generatedExport}.enhanceEndpoints({
+  addTagTypes: [],
+  endpoints: {},
+});
+
+export const {
+${hooks.map((hook) => `  ${hook},`).join('\n')}
+} = ${apiExport};
+`;
+const confirm = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} (Y/n) `)).trim().toLowerCase();
+        return answer === '' || answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+};
+export const generateRest = async (options) => {
+    const { root, rest, log } = options;
+    const addon = readAddonProject(root);
+    const id = camel(addon.name);
+    const resolve = (file) => path.resolve(root, file);
+    const generated = resolve(rest.generated || `src/api/generated/${addon.name}.ts`);
+    const apiFile = resolve(rest.api || `src/api/${addon.name}.ts`);
+    const versionModule = resolve(rest.versionModule || 'src/addonVersion.ts');
+    const generatedExport = `${id}RestApi`;
+    const apiExport = `${id}Api`;
+    // 1. the schema
+    let schema = resolve(options.schemaFile || rest.schema || 'gen/openapi.json');
+    let url;
+    if (!options.schemaFile) {
+        const download = await downloadSchema(root, addon);
+        url = download.url;
+        mkdirSync(path.dirname(schema), { recursive: true });
+        writeFileSync(schema, JSON.stringify(patchSchema(download.schema, addon.name), null, 2));
+        log(`${path.relative(root, schema)}: ${Object.keys(download.schema.paths).length} paths from ${url}`);
+    }
+    else {
+        schema = resolve(options.schemaFile);
+        const patched = patchSchema(JSON.parse(readFileSync(schema, 'utf8')), addon.name);
+        writeFileSync(schema, JSON.stringify(patched, null, 2));
+    }
+    // 2. the endpoints
+    const { generateEndpoints } = await importFromProject(root, '@rtk-query/codegen-openapi').catch(() => {
+        throw new Error('generate-rest needs @rtk-query/codegen-openapi: yarn add -D @rtk-query/codegen-openapi');
+    });
+    const queries = new Set(rest.queries ?? []);
+    mkdirSync(path.dirname(generated), { recursive: true });
+    await generateEndpoints({
+        schemaFile: schema,
+        apiFile: '@ynput/ayon-frontend-shared/api',
+        apiImport: 'api',
+        exportName: generatedExport,
+        outputFile: generated,
+        hooks: false,
+        // the addon's endpoints only
+        filterEndpoints: (_name, operation) => operation.path.startsWith(`/api/addons/${addon.name}/`),
+        endpointOverrides: queries.size ? [{ pattern: [...queries], type: 'query' }] : undefined,
+    });
+    // 3. the running version in the URLs
+    let source = readFileSync(generated, 'utf8');
+    source = source.replace(new RegExp(`/api/addons/${addon.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/[^/\`]+/`, 'g'), `/api/addons/${addon.name}/\${addonVersion}/`);
+    source =
+        `// Generated by \`ayon-addon generate-rest\` from the addon's OpenAPI schema. Do not edit:\n` +
+            `// enhance the endpoints in ${posixRelative(generated, apiFile)}.ts instead.\n` +
+            `import addonVersion from "${posixRelative(generated, versionModule)}";\n` +
+            source;
+    writeFileSync(generated, source);
+    const endpoints = readEndpoints(source);
+    log(`${path.relative(root, generated)}: ${endpoints.length} endpoints`);
+    // 4. the enhanced api and its hooks
+    const hooks = endpoints.map(hookName);
+    const result = {
+        url,
+        schema,
+        generated,
+        api: apiFile,
+        endpoints,
+        created: false,
+        addedHooks: [],
+        missingHooks: [],
+        staleHooks: [],
+    };
+    if (!existsSync(apiFile)) {
+        mkdirSync(path.dirname(apiFile), { recursive: true });
+        writeFileSync(apiFile, apiFileContent(addon.name, apiExport, generatedExport, posixRelative(apiFile, generated), hooks));
+        result.created = true;
+        result.addedHooks = hooks;
+        log(`${path.relative(root, apiFile)}: created, enhance the endpoints there`);
+        return result;
+    }
+    const apiSource = readFileSync(apiFile, 'utf8');
+    const exported = (hook) => new RegExp(`\\b${hook}\\b`).test(apiSource);
+    result.missingHooks = hooks.filter((hook) => !exported(hook));
+    const known = new Set(hooks);
+    result.staleHooks = [...new Set(apiSource.match(new RegExp(`\\buse${capitalize(id)}\\w+(Query|Mutation)\\b`, 'g')))]
+        .filter((hook) => !hook.startsWith('useLazy') && !known.has(hook));
+    if (result.staleHooks.length) {
+        log(`${path.relative(root, apiFile)} exports hooks of endpoints that are gone: ${result.staleHooks.join(', ')}`);
+    }
+    if (!result.missingHooks.length)
+        return result;
+    const relative = path.relative(root, apiFile);
+    const add = options.hooks ||
+        (options.interactive &&
+            (await confirm(`Export hooks for ${result.missingHooks.length} new endpoints in ${relative}?`)));
+    if (!add) {
+        log(`${relative} doesn't export: ${result.missingHooks.join(', ')} (add them with --hooks)`);
+        return result;
+    }
+    // a block of its own: the user's exports are left as they are
+    const apiName = apiSource.match(new RegExp(`export const (\\w+) = ${generatedExport}\\b`))?.[1] || apiExport;
+    const block = `\n// added by ayon-addon generate-rest\nexport const {\n${result.missingHooks
+        .map((hook) => `  ${hook},`)
+        .join('\n')}\n} = ${apiName};\n`;
+    writeFileSync(apiFile, apiSource.replace(/\n*$/, '\n') + block);
+    result.addedHooks = result.missingHooks;
+    result.missingHooks = [];
+    log(`${relative}: exported ${result.addedHooks.join(', ')}`);
+    return result;
+};