@veltrixsecops/app-sdk 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @veltrixsecops/app-sdk
 
-The official SDK for building [Veltrix](https://github.com/captivatortechnologies/Veltrix) Security-as-Code apps.
+The official SDK for building [Veltrix](https://veltrixsecops.com) Security-as-Code apps. Community apps live in the open-source [veltrix-apps](https://github.com/captivatortechnologies/veltrix-apps) repository; the Veltrix platform itself is a hosted SaaS.
 
 A Veltrix app packages everything needed to manage one security tool's configuration as code: pipeline handlers (validate → deploy → rollback → health-check → drift-detect → status), canvas templates, database migrations, lifecycle hooks, and optional client pages. This SDK provides the typed contracts and helpers for all of it.
 
@@ -73,6 +73,50 @@ export default async function onInstall({ db, appId }: AppHookContext): Promise<
 
 ```tsx
 import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
+import { authFetch } from '@veltrixsecops/app-sdk/client'
+```
+
+Your `client/index.tsx` default-exports an `AppClientModule` (`{ id, pages, sidebarItems }`;
+`pages` keys must match `manifest.client.pages[].component`). At packaging time the CLI
+compiles it into a hermetic browser bundle (`client/dist/index.mjs`): `react`, `react-dom`,
+`react/jsx-runtime`, and all `@veltrixsecops/app-sdk` imports are replaced with shims that
+read the platform-provided runtime from `globalThis.__VELTRIX_APP_RUNTIME__`, so your
+components render inside the host React tree with working hooks and shared context — never
+bundle your own copy of React.
+
+Two rules for app pages:
+
+- Use **`authFetch`** (not plain `fetch`) for calls to your app's server routes
+  (`/api/apps/<app-id>/...`) — they are bearer-token protected and a plain `fetch`
+  receives 401s.
+- Only import third-party client libraries if you accept them being compiled into your
+  bundle; keep pages lean.
+
+## Standard app layout
+
+Every Veltrix app follows one canonical folder structure — the CLI scaffolds it (`veltrix init`), `veltrix validate` warns on deviations, and the SDK exports it as constants (`APP_LAYOUT`, `HANDLER_NAMES`, `conventionalPaths(configTypeId)`):
+
+```
+apps/<app-id>/
+├── manifest.yaml                          # App contract
+├── package.json / tsconfig.json / README.md
+├── config-types/<configTypeId>/           # Everything for one configuration type:
+│   ├── canvas.yaml                        #   form schema
+│   ├── defaults.yaml                      #   default values
+│   ├── validate.ts, deploy.ts, rollback.ts,
+│   ├── healthCheck.ts, driftDetect.ts, getStatus.ts
+│   └── __tests__/
+├── lib/                                   # Shared app code (API clients)
+├── hooks/                                 # onInstall.ts, onUninstall.ts, ...
+├── migrations/                            # SQL (with database.tablePrefix)
+├── server/index.ts                        # Route module (AppRouteContext)
+├── client/index.tsx + client/pages/       # Optional UI
+└── assets/                                # Optional icons
+```
+
+```ts
+import { conventionalPaths } from '@veltrixsecops/app-sdk'
+conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'
 ```
 
 ## Package layout
@@ -85,7 +129,7 @@ import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
 
 ## Building an app
 
-Start from the [`_template`](https://github.com/captivatortechnologies/Veltrix/tree/main/apps-and-tools/_template) app and see the contribution guide in `apps-and-tools/CONTRIBUTING.md`.
+Community apps live in the [veltrix-apps](https://github.com/captivatortechnologies/veltrix-apps) repository. Start from its [`_template`](https://github.com/captivatortechnologies/veltrix-apps/tree/main/_template) app and see the [contribution guide](https://github.com/captivatortechnologies/veltrix-apps/blob/main/CONTRIBUTING.md).
 
 ## License
 

package/dist/chunk-I4JJX4LL.js

@@ -0,0 +1,28 @@
+// src/client/index.ts
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function requireHostRuntime() {
+  const runtime = getHostRuntime();
+  if (!runtime) {
+    throw new Error(
+      `Veltrix host runtime not found \u2014 app client bundles only run inside the Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`
+    );
+  }
+  return runtime;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+
+export {
+  HOST_RUNTIME_GLOBAL,
+  getHostRuntime,
+  requireHostRuntime,
+  authFetch
+};
+//# sourceMappingURL=chunk-I4JJX4LL.js.map

package/dist/chunk-I4JJX4LL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/index.ts"],"sourcesContent":["// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n"],"mappings":";AAqBO,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAGO,SAAS,qBAAyC;AACvD,QAAM,UAAU,eAAe;AAC/B,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR,qHAC0C,mBAAmB;AAAA,IAC/D;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;","names":[]}

package/dist/{chunk-TSEIWO6T.js → chunk-JDEA2F7I.js}

@@ -1,6 +1,11 @@
+import {
+  authFetch
+} from "./chunk-I4JJX4LL.js";
+
 // src/hooks/use-app-context.ts
 import { createContext, useContext } from "react";
-var AppContext = createContext(null);
+var hostContext = globalThis.__VELTRIX_APP_RUNTIME__?.AppContext;
+var AppContext = hostContext ?? createContext(null);
 function useAppContext() {
   const ctx = useContext(AppContext);
   if (!ctx) {
@@ -18,7 +23,7 @@ function usePipelineStatus(appId) {
   const refresh = useCallback(async () => {
     try {
       setIsLoading(true);
-      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`);
       if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
       const result = await response.json();
       setData(result);
@@ -40,4 +45,4 @@ export {
   useAppContext,
   usePipelineStatus
 };
-//# sourceMappingURL=chunk-TSEIWO6T.js.map
+//# sourceMappingURL=chunk-JDEA2F7I.js.map

package/dist/chunk-JDEA2F7I.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts"],"sourcesContent":["// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext, type Context } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\n// Anchor the context on the host runtime when running inside the platform,\n// so a bundle that inlined its own SDK copy still shares the host's context\n// (two createContext objects never match, even with identical shapes).\nconst hostContext = (\n  (globalThis as Record<string, unknown>).__VELTRIX_APP_RUNTIME__ as\n    | { AppContext?: Context<AppContextValue | null> }\n    | undefined\n)?.AppContext\n\nexport const AppContext: Context<AppContextValue | null> =\n  hostContext ?? createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\nimport { authFetch } from '../client'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      // Platform APIs are bearer-token protected — plain fetch would 401\n      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n"],"mappings":";;;;;AAKA,SAAS,eAAe,kBAAgC;AAqBxD,IAAM,cACH,WAAuC,yBAGvC;AAEI,IAAM,aACX,eAAe,cAAsC,IAAI;AAepD,SAAS,gBAAiC;AAC/C,QAAM,MAAM,WAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;ACtDA,SAAS,UAAU,WAAW,mBAAmB;AAgC1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,IAAI,SAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,QAAM,UAAU,YAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AAEjB,YAAM,WAAW,MAAM,UAAU,+BAA+B,KAAK,EAAE;AACvE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,YAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":[]}

package/dist/client/index.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  HOST_RUNTIME_GLOBAL: () => HOST_RUNTIME_GLOBAL,
+  authFetch: () => authFetch,
+  getHostRuntime: () => getHostRuntime,
+  requireHostRuntime: () => requireHostRuntime
+});
+module.exports = __toCommonJS(client_exports);
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function requireHostRuntime() {
+  const runtime = getHostRuntime();
+  if (!runtime) {
+    throw new Error(
+      `Veltrix host runtime not found \u2014 app client bundles only run inside the Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`
+    );
+  }
+  return runtime;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+});
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"sourcesContent":["// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBO,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAGO,SAAS,qBAAyC;AACvD,QAAM,UAAU,eAAe;AAC/B,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR,qHAC0C,mBAAmB;AAAA,IAC/D;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;","names":[]}

package/dist/client/index.d.cts

@@ -0,0 +1,58 @@
+import { ComponentType, LazyExoticComponent, Context } from 'react';
+import { A as AppContextValue } from '../use-app-context-PBuG144m.cjs';
+
+/** Name of the global the platform installs before loading app bundles. */
+declare const HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+/**
+ * The runtime surface the platform exposes to app client bundles.
+ * The react/reactDom/jsxRuntime members are the host's own module objects —
+ * app bundles are compiled with shims that re-export them, guaranteeing a
+ * single React instance per page.
+ */
+interface VeltrixHostRuntime {
+    /** The host's `react` module object. */
+    react: unknown;
+    /** The host's `react-dom` module object. */
+    reactDom: unknown;
+    /** The host's `react-dom/client` module object. */
+    reactDomClient?: unknown;
+    /** The host's `react/jsx-runtime` module object. */
+    jsxRuntime: unknown;
+    /** Shared app context — the host wraps app pages in its Provider. */
+    AppContext: Context<AppContextValue | null>;
+    /** fetch() with the platform's Authorization header attached. */
+    authFetch: (input: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,
+     * `.../hooks`, and `.../client` imports (useAppContext, AppContext,
+     * usePipelineStatus, authFetch, getHostRuntime, ...).
+     */
+    sdk: Record<string, unknown>;
+}
+/** Read the host runtime, or null outside the platform (tests, storybook). */
+declare function getHostRuntime(): VeltrixHostRuntime | null;
+/** Read the host runtime, throwing a diagnosable error when absent. */
+declare function requireHostRuntime(): VeltrixHostRuntime;
+/**
+ * fetch() that carries the platform's Authorization header. Required for an
+ * app page to call its own server routes (/api/apps/<app-id>/...), which are
+ * bearer-token protected. Falls back to plain fetch outside the platform.
+ */
+declare function authFetch(input: string, init?: RequestInit): Promise<Response>;
+/** A sidebar entry contributed by the app's client entry module. */
+interface AppSidebarItem {
+    path: string;
+    label: string;
+    icon?: string;
+}
+/**
+ * Shape of the default export of an app's `client/index.tsx`.
+ * `pages` keys must match `manifest.client.pages[].component`.
+ */
+interface AppClientModule {
+    id: string;
+    pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>;
+    sidebarItems?: AppSidebarItem[];
+}
+
+export { type AppClientModule, type AppSidebarItem, HOST_RUNTIME_GLOBAL, type VeltrixHostRuntime, authFetch, getHostRuntime, requireHostRuntime };

package/dist/client/index.d.ts

@@ -0,0 +1,58 @@
+import { ComponentType, LazyExoticComponent, Context } from 'react';
+import { A as AppContextValue } from '../use-app-context-PBuG144m.js';
+
+/** Name of the global the platform installs before loading app bundles. */
+declare const HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+/**
+ * The runtime surface the platform exposes to app client bundles.
+ * The react/reactDom/jsxRuntime members are the host's own module objects —
+ * app bundles are compiled with shims that re-export them, guaranteeing a
+ * single React instance per page.
+ */
+interface VeltrixHostRuntime {
+    /** The host's `react` module object. */
+    react: unknown;
+    /** The host's `react-dom` module object. */
+    reactDom: unknown;
+    /** The host's `react-dom/client` module object. */
+    reactDomClient?: unknown;
+    /** The host's `react/jsx-runtime` module object. */
+    jsxRuntime: unknown;
+    /** Shared app context — the host wraps app pages in its Provider. */
+    AppContext: Context<AppContextValue | null>;
+    /** fetch() with the platform's Authorization header attached. */
+    authFetch: (input: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,
+     * `.../hooks`, and `.../client` imports (useAppContext, AppContext,
+     * usePipelineStatus, authFetch, getHostRuntime, ...).
+     */
+    sdk: Record<string, unknown>;
+}
+/** Read the host runtime, or null outside the platform (tests, storybook). */
+declare function getHostRuntime(): VeltrixHostRuntime | null;
+/** Read the host runtime, throwing a diagnosable error when absent. */
+declare function requireHostRuntime(): VeltrixHostRuntime;
+/**
+ * fetch() that carries the platform's Authorization header. Required for an
+ * app page to call its own server routes (/api/apps/<app-id>/...), which are
+ * bearer-token protected. Falls back to plain fetch outside the platform.
+ */
+declare function authFetch(input: string, init?: RequestInit): Promise<Response>;
+/** A sidebar entry contributed by the app's client entry module. */
+interface AppSidebarItem {
+    path: string;
+    label: string;
+    icon?: string;
+}
+/**
+ * Shape of the default export of an app's `client/index.tsx`.
+ * `pages` keys must match `manifest.client.pages[].component`.
+ */
+interface AppClientModule {
+    id: string;
+    pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>;
+    sidebarItems?: AppSidebarItem[];
+}
+
+export { type AppClientModule, type AppSidebarItem, HOST_RUNTIME_GLOBAL, type VeltrixHostRuntime, authFetch, getHostRuntime, requireHostRuntime };

package/dist/client/index.js

@@ -0,0 +1,13 @@
+import {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+} from "../chunk-I4JJX4LL.js";
+export {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+};
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/hooks/index.cjs

@@ -28,7 +28,8 @@ module.exports = __toCommonJS(hooks_exports);
 
 // src/hooks/use-app-context.ts
 var import_react = require("react");
-var AppContext = (0, import_react.createContext)(null);
+var hostContext = globalThis.__VELTRIX_APP_RUNTIME__?.AppContext;
+var AppContext = hostContext ?? (0, import_react.createContext)(null);
 function useAppContext() {
   const ctx = (0, import_react.useContext)(AppContext);
   if (!ctx) {
@@ -39,6 +40,20 @@ function useAppContext() {
 
 // src/hooks/use-pipeline-status.ts
 var import_react2 = require("react");
+
+// src/client/index.ts
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+
+// src/hooks/use-pipeline-status.ts
 function usePipelineStatus(appId) {
   const [data, setData] = (0, import_react2.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react2.useState)(true);
@@ -46,7 +61,7 @@ function usePipelineStatus(appId) {
   const refresh = (0, import_react2.useCallback)(async () => {
     try {
       setIsLoading(true);
-      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`);
       if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
       const result = await response.json();
       setData(result);

package/dist/hooks/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/hooks/index.ts","../../src/hooks/use-app-context.ts","../../src/hooks/use-pipeline-status.ts"],"sourcesContent":["export { useAppContext, AppContext, type AppContextValue } from './use-app-context'\r\nexport { usePipelineStatus, type PipelineStatusData } from './use-pipeline-status'\r\n","// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\nexport const AppContext = createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      const response = await fetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,mBAA0C;AAkBnC,IAAM,iBAAa,4BAAsC,IAAI;AAe7D,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC5CA,IAAAA,gBAAiD;AA+B1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AACjB,YAAM,WAAW,MAAM,MAAM,+BAA+B,KAAK,EAAE;AACnE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":["import_react"]}
+{"version":3,"sources":["../../src/hooks/index.ts","../../src/hooks/use-app-context.ts","../../src/hooks/use-pipeline-status.ts","../../src/client/index.ts"],"sourcesContent":["export { useAppContext, AppContext, type AppContextValue } from './use-app-context'\r\nexport { usePipelineStatus, type PipelineStatusData } from './use-pipeline-status'\r\n","// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext, type Context } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\n// Anchor the context on the host runtime when running inside the platform,\n// so a bundle that inlined its own SDK copy still shares the host's context\n// (two createContext objects never match, even with identical shapes).\nconst hostContext = (\n  (globalThis as Record<string, unknown>).__VELTRIX_APP_RUNTIME__ as\n    | { AppContext?: Context<AppContextValue | null> }\n    | undefined\n)?.AppContext\n\nexport const AppContext: Context<AppContextValue | null> =\n  hostContext ?? createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\nimport { authFetch } from '../client'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      // Platform APIs are bearer-token protected — plain fetch would 401\n      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n","// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,mBAAwD;AAqBxD,IAAM,cACH,WAAuC,yBAGvC;AAEI,IAAM,aACX,mBAAe,4BAAsC,IAAI;AAepD,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;ACtDA,IAAAA,gBAAiD;;;ACqB1C,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAmBO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;;;AD7CO,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AAEjB,YAAM,WAAW,MAAM,UAAU,+BAA+B,KAAK,EAAE;AACvE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":["import_react"]}

package/dist/hooks/index.d.cts

@@ -1,2 +1,39 @@
-export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.cjs';
+export { d as AppContext, A as AppContextValue, w as useAppContext } from '../use-app-context-PBuG144m.cjs';
 import 'react';
+
+interface PipelineStatusData {
+    pendingApprovals: number;
+    activeDeployments: number;
+    failedDeployments: number;
+    unresolvedDrifts: number;
+    recentDeployments: Array<{
+        id: string;
+        canvasName: string;
+        environment: string;
+        status: string;
+        startedAt: string;
+        completedAt?: string;
+    }>;
+}
+/**
+ * Hook to access pipeline status for the current app/customer.
+ *
+ * @example
+ * ```tsx
+ * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
+ *
+ * function Dashboard() {
+ *   const { data, isLoading } = usePipelineStatus('my-app')
+ *   if (isLoading) return <Spinner />
+ *   return <div>{data.activeDeployments} active deployments</div>
+ * }
+ * ```
+ */
+declare function usePipelineStatus(appId: string): {
+    data: PipelineStatusData | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+
+export { type PipelineStatusData, usePipelineStatus };

package/dist/hooks/index.d.ts

@@ -1,2 +1,39 @@
-export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.js';
+export { d as AppContext, A as AppContextValue, w as useAppContext } from '../use-app-context-PBuG144m.js';
 import 'react';
+
+interface PipelineStatusData {
+    pendingApprovals: number;
+    activeDeployments: number;
+    failedDeployments: number;
+    unresolvedDrifts: number;
+    recentDeployments: Array<{
+        id: string;
+        canvasName: string;
+        environment: string;
+        status: string;
+        startedAt: string;
+        completedAt?: string;
+    }>;
+}
+/**
+ * Hook to access pipeline status for the current app/customer.
+ *
+ * @example
+ * ```tsx
+ * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
+ *
+ * function Dashboard() {
+ *   const { data, isLoading } = usePipelineStatus('my-app')
+ *   if (isLoading) return <Spinner />
+ *   return <div>{data.activeDeployments} active deployments</div>
+ * }
+ * ```
+ */
+declare function usePipelineStatus(appId: string): {
+    data: PipelineStatusData | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+
+export { type PipelineStatusData, usePipelineStatus };

package/dist/hooks/index.js

@@ -2,7 +2,8 @@ import {
   AppContext,
   useAppContext,
   usePipelineStatus
-} from "../chunk-TSEIWO6T.js";
+} from "../chunk-JDEA2F7I.js";
+import "../chunk-I4JJX4LL.js";
 export {
   AppContext,
   useAppContext,

package/dist/index.cjs

@@ -20,7 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  APP_LAYOUT: () => APP_LAYOUT,
+  APP_PAGE_LAYOUTS: () => APP_PAGE_LAYOUTS,
+  APP_PAGE_NAV: () => APP_PAGE_NAV,
   AppContext: () => AppContext,
+  HANDLER_NAMES: () => HANDLER_NAMES,
+  conventionalPaths: () => conventionalPaths,
   defineDeployer: () => defineDeployer,
   defineDriftDetector: () => defineDriftDetector,
   defineHealthChecker: () => defineHealthChecker,
@@ -58,7 +63,8 @@ function defineDriftDetector(handler) {
 
 // src/hooks/use-app-context.ts
 var import_react = require("react");
-var AppContext = (0, import_react.createContext)(null);
+var hostContext = globalThis.__VELTRIX_APP_RUNTIME__?.AppContext;
+var AppContext = hostContext ?? (0, import_react.createContext)(null);
 function useAppContext() {
   const ctx = (0, import_react.useContext)(AppContext);
   if (!ctx) {
@@ -69,6 +75,20 @@ function useAppContext() {
 
 // src/hooks/use-pipeline-status.ts
 var import_react2 = require("react");
+
+// src/client/index.ts
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+
+// src/hooks/use-pipeline-status.ts
 function usePipelineStatus(appId) {
   const [data, setData] = (0, import_react2.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react2.useState)(true);
@@ -76,7 +96,7 @@ function usePipelineStatus(appId) {
   const refresh = (0, import_react2.useCallback)(async () => {
     try {
       setIsLoading(true);
-      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`);
       if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
       const result = await response.json();
       setData(result);
@@ -92,9 +112,68 @@ function usePipelineStatus(appId) {
   }, [refresh]);
   return { data, isLoading, error, refresh };
 }
+
+// src/types/manifest.ts
+var APP_PAGE_LAYOUTS = ["standard", "full-bleed", "canvas"];
+var APP_PAGE_NAV = ["sidebar", "tab", "hidden"];
+
+// src/structure.ts
+var APP_LAYOUT = {
+  /** The app contract. Always at the app root. */
+  manifest: "manifest.yaml",
+  /**
+   * The unit of extension: config-types/<configTypeId>/ colocates everything
+   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline
+   * handlers (extensionless in the manifest), and __tests__/.
+   */
+  configTypesDir: "config-types",
+  /** Canvas form schema filename inside a config-type folder. */
+  canvasFile: "canvas.yaml",
+  /** Default field values filename inside a config-type folder. */
+  defaultsFile: "defaults.yaml",
+  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */
+  hooksDir: "hooks",
+  /** Shared app code used by multiple handlers (API clients, parsers). */
+  libDir: "lib",
+  /** SQL migrations (requires manifest `database.tablePrefix`). */
+  migrationsDir: "migrations",
+  /** Fastify route module receiving (fastify, AppRouteContext). */
+  serverEntry: "server/index",
+  /** Client entry registering pages/sidebar items (optional). */
+  clientEntry: "client/index",
+  /** Icons and logos (optional). */
+  assetsDir: "assets",
+  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */
+  testsDirName: "__tests__"
+};
+var HANDLER_NAMES = [
+  "validate",
+  "deploy",
+  "rollback",
+  "healthCheck",
+  "driftDetect",
+  "getStatus"
+];
+function conventionalPaths(configTypeId) {
+  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`;
+  const handlers = {};
+  for (const name of HANDLER_NAMES) {
+    handlers[name] = `${base}/${name}`;
+  }
+  return {
+    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,
+    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,
+    handlers
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APP_LAYOUT,
+  APP_PAGE_LAYOUTS,
+  APP_PAGE_NAV,
   AppContext,
+  HANDLER_NAMES,
+  conventionalPaths,
   defineDeployer,
   defineDriftDetector,
   defineHealthChecker,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/pipeline/define-validator.ts","../src/pipeline/define-deployer.ts","../src/pipeline/define-rollback-handler.ts","../src/pipeline/define-health-checker.ts","../src/pipeline/define-drift-detector.ts","../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts"],"sourcesContent":["// ========================================================================\n// @veltrixsecops/app-sdk\n//\n// The official SDK for building Veltrix Security-as-Code apps.\n// Import pipeline helpers, hooks, and types to build your app.\n//\n// Usage:\n//   import { defineValidator, defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n//   import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n//   import type { PipelineContext, DeployContext } from '@veltrixsecops/app-sdk'\n// ========================================================================\n\n// Pipeline handler helpers\nexport {\n  defineValidator,\n  defineDeployer,\n  defineRollbackHandler,\n  defineHealthChecker,\n  defineDriftDetector,\n} from './pipeline'\n\n// React hooks\nexport {\n  useAppContext,\n  AppContext,\n  usePipelineStatus,\n} from './hooks'\n\n// Pipeline types\nexport type {\n  PipelineContext,\n  DeployContext,\n  RollbackContext,\n  HealthCheckContext,\n  DriftContext,\n  ValidationResult,\n  ValidationError,\n  ValidationWarning,\n  DeployResult,\n  RollbackResult,\n  HealthCheckResult,\n  HealthCheck,\n  DriftResult,\n  DriftDiff,\n  ConfigStatus,\n  ComponentConfigStatus,\n  CanvasSnapshot,\n  CanvasSectionSnapshot,\n  DeploymentStrategy,\n  EnvironmentRef,\n  UserRef,\n  ComponentRef,\n  CredentialRef,\n  ConnectivityRef,\n  ConnectivityProviderRef,\n  PlatformDataApi,\n  DeploymentSummary,\n  ValidateHandler,\n  DeployHandler,\n  RollbackHandler,\n  HealthCheckHandler,\n  DriftDetectHandler,\n  GetStatusHandler,\n} from './types/pipeline'\n\n// Platform types\nexport type {\n  Component,\n  Credential,\n  Connectivity,\n  Tag,\n  User,\n  Customer,\n  PlatformDatabaseClient,\n  AppHookContext,\n  AppRouteContext,\n} from './types/platform'\n\n// Manifest types\nexport type {\n  AppManifest,\n  AppConfigurationTypeManifest,\n  AppPermissionDeclaration,\n  AppPageDeclaration,\n  AppSettingDeclaration,\n  AppSource,\n  AppStatusType,\n  AppInstallationStatus,\n  AppListItem,\n  AppDetail,\n  AppInstallationDetail,\n} from './types/manifest'\n\n// Hooks types\nexport type { AppContextValue, PipelineStatusData } from './hooks'\n","import type { PipelineContext, ValidationResult } from '../types/pipeline'\n\n/**\n * Define a validation handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineValidator } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineValidator(async (ctx) => {\n *   const errors = []\n *   const name = ctx.canvas.sections[0]?.fields['name']\n *   if (!name) {\n *     errors.push({ field: 'name', message: 'Name is required', code: 'REQUIRED' })\n *   }\n *   return { valid: errors.length === 0, errors, warnings: [] }\n * })\n * ```\n */\nexport function defineValidator(\n  handler: (ctx: PipelineContext) => Promise<ValidationResult>,\n): (ctx: PipelineContext) => Promise<ValidationResult> {\n  return handler\n}\n","import type { DeployContext, DeployResult } from '../types/pipeline'\n\n/**\n * Define a deploy handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineDeployer(async (ctx) => {\n *   const { component, credential, connectivity, canvas } = ctx\n *   // Push configuration to the tool\n *   return { success: true, message: 'Deployed', rollbackData: previousState }\n * })\n * ```\n */\nexport function defineDeployer(\n  handler: (ctx: DeployContext) => Promise<DeployResult>,\n): (ctx: DeployContext) => Promise<DeployResult> {\n  return handler\n}\n","import type { RollbackContext, RollbackResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a rollback handler for a configuration type.\r\n */\r\nexport function defineRollbackHandler(\r\n  handler: (ctx: RollbackContext) => Promise<RollbackResult>,\r\n): (ctx: RollbackContext) => Promise<RollbackResult> {\r\n  return handler\r\n}\r\n","import type { HealthCheckContext, HealthCheckResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a health check handler for a configuration type.\r\n */\r\nexport function defineHealthChecker(\r\n  handler: (ctx: HealthCheckContext) => Promise<HealthCheckResult>,\r\n): (ctx: HealthCheckContext) => Promise<HealthCheckResult> {\r\n  return handler\r\n}\r\n","import type { DriftContext, DriftResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a drift detection handler for a configuration type.\r\n */\r\nexport function defineDriftDetector(\r\n  handler: (ctx: DriftContext) => Promise<DriftResult>,\r\n): (ctx: DriftContext) => Promise<DriftResult> {\r\n  return handler\r\n}\r\n","// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\nexport const AppContext = createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      const response = await fetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBO,SAAS,gBACd,SACqD;AACrD,SAAO;AACT;;;ACPO,SAAS,eACd,SAC+C;AAC/C,SAAO;AACT;;;ACfO,SAAS,sBACd,SACmD;AACnD,SAAO;AACT;;;ACJO,SAAS,oBACd,SACyD;AACzD,SAAO;AACT;;;ACJO,SAAS,oBACd,SAC6C;AAC7C,SAAO;AACT;;;ACJA,mBAA0C;AAkBnC,IAAM,iBAAa,4BAAsC,IAAI;AAe7D,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC5CA,IAAAA,gBAAiD;AA+B1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AACjB,YAAM,WAAW,MAAM,MAAM,+BAA+B,KAAK,EAAE;AACnE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":["import_react"]}
+{"version":3,"sources":["../src/index.ts","../src/pipeline/define-validator.ts","../src/pipeline/define-deployer.ts","../src/pipeline/define-rollback-handler.ts","../src/pipeline/define-health-checker.ts","../src/pipeline/define-drift-detector.ts","../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts","../src/client/index.ts","../src/types/manifest.ts","../src/structure.ts"],"sourcesContent":["// ========================================================================\n// @veltrixsecops/app-sdk\n//\n// The official SDK for building Veltrix Security-as-Code apps.\n// Import pipeline helpers, hooks, and types to build your app.\n//\n// Usage:\n//   import { defineValidator, defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n//   import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n//   import type { PipelineContext, DeployContext } from '@veltrixsecops/app-sdk'\n// ========================================================================\n\n// Pipeline handler helpers\nexport {\n  defineValidator,\n  defineDeployer,\n  defineRollbackHandler,\n  defineHealthChecker,\n  defineDriftDetector,\n} from './pipeline'\n\n// React hooks\nexport {\n  useAppContext,\n  AppContext,\n  usePipelineStatus,\n} from './hooks'\n\n// Pipeline types\nexport type {\n  PipelineContext,\n  DeployContext,\n  RollbackContext,\n  HealthCheckContext,\n  DriftContext,\n  ValidationResult,\n  ValidationError,\n  ValidationWarning,\n  DeployResult,\n  RollbackResult,\n  HealthCheckResult,\n  HealthCheck,\n  DriftResult,\n  DriftDiff,\n  ConfigStatus,\n  ComponentConfigStatus,\n  CanvasSnapshot,\n  CanvasSectionSnapshot,\n  DeploymentStrategy,\n  EnvironmentRef,\n  UserRef,\n  ComponentRef,\n  CredentialRef,\n  ConnectivityRef,\n  ConnectivityProviderRef,\n  PlatformDataApi,\n  DeploymentSummary,\n  ValidateHandler,\n  DeployHandler,\n  RollbackHandler,\n  HealthCheckHandler,\n  DriftDetectHandler,\n  GetStatusHandler,\n} from './types/pipeline'\n\n// Platform types\nexport type {\n  Component,\n  Credential,\n  Connectivity,\n  Tag,\n  User,\n  Customer,\n  PlatformDatabaseClient,\n  AppHookContext,\n  AppRouteContext,\n} from './types/platform'\n\n// App UI & navigation contract\nexport { APP_PAGE_LAYOUTS, APP_PAGE_NAV } from './types/manifest'\nexport type { AppPageLayout, AppPageNav, AppPagePermission } from './types/manifest'\n\n// Manifest types\nexport type {\n  AppManifest,\n  AppConfigurationTypeManifest,\n  AppPermissionDeclaration,\n  AppPageDeclaration,\n  AppSettingDeclaration,\n  AppSource,\n  AppStatusType,\n  AppInstallationStatus,\n  AppListItem,\n  AppDetail,\n  AppInstallationDetail,\n} from './types/manifest'\n\n// Canonical app layout\nexport { APP_LAYOUT, HANDLER_NAMES, conventionalPaths } from './structure'\nexport type { HandlerName } from './structure'\n\n// Hooks types\nexport type { AppContextValue, PipelineStatusData } from './hooks'\n","import type { PipelineContext, ValidationResult } from '../types/pipeline'\n\n/**\n * Define a validation handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineValidator } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineValidator(async (ctx) => {\n *   const errors = []\n *   const name = ctx.canvas.sections[0]?.fields['name']\n *   if (!name) {\n *     errors.push({ field: 'name', message: 'Name is required', code: 'REQUIRED' })\n *   }\n *   return { valid: errors.length === 0, errors, warnings: [] }\n * })\n * ```\n */\nexport function defineValidator(\n  handler: (ctx: PipelineContext) => Promise<ValidationResult>,\n): (ctx: PipelineContext) => Promise<ValidationResult> {\n  return handler\n}\n","import type { DeployContext, DeployResult } from '../types/pipeline'\n\n/**\n * Define a deploy handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineDeployer(async (ctx) => {\n *   const { component, credential, connectivity, canvas } = ctx\n *   // Push configuration to the tool\n *   return { success: true, message: 'Deployed', rollbackData: previousState }\n * })\n * ```\n */\nexport function defineDeployer(\n  handler: (ctx: DeployContext) => Promise<DeployResult>,\n): (ctx: DeployContext) => Promise<DeployResult> {\n  return handler\n}\n","import type { RollbackContext, RollbackResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a rollback handler for a configuration type.\r\n */\r\nexport function defineRollbackHandler(\r\n  handler: (ctx: RollbackContext) => Promise<RollbackResult>,\r\n): (ctx: RollbackContext) => Promise<RollbackResult> {\r\n  return handler\r\n}\r\n","import type { HealthCheckContext, HealthCheckResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a health check handler for a configuration type.\r\n */\r\nexport function defineHealthChecker(\r\n  handler: (ctx: HealthCheckContext) => Promise<HealthCheckResult>,\r\n): (ctx: HealthCheckContext) => Promise<HealthCheckResult> {\r\n  return handler\r\n}\r\n","import type { DriftContext, DriftResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a drift detection handler for a configuration type.\r\n */\r\nexport function defineDriftDetector(\r\n  handler: (ctx: DriftContext) => Promise<DriftResult>,\r\n): (ctx: DriftContext) => Promise<DriftResult> {\r\n  return handler\r\n}\r\n","// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext, type Context } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\n// Anchor the context on the host runtime when running inside the platform,\n// so a bundle that inlined its own SDK copy still shares the host's context\n// (two createContext objects never match, even with identical shapes).\nconst hostContext = (\n  (globalThis as Record<string, unknown>).__VELTRIX_APP_RUNTIME__ as\n    | { AppContext?: Context<AppContextValue | null> }\n    | undefined\n)?.AppContext\n\nexport const AppContext: Context<AppContextValue | null> =\n  hostContext ?? createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\nimport { authFetch } from '../client'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      // Platform APIs are bearer-token protected — plain fetch would 401\n      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n","// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n","// ========================================================================\n// App manifest types\n//\n// Self-contained copy of the platform's manifest contract so the SDK can\n// be published and consumed outside the platform monorepo. The platform\n// keeps its own copy in shared/types/app.ts — changes to the manifest\n// contract must be applied to both files.\n// ========================================================================\n\nexport type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM'\nexport type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED'\nexport type AppInstallationStatus =\n  | 'INSTALLING'\n  | 'INSTALLED'\n  | 'ENABLED'\n  | 'DISABLED'\n  | 'FAILED'\n  | 'UNINSTALLING'\n\n// --- Manifest Types (parsed from manifest.yaml) ---\n\nexport interface AppManifest {\n  id: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  license?: string\n  homepage?: string\n  icon?: string\n  logo?: string\n\n  platform: {\n    minVersion: string\n  }\n\n  permissions: {\n    platform: string[] // Platform permissions the app needs\n    app: AppPermissionDeclaration[] // Permissions the app exposes\n  }\n\n  database?: {\n    migrations: string\n    tablePrefix: string\n  }\n\n  pipeline: {\n    configurationTypes: AppConfigurationTypeManifest[]\n    pipelineEvents?: string[]\n  }\n\n  server: {\n    entry: string\n    routes?: {\n      prefix: string\n    }\n  }\n\n  client?: {\n    entry: string\n    pages?: AppPageDeclaration[]\n  }\n\n  hooks?: {\n    onInstall?: string\n    onUninstall?: string\n    onEnable?: string\n    onDisable?: string\n    onUpgrade?: string\n  }\n\n  events?: string[] // Platform events this app subscribes to\n\n  settings?: AppSettingDeclaration[]\n}\n\nexport interface AppConfigurationTypeManifest {\n  id: string\n  name: string\n  description?: string\n  canvasTemplate: string // Path to canvas template YAML\n  defaultConfig?: string // Path to default config YAML\n\n  handlers: {\n    validate: string\n    deploy: string\n    rollback: string\n    healthCheck: string\n    driftDetect?: string | null\n    getStatus: string\n  }\n\n  targets: {\n    componentTypes: string[]\n    requiresCredential: boolean\n    requiresConnectivity: boolean\n  }\n}\n\nexport interface AppPermissionDeclaration {\n  resource: string\n  actions: string[]\n  description?: string\n}\n\n// --- App UI & navigation contract ---\n//\n// The platform owns the chrome: breadcrumb, app header, navigation, permission\n// gating, error boundary and loading states are rendered identically for every\n// app. Apps own the page body and compose it from @veltrixsecops/ui.\n// Predictable shell, flexible body.\n\n/**\n * How the platform frames an app page.\n * - `standard`   — page header + padded content area (default; use for most pages)\n * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)\n * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)\n */\nexport type AppPageLayout = 'standard' | 'full-bleed' | 'canvas'\nexport const APP_PAGE_LAYOUTS = ['standard', 'full-bleed', 'canvas'] as const\n\n/**\n * Where the page surfaces in navigation.\n * - `sidebar` — an entry beneath the app in the sidebar\n * - `tab`     — a tab within its `parent` page\n * - `hidden`  — routable but not linked (details/drill-down pages)\n */\nexport type AppPageNav = 'sidebar' | 'tab' | 'hidden'\nexport const APP_PAGE_NAV = ['sidebar', 'tab', 'hidden'] as const\n\n/** An app-scoped permission (declared in `permissions.app`) required to see a page. */\nexport interface AppPagePermission {\n  resource: string\n  action: string\n}\n\nexport interface AppPageDeclaration {\n  /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */\n  path: string\n  /** Exported component name from the app's client entry */\n  component: string\n  label: string\n  description?: string\n  /** Icon name from the platform icon set; falls back to the app icon */\n  icon?: string\n  /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */\n  sidebar?: boolean\n  /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */\n  nav?: AppPageNav\n  /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */\n  parent?: string\n  /** Optional sidebar section label, for apps with many pages */\n  group?: string\n  /** Deterministic ordering within its group/parent (ascending; ties break on label) */\n  order?: number\n  /** Layout preset the platform renders around the page body */\n  layout?: AppPageLayout\n  /** Hide the page (and its nav entry) unless the user holds this app permission */\n  requiresPermission?: AppPagePermission\n}\n\nexport interface AppSettingDeclaration {\n  key: string\n  type: 'string' | 'number' | 'boolean' | 'select'\n  label: string\n  description?: string\n  default?: string | number | boolean\n  required?: boolean\n  options?: Array<{ label: string; value: string }>\n}\n\n// --- API Response Types ---\n\nexport interface AppListItem {\n  id: string\n  appId: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  icon?: string\n  logo?: string\n  source: AppSource\n  isDefault: boolean\n  status: AppStatusType\n  installed?: boolean\n  enabled?: boolean\n}\n\nexport interface AppDetail extends AppListItem {\n  license?: string\n  homepage?: string\n  repository?: string\n  configurationTypes: Array<{\n    id: string\n    name: string\n    description?: string\n    componentTypes: string[]\n  }>\n  permissions: AppPermissionDeclaration[]\n  settings: AppSettingDeclaration[]\n}\n\nexport interface AppInstallationDetail {\n  id: string\n  appId: string\n  customerId: string\n  version: string\n  enabled: boolean\n  installedBy: string\n  installedAt: string\n  settings: Record<string, unknown>\n  status: AppInstallationStatus\n  app: AppListItem\n}\n","// ========================================================================\n// Canonical app layout\n//\n// Every Veltrix app follows one predictable folder structure so apps are\n// easy to set up, review, and load. The `veltrix` CLI scaffolds it,\n// `veltrix validate` (and repo CI) warn on deviations, and the platform's\n// app engine resolves manifest references against it.\n// ========================================================================\n\n/** Canonical locations inside an app directory. */\nexport const APP_LAYOUT = {\n  /** The app contract. Always at the app root. */\n  manifest: 'manifest.yaml',\n  /**\n   * The unit of extension: config-types/<configTypeId>/ colocates everything\n   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline\n   * handlers (extensionless in the manifest), and __tests__/.\n   */\n  configTypesDir: 'config-types',\n  /** Canvas form schema filename inside a config-type folder. */\n  canvasFile: 'canvas.yaml',\n  /** Default field values filename inside a config-type folder. */\n  defaultsFile: 'defaults.yaml',\n  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */\n  hooksDir: 'hooks',\n  /** Shared app code used by multiple handlers (API clients, parsers). */\n  libDir: 'lib',\n  /** SQL migrations (requires manifest `database.tablePrefix`). */\n  migrationsDir: 'migrations',\n  /** Fastify route module receiving (fastify, AppRouteContext). */\n  serverEntry: 'server/index',\n  /** Client entry registering pages/sidebar items (optional). */\n  clientEntry: 'client/index',\n  /** Icons and logos (optional). */\n  assetsDir: 'assets',\n  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */\n  testsDirName: '__tests__',\n} as const\n\n/** The six pipeline handler names, in lifecycle order. */\nexport const HANDLER_NAMES = [\n  'validate',\n  'deploy',\n  'rollback',\n  'healthCheck',\n  'driftDetect',\n  'getStatus',\n] as const\n\nexport type HandlerName = (typeof HANDLER_NAMES)[number]\n\n/**\n * Conventional manifest paths for one configuration type — handy when\n * generating or checking a manifest programmatically.\n *\n * @example\n * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'\n */\nexport function conventionalPaths(configTypeId: string): {\n  canvasTemplate: string\n  defaultConfig: string\n  handlers: Record<HandlerName, string>\n} {\n  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`\n  const handlers = {} as Record<HandlerName, string>\n  for (const name of HANDLER_NAMES) {\n    handlers[name] = `${base}/${name}`\n  }\n  return {\n    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,\n    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,\n    handlers,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBO,SAAS,gBACd,SACqD;AACrD,SAAO;AACT;;;ACPO,SAAS,eACd,SAC+C;AAC/C,SAAO;AACT;;;ACfO,SAAS,sBACd,SACmD;AACnD,SAAO;AACT;;;ACJO,SAAS,oBACd,SACyD;AACzD,SAAO;AACT;;;ACJO,SAAS,oBACd,SAC6C;AAC7C,SAAO;AACT;;;ACJA,mBAAwD;AAqBxD,IAAM,cACH,WAAuC,yBAGvC;AAEI,IAAM,aACX,mBAAe,4BAAsC,IAAI;AAepD,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;ACtDA,IAAAA,gBAAiD;;;ACqB1C,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAmBO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;;;AD7CO,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AAEjB,YAAM,WAAW,MAAM,UAAU,+BAA+B,KAAK,EAAE;AACvE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;;;AE8DO,IAAM,mBAAmB,CAAC,YAAY,cAAc,QAAQ;AAS5D,IAAM,eAAe,CAAC,WAAW,OAAO,QAAQ;;;ACvHhD,IAAM,aAAa;AAAA;AAAA,EAExB,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMV,gBAAgB;AAAA;AAAA,EAEhB,YAAY;AAAA;AAAA,EAEZ,cAAc;AAAA;AAAA,EAEd,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,eAAe;AAAA;AAAA,EAEf,aAAa;AAAA;AAAA,EAEb,aAAa;AAAA;AAAA,EAEb,WAAW;AAAA;AAAA,EAEX,cAAc;AAChB;AAGO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,SAAS,kBAAkB,cAIhC;AACA,QAAM,OAAO,GAAG,WAAW,cAAc,IAAI,YAAY;AACzD,QAAM,WAAW,CAAC;AAClB,aAAW,QAAQ,eAAe;AAChC,aAAS,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI;AAAA,EAClC;AACA,SAAO;AAAA,IACL,gBAAgB,GAAG,IAAI,IAAI,WAAW,UAAU;AAAA,IAChD,eAAe,GAAG,IAAI,IAAI,WAAW,YAAY;AAAA,IACjD;AAAA,EACF;AACF;","names":["import_react"]}

package/dist/index.d.cts

@@ -1,3 +1,51 @@
 export { C as CanvasSectionSnapshot, a as CanvasSnapshot, b as ComponentConfigStatus, c as ComponentRef, d as ConfigStatus, e as ConnectivityProviderRef, f as ConnectivityRef, g as CredentialRef, D as DeployContext, h as DeployHandler, i as DeployResult, j as DeploymentStrategy, k as DeploymentSummary, l as DriftContext, m as DriftDetectHandler, n as DriftDiff, o as DriftResult, E as EnvironmentRef, G as GetStatusHandler, H as HealthCheck, p as HealthCheckContext, q as HealthCheckHandler, r as HealthCheckResult, P as PipelineContext, s as PlatformDataApi, R as RollbackContext, t as RollbackHandler, u as RollbackResult, U as UserRef, V as ValidateHandler, v as ValidationError, w as ValidationResult, x as ValidationWarning, y as defineDeployer, z as defineDriftDetector, A as defineHealthChecker, B as defineRollbackHandler, F as defineValidator } from './index-CKeIf4Jx.cjs';
-export { A as AppConfigurationTypeManifest, a as AppContext, b as AppContextValue, c as AppDetail, d as AppHookContext, e as AppInstallationDetail, f as AppInstallationStatus, g as AppListItem, h as AppManifest, i as AppPageDeclaration, j as AppPermissionDeclaration, k as AppRouteContext, l as AppSettingDeclaration, m as AppSource, n as AppStatusType, C as Component, o as Connectivity, p as Credential, q as Customer, P as PipelineStatusData, r as PlatformDatabaseClient, T as Tag, U as User, u as useAppContext, s as usePipelineStatus } from './index-BI8f_mBw.cjs';
+export { a as APP_PAGE_LAYOUTS, b as APP_PAGE_NAV, c as AppConfigurationTypeManifest, d as AppContext, A as AppContextValue, e as AppDetail, f as AppHookContext, g as AppInstallationDetail, h as AppInstallationStatus, i as AppListItem, j as AppManifest, k as AppPageDeclaration, l as AppPageLayout, m as AppPageNav, n as AppPagePermission, o as AppPermissionDeclaration, p as AppRouteContext, q as AppSettingDeclaration, r as AppSource, s as AppStatusType, C as Component, t as Connectivity, u as Credential, v as Customer, P as PlatformDatabaseClient, T as Tag, U as User, w as useAppContext } from './use-app-context-PBuG144m.cjs';
+export { PipelineStatusData, usePipelineStatus } from './hooks/index.cjs';
 import 'react';
+
+/** Canonical locations inside an app directory. */
+declare const APP_LAYOUT: {
+    /** The app contract. Always at the app root. */
+    readonly manifest: "manifest.yaml";
+    /**
+     * The unit of extension: config-types/<configTypeId>/ colocates everything
+     * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline
+     * handlers (extensionless in the manifest), and __tests__/.
+     */
+    readonly configTypesDir: "config-types";
+    /** Canvas form schema filename inside a config-type folder. */
+    readonly canvasFile: "canvas.yaml";
+    /** Default field values filename inside a config-type folder. */
+    readonly defaultsFile: "defaults.yaml";
+    /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */
+    readonly hooksDir: "hooks";
+    /** Shared app code used by multiple handlers (API clients, parsers). */
+    readonly libDir: "lib";
+    /** SQL migrations (requires manifest `database.tablePrefix`). */
+    readonly migrationsDir: "migrations";
+    /** Fastify route module receiving (fastify, AppRouteContext). */
+    readonly serverEntry: "server/index";
+    /** Client entry registering pages/sidebar items (optional). */
+    readonly clientEntry: "client/index";
+    /** Icons and logos (optional). */
+    readonly assetsDir: "assets";
+    /** Tests live next to the code they cover: handlers/<id>/__tests__/ */
+    readonly testsDirName: "__tests__";
+};
+/** The six pipeline handler names, in lifecycle order. */
+declare const HANDLER_NAMES: readonly ["validate", "deploy", "rollback", "healthCheck", "driftDetect", "getStatus"];
+type HandlerName = (typeof HANDLER_NAMES)[number];
+/**
+ * Conventional manifest paths for one configuration type — handy when
+ * generating or checking a manifest programmatically.
+ *
+ * @example
+ * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'
+ */
+declare function conventionalPaths(configTypeId: string): {
+    canvasTemplate: string;
+    defaultConfig: string;
+    handlers: Record<HandlerName, string>;
+};
+
+export { APP_LAYOUT, HANDLER_NAMES, type HandlerName, conventionalPaths };

package/dist/index.d.ts

@@ -1,3 +1,51 @@
 export { C as CanvasSectionSnapshot, a as CanvasSnapshot, b as ComponentConfigStatus, c as ComponentRef, d as ConfigStatus, e as ConnectivityProviderRef, f as ConnectivityRef, g as CredentialRef, D as DeployContext, h as DeployHandler, i as DeployResult, j as DeploymentStrategy, k as DeploymentSummary, l as DriftContext, m as DriftDetectHandler, n as DriftDiff, o as DriftResult, E as EnvironmentRef, G as GetStatusHandler, H as HealthCheck, p as HealthCheckContext, q as HealthCheckHandler, r as HealthCheckResult, P as PipelineContext, s as PlatformDataApi, R as RollbackContext, t as RollbackHandler, u as RollbackResult, U as UserRef, V as ValidateHandler, v as ValidationError, w as ValidationResult, x as ValidationWarning, y as defineDeployer, z as defineDriftDetector, A as defineHealthChecker, B as defineRollbackHandler, F as defineValidator } from './index-CKeIf4Jx.js';
-export { A as AppConfigurationTypeManifest, a as AppContext, b as AppContextValue, c as AppDetail, d as AppHookContext, e as AppInstallationDetail, f as AppInstallationStatus, g as AppListItem, h as AppManifest, i as AppPageDeclaration, j as AppPermissionDeclaration, k as AppRouteContext, l as AppSettingDeclaration, m as AppSource, n as AppStatusType, C as Component, o as Connectivity, p as Credential, q as Customer, P as PipelineStatusData, r as PlatformDatabaseClient, T as Tag, U as User, u as useAppContext, s as usePipelineStatus } from './index-BI8f_mBw.js';
+export { a as APP_PAGE_LAYOUTS, b as APP_PAGE_NAV, c as AppConfigurationTypeManifest, d as AppContext, A as AppContextValue, e as AppDetail, f as AppHookContext, g as AppInstallationDetail, h as AppInstallationStatus, i as AppListItem, j as AppManifest, k as AppPageDeclaration, l as AppPageLayout, m as AppPageNav, n as AppPagePermission, o as AppPermissionDeclaration, p as AppRouteContext, q as AppSettingDeclaration, r as AppSource, s as AppStatusType, C as Component, t as Connectivity, u as Credential, v as Customer, P as PlatformDatabaseClient, T as Tag, U as User, w as useAppContext } from './use-app-context-PBuG144m.js';
+export { PipelineStatusData, usePipelineStatus } from './hooks/index.js';
 import 'react';
+
+/** Canonical locations inside an app directory. */
+declare const APP_LAYOUT: {
+    /** The app contract. Always at the app root. */
+    readonly manifest: "manifest.yaml";
+    /**
+     * The unit of extension: config-types/<configTypeId>/ colocates everything
+     * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline
+     * handlers (extensionless in the manifest), and __tests__/.
+     */
+    readonly configTypesDir: "config-types";
+    /** Canvas form schema filename inside a config-type folder. */
+    readonly canvasFile: "canvas.yaml";
+    /** Default field values filename inside a config-type folder. */
+    readonly defaultsFile: "defaults.yaml";
+    /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */
+    readonly hooksDir: "hooks";
+    /** Shared app code used by multiple handlers (API clients, parsers). */
+    readonly libDir: "lib";
+    /** SQL migrations (requires manifest `database.tablePrefix`). */
+    readonly migrationsDir: "migrations";
+    /** Fastify route module receiving (fastify, AppRouteContext). */
+    readonly serverEntry: "server/index";
+    /** Client entry registering pages/sidebar items (optional). */
+    readonly clientEntry: "client/index";
+    /** Icons and logos (optional). */
+    readonly assetsDir: "assets";
+    /** Tests live next to the code they cover: handlers/<id>/__tests__/ */
+    readonly testsDirName: "__tests__";
+};
+/** The six pipeline handler names, in lifecycle order. */
+declare const HANDLER_NAMES: readonly ["validate", "deploy", "rollback", "healthCheck", "driftDetect", "getStatus"];
+type HandlerName = (typeof HANDLER_NAMES)[number];
+/**
+ * Conventional manifest paths for one configuration type — handy when
+ * generating or checking a manifest programmatically.
+ *
+ * @example
+ * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'
+ */
+declare function conventionalPaths(configTypeId: string): {
+    canvasTemplate: string;
+    defaultConfig: string;
+    handlers: Record<HandlerName, string>;
+};
+
+export { APP_LAYOUT, HANDLER_NAMES, type HandlerName, conventionalPaths };

package/dist/index.js

@@ -9,9 +9,69 @@ import {
   AppContext,
   useAppContext,
   usePipelineStatus
-} from "./chunk-TSEIWO6T.js";
+} from "./chunk-JDEA2F7I.js";
+import "./chunk-I4JJX4LL.js";
+
+// src/types/manifest.ts
+var APP_PAGE_LAYOUTS = ["standard", "full-bleed", "canvas"];
+var APP_PAGE_NAV = ["sidebar", "tab", "hidden"];
+
+// src/structure.ts
+var APP_LAYOUT = {
+  /** The app contract. Always at the app root. */
+  manifest: "manifest.yaml",
+  /**
+   * The unit of extension: config-types/<configTypeId>/ colocates everything
+   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline
+   * handlers (extensionless in the manifest), and __tests__/.
+   */
+  configTypesDir: "config-types",
+  /** Canvas form schema filename inside a config-type folder. */
+  canvasFile: "canvas.yaml",
+  /** Default field values filename inside a config-type folder. */
+  defaultsFile: "defaults.yaml",
+  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */
+  hooksDir: "hooks",
+  /** Shared app code used by multiple handlers (API clients, parsers). */
+  libDir: "lib",
+  /** SQL migrations (requires manifest `database.tablePrefix`). */
+  migrationsDir: "migrations",
+  /** Fastify route module receiving (fastify, AppRouteContext). */
+  serverEntry: "server/index",
+  /** Client entry registering pages/sidebar items (optional). */
+  clientEntry: "client/index",
+  /** Icons and logos (optional). */
+  assetsDir: "assets",
+  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */
+  testsDirName: "__tests__"
+};
+var HANDLER_NAMES = [
+  "validate",
+  "deploy",
+  "rollback",
+  "healthCheck",
+  "driftDetect",
+  "getStatus"
+];
+function conventionalPaths(configTypeId) {
+  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`;
+  const handlers = {};
+  for (const name of HANDLER_NAMES) {
+    handlers[name] = `${base}/${name}`;
+  }
+  return {
+    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,
+    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,
+    handlers
+  };
+}
 export {
+  APP_LAYOUT,
+  APP_PAGE_LAYOUTS,
+  APP_PAGE_NAV,
   AppContext,
+  HANDLER_NAMES,
+  conventionalPaths,
   defineDeployer,
   defineDriftDetector,
   defineHealthChecker,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/types/manifest.ts","../src/structure.ts"],"sourcesContent":["// ========================================================================\n// App manifest types\n//\n// Self-contained copy of the platform's manifest contract so the SDK can\n// be published and consumed outside the platform monorepo. The platform\n// keeps its own copy in shared/types/app.ts — changes to the manifest\n// contract must be applied to both files.\n// ========================================================================\n\nexport type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM'\nexport type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED'\nexport type AppInstallationStatus =\n  | 'INSTALLING'\n  | 'INSTALLED'\n  | 'ENABLED'\n  | 'DISABLED'\n  | 'FAILED'\n  | 'UNINSTALLING'\n\n// --- Manifest Types (parsed from manifest.yaml) ---\n\nexport interface AppManifest {\n  id: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  license?: string\n  homepage?: string\n  icon?: string\n  logo?: string\n\n  platform: {\n    minVersion: string\n  }\n\n  permissions: {\n    platform: string[] // Platform permissions the app needs\n    app: AppPermissionDeclaration[] // Permissions the app exposes\n  }\n\n  database?: {\n    migrations: string\n    tablePrefix: string\n  }\n\n  pipeline: {\n    configurationTypes: AppConfigurationTypeManifest[]\n    pipelineEvents?: string[]\n  }\n\n  server: {\n    entry: string\n    routes?: {\n      prefix: string\n    }\n  }\n\n  client?: {\n    entry: string\n    pages?: AppPageDeclaration[]\n  }\n\n  hooks?: {\n    onInstall?: string\n    onUninstall?: string\n    onEnable?: string\n    onDisable?: string\n    onUpgrade?: string\n  }\n\n  events?: string[] // Platform events this app subscribes to\n\n  settings?: AppSettingDeclaration[]\n}\n\nexport interface AppConfigurationTypeManifest {\n  id: string\n  name: string\n  description?: string\n  canvasTemplate: string // Path to canvas template YAML\n  defaultConfig?: string // Path to default config YAML\n\n  handlers: {\n    validate: string\n    deploy: string\n    rollback: string\n    healthCheck: string\n    driftDetect?: string | null\n    getStatus: string\n  }\n\n  targets: {\n    componentTypes: string[]\n    requiresCredential: boolean\n    requiresConnectivity: boolean\n  }\n}\n\nexport interface AppPermissionDeclaration {\n  resource: string\n  actions: string[]\n  description?: string\n}\n\n// --- App UI & navigation contract ---\n//\n// The platform owns the chrome: breadcrumb, app header, navigation, permission\n// gating, error boundary and loading states are rendered identically for every\n// app. Apps own the page body and compose it from @veltrixsecops/ui.\n// Predictable shell, flexible body.\n\n/**\n * How the platform frames an app page.\n * - `standard`   — page header + padded content area (default; use for most pages)\n * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)\n * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)\n */\nexport type AppPageLayout = 'standard' | 'full-bleed' | 'canvas'\nexport const APP_PAGE_LAYOUTS = ['standard', 'full-bleed', 'canvas'] as const\n\n/**\n * Where the page surfaces in navigation.\n * - `sidebar` — an entry beneath the app in the sidebar\n * - `tab`     — a tab within its `parent` page\n * - `hidden`  — routable but not linked (details/drill-down pages)\n */\nexport type AppPageNav = 'sidebar' | 'tab' | 'hidden'\nexport const APP_PAGE_NAV = ['sidebar', 'tab', 'hidden'] as const\n\n/** An app-scoped permission (declared in `permissions.app`) required to see a page. */\nexport interface AppPagePermission {\n  resource: string\n  action: string\n}\n\nexport interface AppPageDeclaration {\n  /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */\n  path: string\n  /** Exported component name from the app's client entry */\n  component: string\n  label: string\n  description?: string\n  /** Icon name from the platform icon set; falls back to the app icon */\n  icon?: string\n  /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */\n  sidebar?: boolean\n  /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */\n  nav?: AppPageNav\n  /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */\n  parent?: string\n  /** Optional sidebar section label, for apps with many pages */\n  group?: string\n  /** Deterministic ordering within its group/parent (ascending; ties break on label) */\n  order?: number\n  /** Layout preset the platform renders around the page body */\n  layout?: AppPageLayout\n  /** Hide the page (and its nav entry) unless the user holds this app permission */\n  requiresPermission?: AppPagePermission\n}\n\nexport interface AppSettingDeclaration {\n  key: string\n  type: 'string' | 'number' | 'boolean' | 'select'\n  label: string\n  description?: string\n  default?: string | number | boolean\n  required?: boolean\n  options?: Array<{ label: string; value: string }>\n}\n\n// --- API Response Types ---\n\nexport interface AppListItem {\n  id: string\n  appId: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  icon?: string\n  logo?: string\n  source: AppSource\n  isDefault: boolean\n  status: AppStatusType\n  installed?: boolean\n  enabled?: boolean\n}\n\nexport interface AppDetail extends AppListItem {\n  license?: string\n  homepage?: string\n  repository?: string\n  configurationTypes: Array<{\n    id: string\n    name: string\n    description?: string\n    componentTypes: string[]\n  }>\n  permissions: AppPermissionDeclaration[]\n  settings: AppSettingDeclaration[]\n}\n\nexport interface AppInstallationDetail {\n  id: string\n  appId: string\n  customerId: string\n  version: string\n  enabled: boolean\n  installedBy: string\n  installedAt: string\n  settings: Record<string, unknown>\n  status: AppInstallationStatus\n  app: AppListItem\n}\n","// ========================================================================\n// Canonical app layout\n//\n// Every Veltrix app follows one predictable folder structure so apps are\n// easy to set up, review, and load. The `veltrix` CLI scaffolds it,\n// `veltrix validate` (and repo CI) warn on deviations, and the platform's\n// app engine resolves manifest references against it.\n// ========================================================================\n\n/** Canonical locations inside an app directory. */\nexport const APP_LAYOUT = {\n  /** The app contract. Always at the app root. */\n  manifest: 'manifest.yaml',\n  /**\n   * The unit of extension: config-types/<configTypeId>/ colocates everything\n   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline\n   * handlers (extensionless in the manifest), and __tests__/.\n   */\n  configTypesDir: 'config-types',\n  /** Canvas form schema filename inside a config-type folder. */\n  canvasFile: 'canvas.yaml',\n  /** Default field values filename inside a config-type folder. */\n  defaultsFile: 'defaults.yaml',\n  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */\n  hooksDir: 'hooks',\n  /** Shared app code used by multiple handlers (API clients, parsers). */\n  libDir: 'lib',\n  /** SQL migrations (requires manifest `database.tablePrefix`). */\n  migrationsDir: 'migrations',\n  /** Fastify route module receiving (fastify, AppRouteContext). */\n  serverEntry: 'server/index',\n  /** Client entry registering pages/sidebar items (optional). */\n  clientEntry: 'client/index',\n  /** Icons and logos (optional). */\n  assetsDir: 'assets',\n  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */\n  testsDirName: '__tests__',\n} as const\n\n/** The six pipeline handler names, in lifecycle order. */\nexport const HANDLER_NAMES = [\n  'validate',\n  'deploy',\n  'rollback',\n  'healthCheck',\n  'driftDetect',\n  'getStatus',\n] as const\n\nexport type HandlerName = (typeof HANDLER_NAMES)[number]\n\n/**\n * Conventional manifest paths for one configuration type — handy when\n * generating or checking a manifest programmatically.\n *\n * @example\n * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'\n */\nexport function conventionalPaths(configTypeId: string): {\n  canvasTemplate: string\n  defaultConfig: string\n  handlers: Record<HandlerName, string>\n} {\n  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`\n  const handlers = {} as Record<HandlerName, string>\n  for (const name of HANDLER_NAMES) {\n    handlers[name] = `${base}/${name}`\n  }\n  return {\n    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,\n    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,\n    handlers,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwHO,IAAM,mBAAmB,CAAC,YAAY,cAAc,QAAQ;AAS5D,IAAM,eAAe,CAAC,WAAW,OAAO,QAAQ;;;ACvHhD,IAAM,aAAa;AAAA;AAAA,EAExB,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMV,gBAAgB;AAAA;AAAA,EAEhB,YAAY;AAAA;AAAA,EAEZ,cAAc;AAAA;AAAA,EAEd,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,eAAe;AAAA;AAAA,EAEf,aAAa;AAAA;AAAA,EAEb,aAAa;AAAA;AAAA,EAEb,WAAW;AAAA;AAAA,EAEX,cAAc;AAChB;AAGO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,SAAS,kBAAkB,cAIhC;AACA,QAAM,OAAO,GAAG,WAAW,cAAc,IAAI,YAAY;AACzD,QAAM,WAAW,CAAC;AAClB,aAAW,QAAQ,eAAe;AAChC,aAAS,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI;AAAA,EAClC;AACA,SAAO;AAAA,IACL,gBAAgB,GAAG,IAAI,IAAI,WAAW,UAAU;AAAA,IAChD,eAAe,GAAG,IAAI,IAAI,WAAW,YAAY;AAAA,IACjD;AAAA,EACF;AACF;","names":[]}

package/dist/{index-BI8f_mBw.d.cts → use-app-context-PBuG144m.d.cts}

@@ -1,4 +1,4 @@
-import * as react from 'react';
+import { Context } from 'react';
 
 type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM';
 type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED';
@@ -74,13 +74,50 @@ interface AppPermissionDeclaration {
     actions: string[];
     description?: string;
 }
+/**
+ * How the platform frames an app page.
+ * - `standard`   — page header + padded content area (default; use for most pages)
+ * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)
+ * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)
+ */
+type AppPageLayout = 'standard' | 'full-bleed' | 'canvas';
+declare const APP_PAGE_LAYOUTS: readonly ["standard", "full-bleed", "canvas"];
+/**
+ * Where the page surfaces in navigation.
+ * - `sidebar` — an entry beneath the app in the sidebar
+ * - `tab`     — a tab within its `parent` page
+ * - `hidden`  — routable but not linked (details/drill-down pages)
+ */
+type AppPageNav = 'sidebar' | 'tab' | 'hidden';
+declare const APP_PAGE_NAV: readonly ["sidebar", "tab", "hidden"];
+/** An app-scoped permission (declared in `permissions.app`) required to see a page. */
+interface AppPagePermission {
+    resource: string;
+    action: string;
+}
 interface AppPageDeclaration {
+    /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */
     path: string;
+    /** Exported component name from the app's client entry */
     component: string;
     label: string;
+    description?: string;
+    /** Icon name from the platform icon set; falls back to the app icon */
     icon?: string;
+    /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */
     sidebar?: boolean;
+    /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */
+    nav?: AppPageNav;
+    /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */
     parent?: string;
+    /** Optional sidebar section label, for apps with many pages */
+    group?: string;
+    /** Deterministic ordering within its group/parent (ascending; ties break on label) */
+    order?: number;
+    /** Layout preset the platform renders around the page body */
+    layout?: AppPageLayout;
+    /** Hide the page (and its nav entry) unless the user holds this app permission */
+    requiresPermission?: AppPagePermission;
 }
 interface AppSettingDeclaration {
     key: string;
@@ -232,7 +269,7 @@ interface AppContextValue {
     getTags: () => Promise<Tag[]>;
     settings: Record<string, unknown>;
 }
-declare const AppContext: react.Context<AppContextValue | null>;
+declare const AppContext: Context<AppContextValue | null>;
 /**
  * Access the app context in any app component.
  *
@@ -248,39 +285,4 @@ declare const AppContext: react.Context<AppContextValue | null>;
  */
 declare function useAppContext(): AppContextValue;
 
-interface PipelineStatusData {
-    pendingApprovals: number;
-    activeDeployments: number;
-    failedDeployments: number;
-    unresolvedDrifts: number;
-    recentDeployments: Array<{
-        id: string;
-        canvasName: string;
-        environment: string;
-        status: string;
-        startedAt: string;
-        completedAt?: string;
-    }>;
-}
-/**
- * Hook to access pipeline status for the current app/customer.
- *
- * @example
- * ```tsx
- * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
- *
- * function Dashboard() {
- *   const { data, isLoading } = usePipelineStatus('my-app')
- *   if (isLoading) return <Spinner />
- *   return <div>{data.activeDeployments} active deployments</div>
- * }
- * ```
- */
-declare function usePipelineStatus(appId: string): {
-    data: PipelineStatusData | null;
-    isLoading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-};
-
-export { type AppConfigurationTypeManifest as A, type Component as C, type PipelineStatusData as P, type Tag as T, type User as U, AppContext as a, type AppContextValue as b, type AppDetail as c, type AppHookContext as d, type AppInstallationDetail as e, type AppInstallationStatus as f, type AppListItem as g, type AppManifest as h, type AppPageDeclaration as i, type AppPermissionDeclaration as j, type AppRouteContext as k, type AppSettingDeclaration as l, type AppSource as m, type AppStatusType as n, type Connectivity as o, type Credential as p, type Customer as q, type PlatformDatabaseClient as r, usePipelineStatus as s, useAppContext as u };
+export { type AppContextValue as A, type Component as C, type PlatformDatabaseClient as P, type Tag as T, type User as U, APP_PAGE_LAYOUTS as a, APP_PAGE_NAV as b, type AppConfigurationTypeManifest as c, AppContext as d, type AppDetail as e, type AppHookContext as f, type AppInstallationDetail as g, type AppInstallationStatus as h, type AppListItem as i, type AppManifest as j, type AppPageDeclaration as k, type AppPageLayout as l, type AppPageNav as m, type AppPagePermission as n, type AppPermissionDeclaration as o, type AppRouteContext as p, type AppSettingDeclaration as q, type AppSource as r, type AppStatusType as s, type Connectivity as t, type Credential as u, type Customer as v, useAppContext as w };

package/dist/{index-BI8f_mBw.d.ts → use-app-context-PBuG144m.d.ts}

@@ -1,4 +1,4 @@
-import * as react from 'react';
+import { Context } from 'react';
 
 type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM';
 type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED';
@@ -74,13 +74,50 @@ interface AppPermissionDeclaration {
     actions: string[];
     description?: string;
 }
+/**
+ * How the platform frames an app page.
+ * - `standard`   — page header + padded content area (default; use for most pages)
+ * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)
+ * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)
+ */
+type AppPageLayout = 'standard' | 'full-bleed' | 'canvas';
+declare const APP_PAGE_LAYOUTS: readonly ["standard", "full-bleed", "canvas"];
+/**
+ * Where the page surfaces in navigation.
+ * - `sidebar` — an entry beneath the app in the sidebar
+ * - `tab`     — a tab within its `parent` page
+ * - `hidden`  — routable but not linked (details/drill-down pages)
+ */
+type AppPageNav = 'sidebar' | 'tab' | 'hidden';
+declare const APP_PAGE_NAV: readonly ["sidebar", "tab", "hidden"];
+/** An app-scoped permission (declared in `permissions.app`) required to see a page. */
+interface AppPagePermission {
+    resource: string;
+    action: string;
+}
 interface AppPageDeclaration {
+    /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */
     path: string;
+    /** Exported component name from the app's client entry */
     component: string;
     label: string;
+    description?: string;
+    /** Icon name from the platform icon set; falls back to the app icon */
     icon?: string;
+    /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */
     sidebar?: boolean;
+    /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */
+    nav?: AppPageNav;
+    /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */
     parent?: string;
+    /** Optional sidebar section label, for apps with many pages */
+    group?: string;
+    /** Deterministic ordering within its group/parent (ascending; ties break on label) */
+    order?: number;
+    /** Layout preset the platform renders around the page body */
+    layout?: AppPageLayout;
+    /** Hide the page (and its nav entry) unless the user holds this app permission */
+    requiresPermission?: AppPagePermission;
 }
 interface AppSettingDeclaration {
     key: string;
@@ -232,7 +269,7 @@ interface AppContextValue {
     getTags: () => Promise<Tag[]>;
     settings: Record<string, unknown>;
 }
-declare const AppContext: react.Context<AppContextValue | null>;
+declare const AppContext: Context<AppContextValue | null>;
 /**
  * Access the app context in any app component.
  *
@@ -248,39 +285,4 @@ declare const AppContext: react.Context<AppContextValue | null>;
  */
 declare function useAppContext(): AppContextValue;
 
-interface PipelineStatusData {
-    pendingApprovals: number;
-    activeDeployments: number;
-    failedDeployments: number;
-    unresolvedDrifts: number;
-    recentDeployments: Array<{
-        id: string;
-        canvasName: string;
-        environment: string;
-        status: string;
-        startedAt: string;
-        completedAt?: string;
-    }>;
-}
-/**
- * Hook to access pipeline status for the current app/customer.
- *
- * @example
- * ```tsx
- * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
- *
- * function Dashboard() {
- *   const { data, isLoading } = usePipelineStatus('my-app')
- *   if (isLoading) return <Spinner />
- *   return <div>{data.activeDeployments} active deployments</div>
- * }
- * ```
- */
-declare function usePipelineStatus(appId: string): {
-    data: PipelineStatusData | null;
-    isLoading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-};
-
-export { type AppConfigurationTypeManifest as A, type Component as C, type PipelineStatusData as P, type Tag as T, type User as U, AppContext as a, type AppContextValue as b, type AppDetail as c, type AppHookContext as d, type AppInstallationDetail as e, type AppInstallationStatus as f, type AppListItem as g, type AppManifest as h, type AppPageDeclaration as i, type AppPermissionDeclaration as j, type AppRouteContext as k, type AppSettingDeclaration as l, type AppSource as m, type AppStatusType as n, type Connectivity as o, type Credential as p, type Customer as q, type PlatformDatabaseClient as r, usePipelineStatus as s, useAppContext as u };
+export { type AppContextValue as A, type Component as C, type PlatformDatabaseClient as P, type Tag as T, type User as U, APP_PAGE_LAYOUTS as a, APP_PAGE_NAV as b, type AppConfigurationTypeManifest as c, AppContext as d, type AppDetail as e, type AppHookContext as f, type AppInstallationDetail as g, type AppInstallationStatus as h, type AppListItem as i, type AppManifest as j, type AppPageDeclaration as k, type AppPageLayout as l, type AppPageNav as m, type AppPagePermission as n, type AppPermissionDeclaration as o, type AppRouteContext as p, type AppSettingDeclaration as q, type AppSource as r, type AppStatusType as s, type Connectivity as t, type Credential as u, type Customer as v, useAppContext as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltrixsecops/app-sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Official SDK for building Veltrix Security-as-Code apps — typed pipeline handler contracts, lifecycle hook types, manifest types, and React hooks.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -37,7 +37,18 @@
         "types": "./dist/hooks/index.d.cts",
         "default": "./dist/hooks/index.cjs"
       }
-    }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -75,10 +86,10 @@
     "plugin"
   ],
   "license": "MIT",
-  "homepage": "https://github.com/captivatortechnologies/Veltrix/tree/main/app-sdk",
+  "homepage": "https://github.com/captivatortechnologies/veltrix-apps/tree/main/sdk",
   "repository": {
     "type": "git",
-    "url": "https://github.com/captivatortechnologies/Veltrix.git",
-    "directory": "app-sdk"
+    "url": "git+https://github.com/captivatortechnologies/veltrix-apps.git",
+    "directory": "sdk"
   }
 }

package/dist/chunk-TSEIWO6T.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts"],"sourcesContent":["// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\nexport const AppContext = createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      const response = await fetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n"],"mappings":";AAKA,SAAS,eAAe,kBAAkB;AAkBnC,IAAM,aAAa,cAAsC,IAAI;AAe7D,SAAS,gBAAiC;AAC/C,QAAM,MAAM,WAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC5CA,SAAS,UAAU,WAAW,mBAAmB;AA+B1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,IAAI,SAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,QAAM,UAAU,YAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AACjB,YAAM,WAAW,MAAM,MAAM,+BAA+B,KAAK,EAAE;AACnE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,YAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":[]}