@vertesia/tools-sdk 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260722.120446Z

package/src/index.ts

@@ -5,6 +5,8 @@ export { copyRuntimeAssets } from './copy-assets.js';
 export * from './InteractionCollection.js';
 export * from './RenderingTemplateCollection.js';
 export * from './SkillCollection.js';
+export type { BuildAppPackageOptions } from './server/app-package.js';
+export { buildAppPackage } from './server/app-package.js';
 export * from './server/types.js';
 export * from './server.js';
 export * from './site/templates.js';

package/src/server/app-package.test.ts

@@ -0,0 +1,140 @@
+import { PromptRole } from '@llumiverse/common';
+import { PROCESS_DEFINITION_FORMAT_VERSION, TemplateType } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { ContentTypesCollection } from '../ContentTypesCollection.js';
+import { InteractionCollection } from '../InteractionCollection.js';
+import { buildAppPackage } from './app-package.js';
+import type { ToolServerConfig } from './types.js';
+
+describe('buildAppPackage', () => {
+    it('builds the same package artifact inventory used by the package route', async () => {
+        const config = {
+            interactions: [
+                new InteractionCollection({
+                    name: 'claims',
+                    interactions: [
+                        {
+                            name: 'review',
+                            title: 'Review Claim',
+                            prompts: [
+                                {
+                                    role: PromptRole.user,
+                                    content: '{{user_prompt}}',
+                                    content_type: TemplateType.handlebars,
+                                },
+                            ],
+                        },
+                    ],
+                }),
+            ],
+            types: [
+                new ContentTypesCollection({
+                    name: 'claims',
+                    types: [
+                        {
+                            name: 'claim',
+                            object_schema: {
+                                type: 'object',
+                                properties: {
+                                    status: { type: 'string' },
+                                },
+                            },
+                        },
+                    ],
+                }),
+            ],
+            processes: [
+                {
+                    id: 'claims:intake',
+                    name: 'Claims Intake',
+                    definition: {
+                        format_version: PROCESS_DEFINITION_FORMAT_VERSION,
+                        process: 'claims_intake',
+                        initial: 'done',
+                        context: {
+                            schema: {
+                                type: 'object',
+                                additionalProperties: true,
+                            },
+                            initial: {},
+                        },
+                        nodes: {
+                            done: { type: 'final', title: 'Done' },
+                        },
+                    },
+                },
+            ],
+            dashboards: [
+                {
+                    id: 'claims:ops',
+                    title: 'Claims Ops',
+                    spec: {},
+                },
+            ],
+            uiConfig: {
+                src: '/lib/plugin.js',
+                available_in: ['app_portal'],
+            },
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, {
+            origin: 'https://apps.example.test',
+            scope: 'all',
+        });
+
+        expect(pkg.interactions?.map((interaction) => interaction.id)).toEqual(['claims:review']);
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim']);
+        expect(pkg.processes?.map((process) => process.id)).toEqual(['claims:intake']);
+        expect(pkg.dashboards?.map((dashboard) => dashboard.id)).toEqual(['claims:ops']);
+        expect(pkg.ui?.src).toBe('https://apps.example.test/lib/plugin.js');
+    });
+
+    it('honors package scopes', async () => {
+        const config = {
+            interactions: [
+                new InteractionCollection({
+                    name: 'claims',
+                    interactions: [{ name: 'review', prompts: [] }],
+                }),
+            ],
+            types: [
+                new ContentTypesCollection({
+                    name: 'claims',
+                    types: [{ name: 'claim' }],
+                }),
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'types' });
+
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim']);
+        expect(pkg.interactions).toBeUndefined();
+    });
+});
+
+describe('buildAppPackage type identity', () => {
+    it('exposes the bare type name as the public id (collections are code organization only)', async () => {
+        const config = {
+            types: [
+                new ContentTypesCollection({ name: 'claims', types: [{ name: 'claim' }] }),
+                new ContentTypesCollection({ name: 'audit', types: [{ name: 'audit_event' }] }),
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'types' });
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim', 'audit_event']);
+    });
+
+    it('fails the package build when a type name is duplicated across collections', async () => {
+        const config = {
+            types: [
+                new ContentTypesCollection({ name: 'claims', types: [{ name: 'claim' }] }),
+                new ContentTypesCollection({ name: 'legacy', types: [{ name: 'claim' }] }),
+            ],
+        } satisfies ToolServerConfig;
+
+        await expect(buildAppPackage(config, { scope: 'types' })).rejects.toThrow(
+            /Duplicate content type name 'claim'/,
+        );
+    });
+});

package/src/server/app-package.ts

@@ -1,4 +1,5 @@
 import type {
+    AppDashboardDefinition,
     AppPackage,
     AppPackageScope,
     AppWidgetInfo,
@@ -15,14 +16,19 @@ function getRequestPayload<T>(c: Context): Promise<T | undefined> {
     return c.req.method === 'POST' ? c.req.json<T>() : Promise.resolve(undefined);
 }
 
-const builders: Record<
-    Exclude<AppPackageScope, 'all'>,
-    (pkg: AppPackage, config: ToolServerConfig, c: Context) => Promise<void>
-> = {
-    async tools(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+export interface BuildAppPackageOptions {
+    scope?: AppPackageScope | AppPackageScope[] | string;
+    origin?: string;
+    toolUseContext?: ToolUseContext;
+}
+
+type AppPackageBuilder = (pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) => Promise<void>;
+
+const builders: Record<Exclude<AppPackageScope, 'all'>, AppPackageBuilder> = {
+    async tools(pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) {
         const { tools: toolCollections = [], skills: skillCollections = [] } = config;
 
-        const filterContext = await getRequestPayload<ToolUseContext>(c);
+        const filterContext = options.toolUseContext;
 
         // Aggregate all tools from all collections
         const allTools = toolCollections.flatMap((collection) => collection.getToolDefinitions(filterContext));
@@ -59,13 +65,23 @@ const builders: Record<
         pkg.interactions = allInteractions;
     },
     async types(pkg: AppPackage, config: ToolServerConfig) {
+        // A type's public id is its BARE name: stored objects reference it as the portable
+        // `app:<app>:<type>` string, so the in-code collection (a code-organization grouping,
+        // unlike tool/skill collections which are semantic) must NOT leak into the id.
+        // Names must therefore be unique across collections — fail the package build otherwise.
         const allTypes: InCodeTypeDefinition[] = [];
+        const seen = new Map<string, string>();
         for (const coll of config.types || []) {
             for (const type of coll.types) {
-                allTypes.push({
-                    ...type,
-                    id: `${coll.name}:${type.name}`,
-                });
+                const existing = seen.get(type.name);
+                if (existing) {
+                    throw new Error(
+                        `Duplicate content type name '${type.name}' (collections '${existing}' and '${coll.name}'). ` +
+                            `Type names must be unique across collections so the portable 'app:<app>:${type.name}' ref resolves.`,
+                    );
+                }
+                seen.set(type.name, coll.name);
+                allTypes.push({ ...type, id: type.name });
             }
         }
         pkg.types = allTypes;
@@ -77,6 +93,9 @@ const builders: Record<
         }
         pkg.processes = allProcesses;
     },
+    async views(pkg: AppPackage, config: ToolServerConfig) {
+        pkg.views = [...(config.views ?? [])];
+    },
     async templates(pkg: AppPackage, config: ToolServerConfig) {
         const basePath = `${config.prefix || '/api'}/templates`;
         pkg.templates = (config.templates || []).flatMap((coll) =>
@@ -86,6 +105,19 @@ const builders: Record<
             })),
         );
     },
+    async dashboards(pkg: AppPackage, config: ToolServerConfig) {
+        const seen = new Set<string>();
+        const dashboards: AppDashboardDefinition[] = [];
+        for (const dashboard of config.dashboards || []) {
+            if (seen.has(dashboard.id)) {
+                console.warn(`[app-package] Duplicate dashboard id "${dashboard.id}", skipping`);
+                continue;
+            }
+            seen.add(dashboard.id);
+            dashboards.push(dashboard);
+        }
+        pkg.dashboards = dashboards;
+    },
     async widgets(pkg: AppPackage, config: ToolServerConfig) {
         const { skills: skillCollections = [] } = config;
         const widgets: Record<string, AppWidgetInfo> = {};
@@ -102,10 +134,10 @@ const builders: Record<
         }
         pkg.widgets = widgets;
     },
-    async ui(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+    async ui(pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) {
         if (config.uiConfig) {
             pkg.ui = { ...config.uiConfig };
-            const origin = new URL(c.req.url).origin;
+            const origin = options.origin || 'http://localhost';
             pkg.ui.src = new URL(pkg.ui.src, origin).toString();
             if (!pkg.ui.isolation) {
                 pkg.ui.isolation = 'shadow';
@@ -128,52 +160,75 @@ const builders: Record<
     },
 };
 
-async function handlePackageRequest(c: Context, config: ToolServerConfig) {
-    const scope = c.req.query('scope') || 'all';
+function normalizeScopes(scope: BuildAppPackageOptions['scope']): Set<AppPackageScope> {
+    const values = Array.isArray(scope) ? scope : typeof scope === 'string' ? scope.split(',') : [scope || 'all'];
+    return new Set(values.filter(Boolean) as AppPackageScope[]);
+}
+
+export async function buildAppPackage(
+    config: ToolServerConfig,
+    options: BuildAppPackageOptions = {},
+): Promise<AppPackage> {
     const pkg: AppPackage = {};
 
-    const scopes = new Set<AppPackageScope>(scope.split(',') as AppPackageScope[]);
-    // TODO build pkg based on the query param scope
+    const scopes = normalizeScopes(options.scope);
     if (scopes.has('all')) {
-        await builders.tools(pkg, config, c);
-        await builders.interactions(pkg, config, c);
-        await builders.types(pkg, config, c);
-        await builders.processes(pkg, config, c);
-        await builders.templates(pkg, config, c);
-        await builders.widgets(pkg, config, c);
-        await builders.ui(pkg, config, c);
-        await builders.settings(pkg, config, c);
-        await builders.activities(pkg, config, c);
+        await builders.tools(pkg, config, options);
+        await builders.interactions(pkg, config, options);
+        await builders.types(pkg, config, options);
+        await builders.processes(pkg, config, options);
+        await builders.views(pkg, config, options);
+        await builders.templates(pkg, config, options);
+        await builders.dashboards(pkg, config, options);
+        await builders.widgets(pkg, config, options);
+        await builders.ui(pkg, config, options);
+        await builders.settings(pkg, config, options);
+        await builders.activities(pkg, config, options);
     } else {
         if (scopes.has('tools')) {
-            await builders.tools(pkg, config, c);
+            await builders.tools(pkg, config, options);
         }
         if (scopes.has('interactions')) {
-            await builders.interactions(pkg, config, c);
+            await builders.interactions(pkg, config, options);
         }
         if (scopes.has('types')) {
-            await builders.types(pkg, config, c);
+            await builders.types(pkg, config, options);
         }
         if (scopes.has('processes')) {
-            await builders.processes(pkg, config, c);
+            await builders.processes(pkg, config, options);
+        }
+        if (scopes.has('views')) {
+            await builders.views(pkg, config, options);
         }
         if (scopes.has('templates')) {
-            await builders.templates(pkg, config, c);
+            await builders.templates(pkg, config, options);
+        }
+        if (scopes.has('dashboards')) {
+            await builders.dashboards(pkg, config, options);
         }
         if (scopes.has('widgets')) {
-            await builders.widgets(pkg, config, c);
+            await builders.widgets(pkg, config, options);
         }
         if (scopes.has('ui')) {
-            await builders.ui(pkg, config, c);
+            await builders.ui(pkg, config, options);
         }
         if (scopes.has('settings')) {
-            await builders.settings(pkg, config, c);
+            await builders.settings(pkg, config, options);
         }
         if (scopes.has('activities')) {
-            await builders.activities(pkg, config, c);
+            await builders.activities(pkg, config, options);
         }
     }
 
+    return pkg;
+}
+
+async function handlePackageRequest(c: Context, config: ToolServerConfig) {
+    const pkg = await buildAppPackage(config, {
+        scope: c.req.query('scope') || 'all',
+        origin: new URL(c.req.url).origin,
+        toolUseContext: await getRequestPayload<ToolUseContext>(c),
+    });
     return c.json(pkg);
 }
 

package/src/server/content-types.test.ts

@@ -0,0 +1,64 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import { ContentTypesCollection } from '../ContentTypesCollection.js';
+import { createContentTypesRoute } from './content-types.js';
+import type { ToolServerConfig } from './types.js';
+
+function makeApp(config: ToolServerConfig): Hono {
+    const app = new Hono();
+    createContentTypesRoute(app, '/api/types', config);
+    return app;
+}
+
+const config = {
+    types: [
+        new ContentTypesCollection({
+            name: 'contracts',
+            types: [{ name: 'contract' }, { name: 'review_note' }],
+        }),
+        new ContentTypesCollection({
+            name: 'audit',
+            types: [{ name: 'audit_event' }],
+        }),
+    ],
+} satisfies ToolServerConfig;
+
+describe('content types route', () => {
+    it('lists all types with bare ids (collection is not part of the type identity)', async () => {
+        const res = await makeApp(config).request('/api/types');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { types: Array<{ id: string }> };
+        expect(body.types.map((t) => t.id)).toEqual(['contract', 'review_note', 'audit_event']);
+    });
+
+    it('resolves the canonical bare type name (the app:<app>:<type> ref convention)', async () => {
+        const res = await makeApp(config).request('/api/types/contract');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { id: string; name: string };
+        expect(body.id).toBe('contract');
+        expect(body.name).toBe('contract');
+    });
+
+    it('still resolves the legacy collection:type alias, returning the bare id', async () => {
+        const res = await makeApp(config).request('/api/types/contracts:contract');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { id: string };
+        expect(body.id).toBe('contract');
+    });
+
+    it('409s on an ambiguous bare name so the collision is loud, not silent', async () => {
+        const ambiguous = {
+            types: [
+                new ContentTypesCollection({ name: 'a', types: [{ name: 'note' }] }),
+                new ContentTypesCollection({ name: 'b', types: [{ name: 'note' }] }),
+            ],
+        } satisfies ToolServerConfig;
+        const res = await makeApp(ambiguous).request('/api/types/note');
+        expect(res.status).toBe(409);
+    });
+
+    it('404s for an unknown type name', async () => {
+        const res = await makeApp(config).request('/api/types/nope');
+        expect(res.status).toBe(404);
+    });
+});

package/src/server/content-types.ts

@@ -10,13 +10,15 @@ import type { ToolServerConfig } from './types.js';
 export function createContentTypesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
     const { types = [] } = config;
 
-    // GET /api/types - Returns all interactions from all collections
+    // GET /api/types - Returns all content types from all collections.
+    // A type's public id is its declared BARE name, verbatim (`app:<app>:<type>` once
+    // app-prefixed): collections organize code, they are not part of the type identity.
     app.get(basePath, (c) => {
         const allTypes: InCodeTypeDefinition[] = [];
 
         for (const coll of types) {
             for (const type of coll.types) {
-                allTypes.push({ ...type, id: `${coll.name}:${toPathName(type.name)}` });
+                allTypes.push({ ...type, id: type.name });
             }
         }
 
@@ -37,20 +39,51 @@ export function createContentTypesRoute(app: Hono, basePath: string, config: Too
         app.route(`${basePath}/${coll.name}`, createContentTypeEndpoints(coll));
     }
 
-    // GET /api/types/:name - Direct access to content type
+    // GET /api/types/:name - Direct access to content type.
+    // Canonical form is the BARE type name (`<type>`), matching the portable
+    // `app:<app>:<type>` ref convention used by objects.create/search — the
+    // collection is an in-code grouping, not part of the type's public id.
+    // `<collection>:<type>` is also accepted as a backward-compatible alias.
     app.get(`${basePath}/:name`, async (c) => {
         const name = c.req.param('name');
         const parts = name.split(':');
+        if (parts.length === 1) {
+            // Match the declared name verbatim; fall back to the toPathName variant for
+            // leniency with legacy refs that used the path-mangled form.
+            const matches = types.flatMap((coll) =>
+                coll.types
+                    .filter((t) => t.name === name || toPathName(t.name) === name)
+                    .map((t) => ({ coll, type: t })),
+            );
+            if (matches.length === 1) {
+                return c.json({ ...matches[0].type, id: matches[0].type.name });
+            }
+            if (matches.length > 1) {
+                const colls = matches.map((m) => m.coll.name).join(', ');
+                throw new HTTPException(409, {
+                    message:
+                        `Ambiguous content type name '${name}': defined in collections ${colls}. ` +
+                        'Type names must be unique across collections so the portable ' +
+                        `'app:<app>:${name}' ref resolves; rename one of them, or address it as '<collection>:<type>'.`,
+                });
+            }
+            throw new HTTPException(404, {
+                message: `No content type found with name: ${name}`,
+            });
+        }
         if (parts.length !== 2) {
             throw new HTTPException(400, {
-                message: "Invalid content type name. Expected format 'collection:type'",
+                message: "Invalid content type name. Expected '<type>' or 'collection:type'",
             });
         }
         const collName = parts[0];
-        const typeName = toPathName(parts[1]);
-        const ctype = types.find((t) => t.name === collName)?.getTypeByName(typeName);
+        const typeName = parts[1];
+        const ctype = types
+            .find((t) => t.name === collName)
+            ?.types.find((t) => t.name === typeName || toPathName(t.name) === toPathName(typeName));
         if (ctype) {
-            return c.json({ ...ctype, id: `${collName}:${typeName}` });
+            // Alias lookup still returns the canonical bare id.
+            return c.json({ ...ctype, id: ctype.name });
         }
 
         throw new HTTPException(404, {
@@ -63,12 +96,12 @@ function createContentTypeEndpoints(coll: ContentTypesCollection): Hono {
     const endpoint = new Hono();
 
     endpoint.get('/', (c: Context) => {
-        return c.json(coll.types.map((t) => ({ ...t, id: `${coll.name}:${toPathName(t.name)}` })));
+        return c.json(coll.types.map((t) => ({ ...t, id: t.name })));
     });
 
     endpoint.get('/:name', (c: Context) => {
         const name = c.req.param('name');
-        const ctype = coll.types.find((t) => toPathName(t.name) === name);
+        const ctype = coll.types.find((t) => t.name === name || toPathName(t.name) === name);
         if (!ctype) {
             throw new HTTPException(404, {
                 message: `No content type found with name: ${name}`,
@@ -76,7 +109,7 @@ function createContentTypeEndpoints(coll: ContentTypesCollection): Hono {
         }
         return c.json({
             ...ctype,
-            id: `${coll.name}:${toPathName(ctype.name)}`,
+            id: ctype.name,
         });
     });
 

package/src/server/dashboards.ts

@@ -0,0 +1,31 @@
+import type { AppDashboardDefinition } from '@vertesia/common';
+import type { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ToolServerConfig } from './types.js';
+
+export function createDashboardsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { dashboards = [] } = config;
+
+    app.get(basePath, (c) => {
+        return c.json({
+            title: 'All Dashboards',
+            description: 'All available dashboard definitions',
+            dashboards,
+        });
+    });
+
+    app.get(`${basePath}/:id`, (c) => {
+        const id = c.req.param('id');
+        const dashboard = findDashboard(dashboards, id);
+        if (!dashboard) {
+            throw new HTTPException(404, {
+                message: `No dashboard found with id: ${id}`,
+            });
+        }
+        return c.json(dashboard);
+    });
+}
+
+function findDashboard(dashboards: AppDashboardDefinition[], id: string): AppDashboardDefinition | undefined {
+    return dashboards.find((dashboard) => dashboard.id === id || dashboard.name === id || dashboard.title === id);
+}

package/src/server/types.ts

@@ -1,5 +1,11 @@
 import type { JSONSchema } from '@llumiverse/common';
-import type { AppUIConfig, InCodeProcessDefinition, ProjectConfiguration } from '@vertesia/common';
+import type {
+    AppDashboardDefinition,
+    AppUIConfig,
+    InCodeProcessDefinition,
+    InCodeViewDefinition,
+    ProjectConfiguration,
+} from '@vertesia/common';
 import type { Context } from 'hono';
 import type { ActivityCollection } from '../ActivityCollection.js';
 import type { AuthSession } from '../auth.js';
@@ -63,6 +69,14 @@ export interface ToolServerConfig {
      * Process definitions to expose as app-contributed processes.
      */
     processes?: InCodeProcessDefinition[];
+    /**
+     * Dashboard definitions to expose as app-contributed dashboards.
+     */
+    dashboards?: AppDashboardDefinition[];
+    /**
+     * View Experiences to expose as app-contributed in-code definitions.
+     */
+    views?: InCodeViewDefinition[];
     /**
      * Skill collections to expose
      */

package/src/server/views.test.ts

@@ -0,0 +1,45 @@
+import type { InCodeViewDefinition } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { createToolServer } from '../server.js';
+
+const view: InCodeViewDefinition = {
+    id: 'document-library',
+    name: 'document-library',
+    title: 'Document Library',
+    tags: ['content'],
+    definition: {
+        name: 'Document Library',
+        layout: { mode: 'browse' },
+        results: {
+            default_display: 'list',
+            displays: [
+                {
+                    id: 'list',
+                    label: 'List',
+                    type: 'list',
+                    title: { field: 'name' },
+                },
+            ],
+        },
+    },
+};
+
+describe('in-code View app package', () => {
+    it('exposes Views through the package scope and direct resource route', async () => {
+        const app = createToolServer({ views: [view], disableHtml: true });
+        const packageResponse = await app.request('/api/package?scope=views');
+        const directResponse = await app.request('/api/views/document-library');
+
+        expect(packageResponse.status).toBe(200);
+        expect(await packageResponse.json()).toEqual({ views: [view] });
+        expect(directResponse.status).toBe(200);
+        expect(await directResponse.json()).toEqual(view);
+    });
+
+    it('returns 404 for an unknown View', async () => {
+        const app = createToolServer({ views: [view], disableHtml: true });
+        const response = await app.request('/api/views/missing');
+
+        expect(response.status).toBe(404);
+    });
+});

package/src/server/views.ts

@@ -0,0 +1,31 @@
+import type { InCodeViewDefinition } from '@vertesia/common';
+import type { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ToolServerConfig } from './types.js';
+
+export function createViewsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { views = [] } = config;
+
+    app.get(basePath, (c) => {
+        return c.json({
+            title: 'All Views',
+            description: 'All available View Experience definitions',
+            views,
+        });
+    });
+
+    app.get(`${basePath}/:name`, (c) => {
+        const name = c.req.param('name');
+        const view = findView(views, name);
+        if (!view) {
+            throw new HTTPException(404, {
+                message: `No View found with name: ${name}`,
+            });
+        }
+        return c.json(view);
+    });
+}
+
+function findView(views: InCodeViewDefinition[], name: string): InCodeViewDefinition | undefined {
+    return views.find((view) => view.id === name || view.name === name);
+}