create-ekka-desktop-app 0.2.2

package/template/src/ekka/backend/demo.ts

@@ -0,0 +1,151 @@
+/**
+ * EKKA Demo Backend
+ *
+ * In-memory implementation for development/testing.
+ * Only implements ops that have real Rust implementations.
+ */
+
+import type { EngineRequest, EngineResponse } from '../types';
+import type { Backend } from './interface';
+import { OPS, ERROR_CODES } from '../constants';
+import { ok, err } from '../types';
+import branding from '../../../branding/app.json';
+
+// Derive display-only home path from branding (no OS detection, works in browser)
+function slugify(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+const DEMO_HOME_PATH = `~/.local/share/${slugify(branding.name) || 'ekka-desktop'}`;
+
+/**
+ * Demo backend using in-memory storage.
+ * Used when Tauri engine is not available.
+ */
+export class DemoBackend implements Backend {
+  private connected = false;
+  private authContext: { tenantId: string; sub: string; jwt: string } | null = null;
+  private homeGranted = false;
+
+  async connect(): Promise<void> {
+    await Promise.resolve();
+    this.connected = true;
+  }
+
+  disconnect(): void {
+    this.connected = false;
+    this.authContext = null;
+    this.homeGranted = false;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async request(req: EngineRequest): Promise<EngineResponse> {
+    await Promise.resolve();
+    return this.handle(req);
+  }
+
+  private handle(req: EngineRequest): EngineResponse {
+    // Check connection for non-runtime ops
+    if (req.op !== OPS.RUNTIME_INFO && !this.connected) {
+      return err(ERROR_CODES.NOT_CONNECTED, 'Not connected. Call ekka.connect() first.');
+    }
+
+    switch (req.op) {
+      // -----------------------------------------------------------------------
+      // Runtime
+      // -----------------------------------------------------------------------
+      case OPS.RUNTIME_INFO: {
+        return ok({
+          runtime: 'demo',
+          engine_present: false,
+          mode: 'demo',
+          homeState: this.getHomeState(),
+          homePath: DEMO_HOME_PATH,
+        });
+      }
+
+      // -----------------------------------------------------------------------
+      // Auth
+      // -----------------------------------------------------------------------
+      case OPS.AUTH_SET: {
+        const payload = req.payload as { tenantId?: string; sub?: string; jwt?: string };
+
+        if (!payload?.tenantId || !payload?.sub || !payload?.jwt) {
+          return err(ERROR_CODES.INVALID_PAYLOAD, 'Missing tenantId, sub, or jwt');
+        }
+
+        this.authContext = {
+          tenantId: payload.tenantId,
+          sub: payload.sub,
+          jwt: payload.jwt,
+        };
+
+        return ok({ ok: true });
+      }
+
+      // -----------------------------------------------------------------------
+      // Home
+      // -----------------------------------------------------------------------
+      case OPS.HOME_STATUS: {
+        return ok({
+          state: this.getHomeState(),
+          homePath: DEMO_HOME_PATH,
+          grantPresent: this.homeGranted,
+          reason: this.homeGranted ? null : 'Demo mode - call home.grant to simulate',
+        });
+      }
+
+      case OPS.HOME_GRANT: {
+        if (!this.authContext) {
+          return err(ERROR_CODES.NOT_AUTHENTICATED, 'Must call auth.set before home.grant');
+        }
+
+        // Simulate grant issuance
+        this.homeGranted = true;
+
+        return ok({
+          success: true,
+          grant_id: 'demo-grant-' + Date.now(),
+          expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
+        });
+      }
+
+      // -----------------------------------------------------------------------
+      // Setup (pre-login) - only checks node credentials
+      // Home folder grant is post-login
+      // -----------------------------------------------------------------------
+      case OPS.SETUP_STATUS: {
+        // In demo mode, node credentials are never configured
+        return ok({
+          nodeIdentity: 'not_configured',
+          setupComplete: false,
+        });
+      }
+
+      // -----------------------------------------------------------------------
+      // Unknown
+      // -----------------------------------------------------------------------
+      default:
+        return err(ERROR_CODES.INVALID_OP, `Unknown operation: ${req.op}`);
+    }
+  }
+
+  private getHomeState(): string {
+    if (this.homeGranted) return 'HOME_GRANTED';
+    if (this.authContext) return 'AUTHENTICATED_NO_HOME_GRANT';
+    return 'BOOTSTRAP_PRE_LOGIN';
+  }
+
+  /**
+   * Reset all state (for testing).
+   */
+  resetAll(): void {
+    this.connected = false;
+    this.authContext = null;
+    this.homeGranted = false;
+  }
+}
+
+export const demoBackend = new DemoBackend();

package/template/src/ekka/backend/interface.ts

@@ -0,0 +1,36 @@
+/**
+ * EKKA Backend Interface
+ *
+ * Defines the contract for all backend implementations.
+ * Both DemoBackend and EngineBackend implement this interface.
+ */
+
+import type { EngineRequest, EngineResponse } from '../types';
+
+/**
+ * Backend interface for EKKA operations.
+ * All requests flow through a backend implementing this interface.
+ */
+export interface Backend {
+  /**
+   * Connect to the backend.
+   * Must be called before any db/queue operations.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from the backend.
+   */
+  disconnect(): void;
+
+  /**
+   * Check if connected to the backend.
+   */
+  isConnected(): boolean;
+
+  /**
+   * Send a request to the backend and receive a response.
+   * Single RPC method for all operations.
+   */
+  request(req: EngineRequest): Promise<EngineResponse>;
+}

package/template/src/ekka/config.ts

@@ -0,0 +1,48 @@
+/**
+ * EKKA Configuration
+ *
+ * API configuration and client identity constants.
+ */
+
+// =============================================================================
+// API CONFIGURATION
+// =============================================================================
+
+const getApiUrl = (): string => {
+  if (import.meta.env.PROD) return 'https://api.ekka.ai';
+  if (import.meta.env.VITE_EKKA_API_URL) return import.meta.env.VITE_EKKA_API_URL;
+  return 'https://api.ekka.ai';
+};
+
+/** API base URL */
+export const API_BASE_URL = getApiUrl();
+
+// =============================================================================
+// ENGINE CONFIGURATION
+// =============================================================================
+
+const getEngineUrl = (): string => {
+  if (import.meta.env.VITE_EKKA_ENGINE_URL) return import.meta.env.VITE_EKKA_ENGINE_URL;
+  return 'http://localhost:3200'; // Default local engine port
+};
+
+/** Engine base URL for workflow runs */
+export const ENGINE_BASE_URL = getEngineUrl();
+
+// =============================================================================
+// CLIENT IDENTITY (Security Envelope)
+// =============================================================================
+
+export const CLIENT_TYPE = 'desktop';
+export const CLIENT_VERSION = '0.2.0';
+
+// =============================================================================
+// AUTH ENDPOINTS
+// =============================================================================
+
+export const AUTH_ENDPOINTS = {
+  login: '/auth/login',
+  refresh: '/auth/refresh',
+  logout: '/auth/logout',
+  me: '/auth/me',
+} as const;

package/template/src/ekka/constants.ts

@@ -0,0 +1,143 @@
+/**
+ * EKKA Constants
+ *
+ * Operation names and error codes.
+ * Only includes IMPLEMENTED operations.
+ */
+
+// =============================================================================
+// OPERATION NAMES (only implemented ops)
+// =============================================================================
+
+export const OPS = {
+  // Setup
+  SETUP_STATUS: 'setup.status',
+
+  // Runtime
+  RUNTIME_INFO: 'runtime.info',
+
+  // Auth
+  AUTH_SET: 'auth.set',
+
+  // Node Session
+  NODE_SESSION_ENSURE_IDENTITY: 'nodeSession.ensureIdentity',
+  NODE_SESSION_BOOTSTRAP: 'nodeSession.bootstrap',
+  NODE_SESSION_STATUS: 'nodeSession.status',
+
+  // Node Credentials (keychain-stored)
+  NODE_CREDENTIALS_SET: 'nodeCredentials.set',
+  NODE_CREDENTIALS_STATUS: 'nodeCredentials.status',
+  NODE_CREDENTIALS_CLEAR: 'nodeCredentials.clear',
+
+  // Runner
+  RUNNER_STATUS: 'runner.status',
+  RUNNER_TASK_STATS: 'runner.taskStats',
+
+  // Workflow Runs (proxied via Rust)
+  WORKFLOW_RUNS_CREATE: 'workflowRuns.create',
+  WORKFLOW_RUNS_GET: 'workflowRuns.get',
+
+  // Auth (proxied via Rust)
+  AUTH_LOGIN: 'auth.login',
+  AUTH_REFRESH: 'auth.refresh',
+  AUTH_LOGOUT: 'auth.logout',
+
+  // Home
+  HOME_STATUS: 'home.status',
+  HOME_GRANT: 'home.grant',
+
+  // Paths
+  PATHS_CHECK: 'paths.check',
+  PATHS_LIST: 'paths.list',
+  PATHS_GET: 'paths.get',
+  PATHS_REQUEST: 'paths.request',
+  PATHS_REMOVE: 'paths.remove',
+
+  // Vault - Status/Capabilities
+  VAULT_STATUS: 'vault.status',
+  VAULT_CAPABILITIES: 'vault.capabilities',
+
+  // Vault - Secrets
+  VAULT_SECRETS_LIST: 'vault.secrets.list',
+  VAULT_SECRETS_GET: 'vault.secrets.get',
+  VAULT_SECRETS_CREATE: 'vault.secrets.create',
+  VAULT_SECRETS_UPDATE: 'vault.secrets.update',
+  VAULT_SECRETS_DELETE: 'vault.secrets.delete',
+  VAULT_SECRETS_UPSERT: 'vault.secrets.upsert',
+
+  // Vault - Bundles
+  VAULT_BUNDLES_LIST: 'vault.bundles.list',
+  VAULT_BUNDLES_GET: 'vault.bundles.get',
+  VAULT_BUNDLES_CREATE: 'vault.bundles.create',
+  VAULT_BUNDLES_RENAME: 'vault.bundles.rename',
+  VAULT_BUNDLES_DELETE: 'vault.bundles.delete',
+  VAULT_BUNDLES_LIST_SECRETS: 'vault.bundles.listSecrets',
+  VAULT_BUNDLES_ADD_SECRET: 'vault.bundles.addSecret',
+  VAULT_BUNDLES_REMOVE_SECRET: 'vault.bundles.removeSecret',
+
+  // Vault - Files
+  VAULT_FILES_WRITE_TEXT: 'vault.files.writeText',
+  VAULT_FILES_WRITE_BYTES: 'vault.files.writeBytes',
+  VAULT_FILES_READ_TEXT: 'vault.files.readText',
+  VAULT_FILES_READ_BYTES: 'vault.files.readBytes',
+  VAULT_FILES_LIST: 'vault.files.list',
+  VAULT_FILES_EXISTS: 'vault.files.exists',
+  VAULT_FILES_DELETE: 'vault.files.delete',
+  VAULT_FILES_MKDIR: 'vault.files.mkdir',
+  VAULT_FILES_MOVE: 'vault.files.move',
+
+  // Vault - Injection (DEFERRED - returns NOT_IMPLEMENTED)
+  VAULT_ATTACH_SECRETS_TO_CONNECTOR: 'vault.attachSecretsToConnector',
+  VAULT_INJECT_SECRETS_INTO_RUN: 'vault.injectSecretsIntoRun',
+
+  // Vault - Audit
+  VAULT_AUDIT_LIST: 'vault.audit.list',
+} as const;
+
+export type OpName = (typeof OPS)[keyof typeof OPS];
+
+// =============================================================================
+// ERROR CODES
+// =============================================================================
+
+export const ERROR_CODES = {
+  NOT_CONNECTED: 'NOT_CONNECTED',
+  NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+  HOME_GRANT_REQUIRED: 'HOME_GRANT_REQUIRED',
+  INVALID_OP: 'INVALID_OP',
+  INVALID_PAYLOAD: 'INVALID_PAYLOAD',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+
+  // Vault
+  VAULT_NOT_INITIALIZED: 'VAULT_NOT_INITIALIZED',
+  VAULT_ERROR: 'VAULT_ERROR',
+  SECRET_NOT_FOUND: 'SECRET_NOT_FOUND',
+  SECRET_ALREADY_EXISTS: 'SECRET_ALREADY_EXISTS',
+  BUNDLE_NOT_FOUND: 'BUNDLE_NOT_FOUND',
+  BUNDLE_ALREADY_EXISTS: 'BUNDLE_ALREADY_EXISTS',
+
+  // Files
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FILE_ALREADY_EXISTS: 'FILE_ALREADY_EXISTS',
+  DIRECTORY_NOT_EMPTY: 'DIRECTORY_NOT_EMPTY',
+  INVALID_PATH: 'INVALID_PATH',
+  PATH_TRAVERSAL_DENIED: 'PATH_TRAVERSAL_DENIED',
+
+  // Deferred
+  NOT_IMPLEMENTED: 'NOT_IMPLEMENTED',
+
+  // Credentials
+  INVALID_NODE_ID: 'INVALID_NODE_ID',
+  INVALID_NODE_SECRET: 'INVALID_NODE_SECRET',
+  CREDENTIALS_STORE_ERROR: 'CREDENTIALS_STORE_ERROR',
+  CREDENTIALS_CLEAR_ERROR: 'CREDENTIALS_CLEAR_ERROR',
+  CREDENTIALS_NOT_CONFIGURED: 'CREDENTIALS_NOT_CONFIGURED',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+// =============================================================================
+// CONTRACT VERSION
+// =============================================================================
+
+export const CONTRACT_VERSION = 2;

package/template/src/ekka/errors.ts

@@ -0,0 +1,54 @@
+/**
+ * EKKA Error Classes
+ *
+ * Custom error types for the EKKA client library.
+ */
+
+import { ERROR_CODES } from './constants';
+
+/**
+ * Base error class for all EKKA errors.
+ */
+export class EkkaError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = 'EkkaError';
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when an operation is attempted without a connection.
+ */
+export class EkkaNotConnectedError extends EkkaError {
+  constructor() {
+    super('Not connected. Call ekka.connect() first.', ERROR_CODES.NOT_CONNECTED);
+    this.name = 'EkkaNotConnectedError';
+  }
+}
+
+/**
+ * Thrown when connection fails.
+ */
+export class EkkaConnectionError extends EkkaError {
+  constructor(message: string) {
+    super(message, 'CONNECTION_ERROR');
+    this.name = 'EkkaConnectionError';
+  }
+}
+
+/**
+ * Thrown when an API operation fails.
+ */
+export class EkkaApiError extends EkkaError {
+  readonly httpStatus?: number;
+
+  constructor(message: string, code: string, httpStatus?: number) {
+    super(message, code);
+    this.name = 'EkkaApiError';
+    this.httpStatus = httpStatus;
+  }
+}