@vertesia/common 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260717.131047Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.5.0-dev.20260714.072725Z",
+  "version": "1.5.0-dev.20260717.131047Z",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,7 +17,7 @@
     }
   },
   "devDependencies": {
-    "rolldown": "1.1.3",
+    "rolldown": "1.1.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@vertesia/tsconfig": "0.1.0"
@@ -39,6 +39,7 @@
     "ai",
     "typescript"
   ],
+  "gitHead": "8aaad228827b2927db8e6aa75b27bfac90fec36f",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",

package/src/apikey.ts

@@ -145,6 +145,7 @@ export interface AuthTokenPayload {
               studio: string;
               store: string;
               token?: string;
+              git?: string;
           };
 
     iss: string; //issuer

package/src/apps.ts

@@ -1,4 +1,5 @@
 import type { JSONObject, JSONSchema, ToolDefinition } from '@llumiverse/common';
+import type { AppDashboardDefinition } from './data-platform.js';
 import type { CatalogInteractionRef } from './interaction.js';
 import type { DSLActivityOptions, InCodeProcessDefinition, InCodeTypeDefinition } from './store/index.js';
 
@@ -382,9 +383,301 @@ export interface RemoteActivityDefinition {
     options?: DSLActivityOptions;
 }
 
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates';
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates' | 'dashboards';
+
+/**
+ * Canonical runtime list of {@link AppCapabilities} — the app capabilities Studio
+ * renders/supports. Co-located with the type so TypeScript rejects any drift between
+ * the two. Consumers (publish manifest derivation, etc.) must use this rather than
+ * re-listing the values.
+ */
+export const APP_CAPABILITIES: readonly AppCapabilities[] = [
+    'ui',
+    'tools',
+    'interactions',
+    'types',
+    'processes',
+    'templates',
+    'dashboards',
+];
+
+/**
+ * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
+ * capability refs (`app:<app>:...`) against that version (candidate testing) instead of current.
+ * Resolution-time only; never persisted. Set by the generated app template via client.withAppVersion.
+ */
+export const APP_VERSION_HEADER = 'x-vertesia-app-version';
+/**
+ * The platform-artifact types an app build can be required to create. A finer-grained
+ * counterpart to {@link AppCapabilities}: a single `interactions` capability may comprise
+ * several `interaction` artifacts plus `agent`, `activity`, and `tool` artifacts that
+ * {@link AppCapabilities} folds together. Used by the App Solution Architect manifest and
+ * the publish-time capability gate.
+ */
+export type AppArtifactType =
+    | 'interaction'
+    | 'agent'
+    | 'type'
+    | 'process'
+    | 'template'
+    | 'dashboard'
+    | 'activity'
+    | 'tool';
+
+export const APP_ARTIFACT_TYPES: readonly AppArtifactType[] = [
+    'interaction',
+    'agent',
+    'type',
+    'process',
+    'template',
+    'dashboard',
+    'activity',
+    'tool',
+];
+
+/**
+ * A single platform artifact the App Solution Architect requires the build to create.
+ * `id` is the app-owned in-code id the implementation must register and reference
+ * (e.g. `app:<name>:main:extract-item` for interactions/agents, `app:<name>:<type>` for
+ * types, `app:<name>:<process>` for processes).
+ */
+/**
+ * Build progress for one artifact, maintained by the developer agent as a living checklist:
+ *  - `pending` — defined by the architect, not yet built.
+ *  - `built`   — registered in the package, not yet successfully exercised.
+ *  - `done`    — built AND successfully exercised against real data.
+ * This is the agent's self-reported claim for tracking/handoff; the capability gate verifies
+ * the truth independently via package registration + run/data telemetry and does not trust it.
+ */
+export type AppArtifactStatus = 'pending' | 'built' | 'done';
+
+export const APP_ARTIFACT_STATUSES: readonly AppArtifactStatus[] = ['pending', 'built', 'done'];
+
+export interface AppPlannedArtifact {
+    /** App-owned in-code id the build must register and reference. */
+    id: string;
+    type: AppArtifactType;
+    /** Short human label. */
+    name?: string;
+    /** Why this artifact exists / what it does — carried into the build checklist. */
+    purpose?: string;
+    /**
+     * When false, the artifact is planned but optional: the capability gate warns rather
+     * than blocks if it is missing or never exercised. Defaults to required (true).
+     */
+    required?: boolean;
+    /** Build progress, updated by the developer agent. Defaults to `pending`. */
+    status?: AppArtifactStatus;
+}
+
+/**
+ * Structured result the App Solution Architect emits alongside its prose artifacts — the
+ * machine-readable contract for the build. The implementation MUST create and successfully
+ * exercise every required artifact before preview/publish. Persisted into the app repo as
+ * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the publish-time
+ * capability gate can verify against it deterministically. If the builder finds the plan
+ * wrong or insufficient, the orchestrator relaunches the architect to revise the manifest;
+ * the gate always checks against the latest committed copy.
+ */
+export interface AppCapabilityManifest {
+    /** Artifact-storage ref to the prose architecture spec (e.g. the architecture `.md`). */
+    spec_artifact: string;
+    /** Platform artifacts the build must create. */
+    artifacts: AppPlannedArtifact[];
+    /**
+     * Monotonic revision, starting at 1, bumped each time the architect evolves the manifest for
+     * the SAME app on a later iteration (read the committed manifest, preserve untouched artifacts,
+     * add/modify/remove, then bump). Lets downstream agents tell which contract they are building to.
+     */
+    revision?: number;
+    /**
+     * Newest-first change notes, one entry per revision (what was added/modified/removed and why).
+     * How manifest changes are communicated to downstream agents across iterations.
+     */
+    changelog?: string[];
+    /** Optional free-form notes the architect wants the builder to honor. */
+    notes?: string;
+}
+
+/** Repo-relative path the capability manifest is committed to, read by the publish gate. */
+export const APP_CAPABILITY_MANIFEST_PATH = 'docs/app-capability-manifest.json';
+
 export type AppAvailableIn = 'app_portal' | 'composite_app';
 
+export type AppVersionKind = 'design' | 'preview' | 'published';
+export type AppVersionState = 'ready' | 'failed' | 'expired';
+export type AppVersionTarget = 'static' | 'service';
+export type AppVersionGitRefType = 'branch' | 'tag' | 'commit' | 'detached';
+export type AppBuildIntent = 'preview' | 'publish';
+export type AppBuildTrigger = 'ui' | 'git_push' | 'agent' | 'api';
+
+export interface AppVersionStorage {
+    tenant_id?: string;
+    app_prefix?: string;
+    artifacts_prefix?: string;
+    source_archive?: string;
+    source_git?: AppVersionGitSource;
+    build_prefix?: string;
+    manifest_path?: string;
+    service_archive?: string;
+    live_metadata_path?: string;
+}
+
+export interface AppVersionGitSource {
+    url?: string;
+    remote?: string;
+    /**
+     * The source ref that should be used to reproduce this version. For immutable
+     * app versions this is normally the tag created during preview/publish.
+     */
+    ref?: string;
+    ref_type?: AppVersionGitRefType;
+    branch?: string;
+    tag?: string;
+    commit?: string;
+    dirty?: boolean;
+    pushed?: boolean;
+    push_warning?: string;
+}
+
+export interface AppVersionUrls {
+    live_url?: string;
+    app_url?: string;
+    plugin_url?: string;
+    package_url?: string;
+    internal_preview_url?: string;
+}
+
+export interface AppVersionRecord {
+    id: string;
+    account: string;
+    project: string;
+    app?: string;
+    app_id: string;
+    app_name: string;
+    version_id: string;
+    kind: AppVersionKind;
+    state: AppVersionState;
+    active?: boolean;
+    target?: AppVersionTarget;
+    agent_run_id?: string;
+    sandbox_id?: string;
+    title?: string;
+    description?: string;
+    storage?: AppVersionStorage;
+    urls?: AppVersionUrls;
+    manifest?: Record<string, unknown>;
+    files?: string[];
+    file_count?: number;
+    source_file_count?: number;
+    screenshot_artifact?: string;
+    checks?: string[];
+    created_by?: string;
+    created_at: string;
+    updated_at: string;
+    published_at?: string;
+    checked_at?: string;
+    expires_at?: string;
+}
+
+export interface UpsertAppVersionRequest {
+    app?: string;
+    app_id: string;
+    app_name?: string;
+    version_id: string;
+    kind: AppVersionKind;
+    state?: AppVersionState;
+    active?: boolean;
+    target?: AppVersionTarget;
+    agent_run_id?: string;
+    sandbox_id?: string;
+    title?: string;
+    description?: string;
+    storage?: AppVersionStorage;
+    urls?: AppVersionUrls;
+    manifest?: Record<string, unknown>;
+    files?: string[];
+    file_count?: number;
+    source_file_count?: number;
+    screenshot_artifact?: string;
+    checks?: string[];
+    published_at?: string;
+    checked_at?: string;
+    expires_at?: string;
+}
+
+export interface AppVersionListQuery {
+    app_id?: string;
+    kind?: AppVersionKind;
+    include_expired?: boolean;
+    limit?: number;
+}
+
+export interface ActivateAppVersionResponse {
+    version: AppVersionRecord;
+    app?: AppManifest;
+}
+
+export interface StartAppBuildRequest {
+    /**
+     * Source branch, tag, or commit to build. When omitted, the app source
+     * configuration chooses the dev branch for previews and production branch
+     * for publishes.
+     */
+    source_ref?: string;
+    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
+    intent?: AppBuildIntent;
+    trigger?: AppBuildTrigger;
+    target?: AppVersionTarget;
+    activate?: boolean;
+    title?: string;
+    description?: string;
+}
+
+export interface StartAppBuildResponse {
+    workflow_id: string;
+    run_id: string;
+    app_id: string;
+    intent: AppBuildIntent;
+    source_ref?: string;
+    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
+}
+
+export interface AppBuildWorkflowInput extends StartAppBuildRequest {
+    app_id: string;
+    app_record_id?: string;
+    app_title?: string;
+    app_description?: string;
+    source_git_url?: string;
+}
+
+export interface AppBuildWorkflowResult {
+    app_id: string;
+    version_id: string;
+    kind: Extract<AppVersionKind, 'preview' | 'published'>;
+    state: AppVersionState;
+    source_git?: AppVersionGitSource;
+    urls?: AppVersionUrls;
+    file_count?: number;
+}
+
+export type AppBuildProgressStatus = 'queued' | 'resolving' | 'building' | 'completed' | 'failed';
+
+export interface AppBuildProgress {
+    status: AppBuildProgressStatus;
+    step: string;
+    app_id?: string;
+    version_id?: string;
+    intent?: AppBuildIntent;
+    source_ref?: string;
+    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
+    source_commit?: string;
+    file_count?: number;
+    app_url?: string;
+    error?: string;
+    updated_at: string;
+}
+
 /**
  * Access control policy for an app installation.
  * Declares which access surfaces are gated by per-user ACEs.
@@ -445,6 +738,18 @@ export interface AppManifestData {
      */
     color?: string;
 
+    /**
+     * Optional preview screenshot for the app-management UI, captured by the builder during a
+     * build/QA run. Resolved client-side from the owning agent run's artifact storage, so it
+     * carries both the run id and the artifact path.
+     */
+    preview_screenshot?: {
+        /** Agent run id whose artifact storage holds the screenshot. */
+        agent_run_id: string;
+        /** Artifact path within that storage, e.g. "preview-checks/app-preview-<ts>.png". */
+        artifact: string;
+    };
+
     status: 'beta' | 'stable' | 'deprecated';
 
     /**
@@ -501,6 +806,8 @@ export interface AppManifestData {
      * - interactions
      * - types
      * - processes
+     * - templates
+     * - dashboards
      * - settings
      * - all (the default if no scope is provided)
      *  You can also use comma-separated values to combine scopes (e.g. "ui,tools").
@@ -523,6 +830,13 @@ export interface AppManifestData {
      */
     version?: string;
 
+    /**
+     * Source repository configuration for apps generated and maintained through
+     * AppGen. Branches are mutable deployment lanes; immutable app versions
+     * record their exact source tag/commit in AppVersionRecord.storage.source_git.
+     */
+    source?: AppSourceConfig;
+
     /**
      * Free-form tags used for classification and filtering. Platform apps
      * carry `"system"` so UIs can skip install/uninstall/manage-permission
@@ -538,20 +852,16 @@ export interface AppManifestData {
     access_control?: AppAccessControl;
 }
 
-/**
- * Reserved deployment environment names that may never be used as endpoint
- * override keys. Reserving them prevents a manifest from hijacking auto-resolution
- * on a shared production studio-server (whose `Env.environment` is one of these).
- */
-const RESERVED_ENDPOINT_OVERRIDE_ENVS = new Set(['production', 'preview', 'staging']);
+export interface AppGitSourceConfig {
+    url?: string;
+    default_branch?: string;
+    production_branch?: string;
+    development_branch?: string;
+}
 
-/**
- * Returns true if the given environment name is allowed as an endpoint override key.
- * Any non-empty name is accepted except the reserved shared-deployment names.
- */
-export function isValidEndpointOverrideEnv(envName: string): boolean {
-    if (!envName) return false;
-    return !RESERVED_ENDPOINT_OVERRIDE_ENVS.has(envName.toLowerCase());
+export interface AppSourceConfig {
+    kind: 'git';
+    git?: AppGitSourceConfig;
 }
 
 /**
@@ -569,6 +879,10 @@ export interface Endpoints {
     token?: string;
     /** The browser-facing Studio UI (composable-ui) base URL */
     ui?: string;
+    /** The Smart HTTP app source git server base URL */
+    git?: string;
+    /** The appgen app-gateway base URL (serves published app bundles + their `/api` runtime). */
+    gateway?: string;
 }
 
 /**
@@ -577,7 +891,7 @@ export interface Endpoints {
  * with the unresolved placeholder visible, rather than silently pointing nowhere).
  * Trailing slashes on replacement values are stripped to avoid `//api/...` joins.
  */
-export function substituteEndpoints(url: string, endpoints?: Endpoints): string {
+function substituteEndpoints(url: string, endpoints?: Endpoints): string {
     if (!url || !endpoints) return url;
     return url.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key: string) => {
         const value = (endpoints as Record<string, string | undefined>)[key];
@@ -594,72 +908,55 @@ function trimTrailingSlashes(value: string): string {
     return end === value.length ? value : value.slice(0, end);
 }
 
-/**
- * Resolves the effective endpoint for an app.
- *
- * Order of resolution:
- * 1. If `requestedOverride` matches an `endpoint_overrides` key, use that URL
- *    (caller must verify the user is allowed to use the override).
- * 2. Else if `envName` matches an `endpoint_overrides` key, use that URL
- *    (auto-resolution from the studio-server's deployment env).
- * 3. Otherwise use the main `endpoint`.
- * 4. Apply `{{var}}` substitution using `vars`.
- */
-export function resolveAppEndpoint(
-    manifest: Pick<AppManifestData, 'endpoint' | 'endpoint_overrides'>,
-    envName?: string,
-    vars?: Endpoints,
-    requestedOverride?: string,
-): string | undefined {
-    let raw: string | undefined;
-    if (
-        requestedOverride &&
-        manifest.endpoint_overrides?.[requestedOverride] &&
-        isValidEndpointOverrideEnv(requestedOverride)
-    ) {
-        raw = manifest.endpoint_overrides[requestedOverride];
-    } else if (envName && manifest.endpoint_overrides?.[envName] && isValidEndpointOverrideEnv(envName)) {
-        raw = manifest.endpoint_overrides[envName];
-    } else {
-        raw = manifest.endpoint;
-    }
-    return raw ? substituteEndpoints(raw, vars) : raw;
+/** One entry in an app git-repo directory listing (see {@link AppRepoTree}). */
+export interface AppRepoTreeEntry {
+    /** File or directory name (last path segment). */
+    name: string;
+    /** Path relative to the repo root. */
+    path: string;
+    /** Whether the entry is a file (`blob`) or a directory (`tree`). */
+    type: 'blob' | 'tree';
 }
 
-/**
- * Resolves all URL placeholders in a manifest in place (both `endpoint` and
- * `tool_collections[].url`). Intended for server-side serialization — clients and
- * downstream workers receive already-substituted URLs so they don't need to know
- * about deployment-time vars.
- *
- * Mutates the manifest rather than returning a copy so it works cleanly with
- * Mongoose populated subdocs.
- */
-export function resolveManifestUrls(
-    manifest: Partial<AppManifestData> | null | undefined,
-    envName?: string,
-    vars?: Endpoints,
-    requestedOverride?: string,
-): void {
-    if (!manifest) return;
-
-    if (manifest.endpoint) {
-        const resolved = resolveAppEndpoint(manifest, envName, vars, requestedOverride);
-        if (resolved && resolved !== manifest.endpoint) {
-            manifest.endpoint = resolved;
-        }
-    }
+/** A non-recursive listing of an app git repo directory at a given ref. */
+export interface AppRepoTree {
+    /** The ref the listing was read at (empty/undefined = default branch / HEAD). */
+    ref?: string;
+    /** The directory prefix that was listed (empty = repo root). */
+    prefix?: string;
+    entries: AppRepoTreeEntry[];
+}
 
-    const toolCollections = manifest.tool_collections as ToolCollectionObject[] | undefined;
-    if (toolCollections && Array.isArray(toolCollections)) {
-        for (let i = 0; i < toolCollections.length; i++) {
-            const item = toolCollections[i];
-            if (item && typeof item === 'object' && item.url) {
-                const sub = substituteEndpoints(item.url, vars);
-                if (sub !== item.url) item.url = sub;
-            }
-        }
-    }
+/** The content of a single file read from an app git repo at a given ref. */
+export interface AppRepoFile {
+    /** Path relative to the repo root. */
+    path: string;
+    /** The ref the file was read at (empty/undefined = default branch / HEAD). */
+    ref?: string;
+    /** UTF-8 file content. */
+    content: string;
+}
+
+/** A branch or tag in an app git repo, resolved to its latest commit. */
+export interface AppRepoRef {
+    /** Short ref name (e.g. `main`, `v1.0.0`). */
+    name: string;
+    /** Commit hash the ref points at (annotated tags are peeled to their commit). */
+    commit: string;
+    /** First line of the commit message, when available. */
+    commit_subject?: string;
+    /** Commit date as an ISO-8601 string, when available. */
+    commit_date?: string;
+    /** Commit author name, when available. */
+    commit_author?: string;
+}
+
+/** The branches and tags of an app git repo (see {@link AppRepoRef}). */
+export interface AppRepoRefs {
+    /** The repository's default branch (HEAD target), when resolvable. */
+    default_branch?: string;
+    branches: AppRepoRef[];
+    tags: AppRepoRef[];
 }
 
 export type AppPackageScope =
@@ -669,10 +966,30 @@ export type AppPackageScope =
     | 'types'
     | 'processes'
     | 'templates'
+    | 'dashboards'
     | 'settings'
     | 'widgets'
     | 'activities'
     | 'all';
+
+/**
+ * Canonical runtime list of {@link AppPackageScope} — every package scope, including the
+ * catch-all `'all'`. Co-located with the type so TypeScript rejects drift. Consumers (the
+ * /package?scope= parser, the inspection report) must use this rather than re-listing.
+ */
+export const APP_PACKAGE_SCOPES: readonly AppPackageScope[] = [
+    'ui',
+    'tools',
+    'interactions',
+    'types',
+    'processes',
+    'templates',
+    'dashboards',
+    'settings',
+    'widgets',
+    'activities',
+    'all',
+];
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -712,6 +1029,11 @@ export interface AppPackage {
      */
     templates?: RenderingTemplateDefinitionRef[];
 
+    /**
+     * Dashboards provided by the app.
+     */
+    dashboards?: AppDashboardDefinition[];
+
     /**
      * Widgets provided by the app.
      */
@@ -730,6 +1052,61 @@ export interface AppPackage {
     settings_schema?: JSONSchema;
 }
 
+/**
+ * A single diagnostic produced while inspecting an app's registration state.
+ */
+export interface AppInspectionIssue {
+    severity: 'error' | 'warning';
+    /** The capability this issue relates to, when applicable (e.g. 'types'). */
+    capability?: AppPackageScope;
+    /** Stable machine code, e.g. 'capability_declared_but_empty', 'endpoint_unreachable', 'not_installed'. */
+    code: string;
+    /** Human-readable explanation, safe to surface to the model and the UI. */
+    message: string;
+}
+
+/**
+ * Per-capability report of what an app's published package actually exposes,
+ * compared against what its manifest declares.
+ */
+export interface AppInspectionCapabilityReport {
+    capability: AppPackageScope;
+    /** True when the manifest's `capabilities` array declares this capability. */
+    declared: boolean;
+    /** The local ids the published package actually serves for this capability. */
+    exposed_ids: string[];
+    /** Convenience count of `exposed_ids`. */
+    exposed_count: number;
+}
+
+/**
+ * Result of inspecting an app's registration: the resolved manifest state, what
+ * the published package actually exposes per capability, and diagnostics. This
+ * is the ground truth used by the `app_inspect_registration` agent tool and the
+ * Build › App inspection UI to verify what is registered vs declared, instead of
+ * inferring it from failed object/import calls.
+ */
+export interface AppInspectionResult {
+    app_id: string;
+    name: string;
+    version?: string;
+    /** The resolved package endpoint for the current environment, if any. */
+    endpoint?: string;
+    /** True when the package endpoint responded to the capability probe. */
+    endpoint_reachable: boolean;
+    /** True when the app is installed in the current project. */
+    installed: boolean;
+    access_control?: string;
+    /** The capabilities declared on the manifest. */
+    capabilities: AppPackageScope[];
+    /** What the published package exposes, per capability. */
+    package: AppInspectionCapabilityReport[];
+    /** Diagnostics — errors and warnings about the registration state. */
+    issues: AppInspectionIssue[];
+    /** Populated when the package probe itself failed (endpoint error/unreachable). */
+    probe_error?: string;
+}
+
 export interface AppWidgetInfo {
     collection: string;
     skill: string;
@@ -775,6 +1152,7 @@ export interface AppManifestSource {
     git: {
         url: string;
         default_branch?: string;
+        production_branch?: string;
         development_branch?: string;
     };
 }
@@ -1322,3 +1700,20 @@ export interface ValidateUrlRequest {
 export interface ValidateUrlResponse {
     valid: true;
 }
+
+/**
+ * Result of DELETE /api/v1/apps/:id. With `?confirm=true` the cascade runs and
+ * `deleted: true` is set; without it the endpoint returns a dry-run summary so
+ * the UI can show what would be removed.
+ */
+export interface AppDeleteSummary {
+    confirmed: boolean;
+    app_id: string;
+    app_name: string;
+    versions: number;
+    installations: number;
+    storage_prefix: string;
+    git_repo_url?: string;
+    deleted: boolean;
+    warnings: string[];
+}