@khal-os/types 1.0.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2026 KhalOS
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,19 @@
+# @khal-os/types
+
+Shared TypeScript type definitions for the KhalOS ecosystem. Includes types for authentication, app manifests, NATS messaging, and role definitions.
+
+## Install
+
+```bash
+npm install @khal-os/types
+```
+
+## Usage
+
+```ts
+import type { KhalAppManifest, KhalRole, NatsSubject } from '@khal-os/types';
+```
+
+## License
+
+[Elastic License 2.0 (ELv2)](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,33 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ROLE_HIERARCHY: () => ROLE_HIERARCHY
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/roles.ts
+var ROLE_HIERARCHY = ["member", "platform-dev", "platform-admin", "platform-owner"];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ROLE_HIERARCHY
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/roles.ts"],"sourcesContent":["export type { KhalAuth } from './auth';\nexport type {\n\tAppDeployConfig,\n\tAppDesktopConfig,\n\tAppEnvVar,\n\tAppManifest,\n\tAppManifestView,\n\tAppServiceConfig,\n\tAppTauriConfig,\n\tServiceHealthConfig,\n} from './manifest';\nexport type { ConnectionState } from './nats';\nexport type { Role } from './roles';\nexport { ROLE_HIERARCHY } from './roles';\n","/** Canonical role hierarchy from least to most privileged. */\nexport const ROLE_HIERARCHY = ['member', 'platform-dev', 'platform-admin', 'platform-owner'] as const;\nexport type Role = (typeof ROLE_HIERARCHY)[number];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCO,IAAM,iBAAiB,CAAC,UAAU,gBAAgB,kBAAkB,gBAAgB;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,191 @@
+/** Authenticated user state returned by `useKhalAuth`. */
+interface KhalAuth {
+    userId: string;
+    orgId: string;
+    role: string;
+    permissions: string[];
+    loading: boolean;
+}
+
+/** Canonical role hierarchy from least to most privileged. */
+declare const ROLE_HIERARCHY: readonly ["member", "platform-dev", "platform-admin", "platform-owner"];
+type Role = (typeof ROLE_HIERARCHY)[number];
+
+/** Desktop integration metadata for an app. */
+interface AppDesktopConfig {
+    /** Path to the app icon (relative to the public directory). */
+    icon: string;
+    /** Categories for desktop launcher grouping. */
+    categories: string[];
+    /** Short description shown in the desktop launcher. */
+    comment: string;
+}
+/** A single view within an app manifest. */
+interface AppManifestView {
+    /** Unique view identifier within the app. */
+    id: string;
+    /** Human-readable label for the view. */
+    label: string;
+    /** Permission string required to access this view. */
+    permission: string;
+    /** Minimum role level required. */
+    minRole: Role;
+    /** NATS subject segment after `khal.<orgId>.` for this view's services. */
+    natsPrefix?: string;
+    /** Default window dimensions. */
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    /** Relative path to the view's React component. */
+    component: string;
+}
+/** Health check configuration for a service. */
+interface ServiceHealthConfig {
+    /** Check type: tcp (connect to port), http (GET endpoint), command (run shell). */
+    type: 'tcp' | 'http' | 'command';
+    /** Target: port number for tcp, URL for http, shell command for command. */
+    target: string | number;
+    /** Check interval in milliseconds (default: 30000). */
+    interval?: number;
+    /** Timeout in milliseconds (default: 5000). */
+    timeout?: number;
+}
+/** Service declaration within an app manifest. */
+interface AppServiceConfig {
+    /** Service name (must be unique across the app). */
+    name: string;
+    /** Shell command to start the service (alternative to entry). */
+    command?: string;
+    /** Entry point file path relative to the package root. */
+    entry?: string;
+    /** Runtime environment. */
+    runtime?: 'node' | 'python';
+    /** Health check configuration. */
+    health?: ServiceHealthConfig;
+    /** Restart policy. */
+    restart?: 'always' | 'on-failure' | 'never';
+    /** Ports the service binds to internally. Khal assigns proxy ports. */
+    ports?: number[];
+}
+/** Environment variable declaration for app configuration. */
+interface AppEnvVar {
+    /** Variable name (e.g., "API_KEY"). */
+    key: string;
+    /** Human-readable description shown in the config UI. */
+    description: string;
+    /** Whether the variable is required for the app to run. */
+    required: boolean;
+    /** Default value if not configured. */
+    default?: string;
+    /** Value type — affects config UI rendering and validation. */
+    type?: 'string' | 'number' | 'boolean' | 'secret' | 'url';
+    /** Storage: 'config' for plain ConfigMap, 'vault' for Kubernetes Secret. */
+    visibility?: 'config' | 'vault';
+}
+/** Kubernetes deployment configuration for apps with backends. */
+interface AppDeployConfig {
+    /** Dockerfile path relative to app root (default: "Dockerfile"). */
+    dockerfile?: string;
+    /** Build args passed to docker build. */
+    buildArgs?: Record<string, string>;
+    /** Container port the app listens on. */
+    port?: number;
+    /** Resource requests and limits for the pod. */
+    resources?: {
+        requests?: {
+            cpu?: string;
+            memory?: string;
+        };
+        limits?: {
+            cpu?: string;
+            memory?: string;
+        };
+    };
+    /** Replica count (default: 1). */
+    replicas?: number;
+    /** Health check path for k8s readiness/liveness probes. */
+    healthPath?: string;
+    /** Ingress configuration for per-app routing. */
+    ingress?: {
+        /** Subdomain prefix: <value>.apps.<domain>. Defaults to app id. */
+        subdomain?: string;
+        /** Additional path prefixes to route to this app. */
+        pathPrefixes?: string[];
+    };
+    /** Horizontal Pod Autoscaler configuration. */
+    autoscaling?: {
+        enabled: boolean;
+        minReplicas?: number;
+        maxReplicas?: number;
+        targetCPU?: number;
+    };
+    /** Environment sources injected at runtime from k8s resources. */
+    envFrom?: Array<{
+        secretRef?: string;
+        configMapRef?: string;
+    }>;
+}
+/** Tauri standalone export configuration. */
+interface AppTauriConfig {
+    /** Whether this app supports standalone Tauri export. */
+    exportable: boolean;
+    /** Path to src-tauri/ directory (default: "./src-tauri"). */
+    tauriDir?: string;
+    /** App name for the exported binary. */
+    appName?: string;
+    /** App icon path relative to app root. */
+    icon?: string;
+    /** Window configuration for standalone mode. */
+    window?: {
+        width?: number;
+        height?: number;
+        title?: string;
+    };
+}
+/**
+ * Full app manifest — the type for `manifest.ts` files in KhalOS app packages.
+ *
+ * Every app package must export a default manifest conforming to this shape.
+ * Use `defineManifest()` for compile-time validation and autocomplete.
+ *
+ * The JSON equivalent (`khal-app.json`) uses the same shape and is the
+ * language-agnostic install-time contract that the marketplace reads.
+ */
+interface AppManifest {
+    /** Unique app identifier (must match the package directory name). */
+    id: string;
+    /** One or more views the app exposes. */
+    views: AppManifestView[];
+    /** Desktop integration configuration. */
+    desktop: AppDesktopConfig;
+    /** Backend services this app runs. Optional — pure UI apps have no services. */
+    services?: AppServiceConfig[];
+    /** Schema version for forward compatibility (default: 1). */
+    schemaVersion?: number;
+    /** Human-readable app name. */
+    name?: string;
+    /** Semantic version of the app. */
+    version?: string;
+    /** Short description for the marketplace listing. */
+    description?: string;
+    /** Author name or organization. */
+    author?: string;
+    /** SPDX license identifier. */
+    license?: string;
+    /** Source repository URL. */
+    repository?: string;
+    /** Minimum KhalOS host version required. */
+    minHostVersion?: string;
+    /** Environment variables the app needs — auto-generates config UI. */
+    env?: AppEnvVar[];
+    /** Native Kubernetes deployment configuration. */
+    deploy?: AppDeployConfig;
+    /** Tauri standalone export configuration. */
+    tauri?: AppTauriConfig;
+}
+
+/** Connection states reported by the WS relay. */
+type ConnectionState = 'connected' | 'reconnecting' | 'disconnected' | 'auth_expired' | 'version_mismatch';
+
+export { type AppDeployConfig, type AppDesktopConfig, type AppEnvVar, type AppManifest, type AppManifestView, type AppServiceConfig, type AppTauriConfig, type ConnectionState, type KhalAuth, ROLE_HIERARCHY, type Role, type ServiceHealthConfig };

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/** Authenticated user state returned by `useKhalAuth`. */
+interface KhalAuth {
+    userId: string;
+    orgId: string;
+    role: string;
+    permissions: string[];
+    loading: boolean;
+}
+
+/** Canonical role hierarchy from least to most privileged. */
+declare const ROLE_HIERARCHY: readonly ["member", "platform-dev", "platform-admin", "platform-owner"];
+type Role = (typeof ROLE_HIERARCHY)[number];
+
+/** Desktop integration metadata for an app. */
+interface AppDesktopConfig {
+    /** Path to the app icon (relative to the public directory). */
+    icon: string;
+    /** Categories for desktop launcher grouping. */
+    categories: string[];
+    /** Short description shown in the desktop launcher. */
+    comment: string;
+}
+/** A single view within an app manifest. */
+interface AppManifestView {
+    /** Unique view identifier within the app. */
+    id: string;
+    /** Human-readable label for the view. */
+    label: string;
+    /** Permission string required to access this view. */
+    permission: string;
+    /** Minimum role level required. */
+    minRole: Role;
+    /** NATS subject segment after `khal.<orgId>.` for this view's services. */
+    natsPrefix?: string;
+    /** Default window dimensions. */
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    /** Relative path to the view's React component. */
+    component: string;
+}
+/** Health check configuration for a service. */
+interface ServiceHealthConfig {
+    /** Check type: tcp (connect to port), http (GET endpoint), command (run shell). */
+    type: 'tcp' | 'http' | 'command';
+    /** Target: port number for tcp, URL for http, shell command for command. */
+    target: string | number;
+    /** Check interval in milliseconds (default: 30000). */
+    interval?: number;
+    /** Timeout in milliseconds (default: 5000). */
+    timeout?: number;
+}
+/** Service declaration within an app manifest. */
+interface AppServiceConfig {
+    /** Service name (must be unique across the app). */
+    name: string;
+    /** Shell command to start the service (alternative to entry). */
+    command?: string;
+    /** Entry point file path relative to the package root. */
+    entry?: string;
+    /** Runtime environment. */
+    runtime?: 'node' | 'python';
+    /** Health check configuration. */
+    health?: ServiceHealthConfig;
+    /** Restart policy. */
+    restart?: 'always' | 'on-failure' | 'never';
+    /** Ports the service binds to internally. Khal assigns proxy ports. */
+    ports?: number[];
+}
+/** Environment variable declaration for app configuration. */
+interface AppEnvVar {
+    /** Variable name (e.g., "API_KEY"). */
+    key: string;
+    /** Human-readable description shown in the config UI. */
+    description: string;
+    /** Whether the variable is required for the app to run. */
+    required: boolean;
+    /** Default value if not configured. */
+    default?: string;
+    /** Value type — affects config UI rendering and validation. */
+    type?: 'string' | 'number' | 'boolean' | 'secret' | 'url';
+    /** Storage: 'config' for plain ConfigMap, 'vault' for Kubernetes Secret. */
+    visibility?: 'config' | 'vault';
+}
+/** Kubernetes deployment configuration for apps with backends. */
+interface AppDeployConfig {
+    /** Dockerfile path relative to app root (default: "Dockerfile"). */
+    dockerfile?: string;
+    /** Build args passed to docker build. */
+    buildArgs?: Record<string, string>;
+    /** Container port the app listens on. */
+    port?: number;
+    /** Resource requests and limits for the pod. */
+    resources?: {
+        requests?: {
+            cpu?: string;
+            memory?: string;
+        };
+        limits?: {
+            cpu?: string;
+            memory?: string;
+        };
+    };
+    /** Replica count (default: 1). */
+    replicas?: number;
+    /** Health check path for k8s readiness/liveness probes. */
+    healthPath?: string;
+    /** Ingress configuration for per-app routing. */
+    ingress?: {
+        /** Subdomain prefix: <value>.apps.<domain>. Defaults to app id. */
+        subdomain?: string;
+        /** Additional path prefixes to route to this app. */
+        pathPrefixes?: string[];
+    };
+    /** Horizontal Pod Autoscaler configuration. */
+    autoscaling?: {
+        enabled: boolean;
+        minReplicas?: number;
+        maxReplicas?: number;
+        targetCPU?: number;
+    };
+    /** Environment sources injected at runtime from k8s resources. */
+    envFrom?: Array<{
+        secretRef?: string;
+        configMapRef?: string;
+    }>;
+}
+/** Tauri standalone export configuration. */
+interface AppTauriConfig {
+    /** Whether this app supports standalone Tauri export. */
+    exportable: boolean;
+    /** Path to src-tauri/ directory (default: "./src-tauri"). */
+    tauriDir?: string;
+    /** App name for the exported binary. */
+    appName?: string;
+    /** App icon path relative to app root. */
+    icon?: string;
+    /** Window configuration for standalone mode. */
+    window?: {
+        width?: number;
+        height?: number;
+        title?: string;
+    };
+}
+/**
+ * Full app manifest — the type for `manifest.ts` files in KhalOS app packages.
+ *
+ * Every app package must export a default manifest conforming to this shape.
+ * Use `defineManifest()` for compile-time validation and autocomplete.
+ *
+ * The JSON equivalent (`khal-app.json`) uses the same shape and is the
+ * language-agnostic install-time contract that the marketplace reads.
+ */
+interface AppManifest {
+    /** Unique app identifier (must match the package directory name). */
+    id: string;
+    /** One or more views the app exposes. */
+    views: AppManifestView[];
+    /** Desktop integration configuration. */
+    desktop: AppDesktopConfig;
+    /** Backend services this app runs. Optional — pure UI apps have no services. */
+    services?: AppServiceConfig[];
+    /** Schema version for forward compatibility (default: 1). */
+    schemaVersion?: number;
+    /** Human-readable app name. */
+    name?: string;
+    /** Semantic version of the app. */
+    version?: string;
+    /** Short description for the marketplace listing. */
+    description?: string;
+    /** Author name or organization. */
+    author?: string;
+    /** SPDX license identifier. */
+    license?: string;
+    /** Source repository URL. */
+    repository?: string;
+    /** Minimum KhalOS host version required. */
+    minHostVersion?: string;
+    /** Environment variables the app needs — auto-generates config UI. */
+    env?: AppEnvVar[];
+    /** Native Kubernetes deployment configuration. */
+    deploy?: AppDeployConfig;
+    /** Tauri standalone export configuration. */
+    tauri?: AppTauriConfig;
+}
+
+/** Connection states reported by the WS relay. */
+type ConnectionState = 'connected' | 'reconnecting' | 'disconnected' | 'auth_expired' | 'version_mismatch';
+
+export { type AppDeployConfig, type AppDesktopConfig, type AppEnvVar, type AppManifest, type AppManifestView, type AppServiceConfig, type AppTauriConfig, type ConnectionState, type KhalAuth, ROLE_HIERARCHY, type Role, type ServiceHealthConfig };

package/dist/index.js

@@ -0,0 +1,6 @@
+// src/roles.ts
+var ROLE_HIERARCHY = ["member", "platform-dev", "platform-admin", "platform-owner"];
+export {
+  ROLE_HIERARCHY
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/roles.ts"],"sourcesContent":["/** Canonical role hierarchy from least to most privileged. */\nexport const ROLE_HIERARCHY = ['member', 'platform-dev', 'platform-admin', 'platform-owner'] as const;\nexport type Role = (typeof ROLE_HIERARCHY)[number];\n"],"mappings":";AACO,IAAM,iBAAiB,CAAC,UAAU,gBAAgB,kBAAkB,gBAAgB;","names":[]}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@khal-os/types",
+  "version": "1.0.0",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Elastic-2.0",
+  "scripts": {
+    "build": "tsup"
+  }
+}