@makaio/framework 1.0.0-dev-1779046984397

package/dist/index-ESSDWIB7.d.mts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+//#region packages/services/core/src/settings/storage/shared-schemas.d.ts
+/**
+ * Shared CRUD request shape for storage namespaces that address rows by ID.
+ */
+declare const StorageIdRequestSchema: z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+export { StorageIdRequestSchema as t };

package/dist/index-N5K1NOYs.d.mts

@@ -0,0 +1,184 @@
+import { RequestMessagePayload, SubjectDefinition } from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { SQLiteColumn, SQLiteTable } from "drizzle-orm/sqlite-core";
+import { Column, SQL } from "drizzle-orm";
+import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
+
+//#region packages/storage/handlers/src/drizzle/types.d.ts
+type RequestSubjectDefinition<Req extends Record<string, unknown>, Res extends Record<string, unknown>> = SubjectDefinition & {
+  $meta: {
+    payload: RequestMessagePayload<Req, Res>;
+  };
+};
+type EventSubjectDefinition<Payload> = SubjectDefinition & {
+  $meta: {
+    payload: Payload;
+  };
+};
+type TableRow<TTable extends SQLiteTable> = TTable['$inferSelect'];
+type TableInsert<TTable extends SQLiteTable> = TTable['$inferInsert'];
+type ColumnKey<TTable extends SQLiteTable> = Extract<keyof TTable['_']['columns'], string>;
+type TimestampedRow = {
+  createdAt: number;
+  updatedAt: number;
+};
+type TimestampedTable<TTable extends SQLiteTable> = TableRow<TTable> extends TimestampedRow ? TTable : never;
+/**
+ * Lifecycle event subjects for CRUD operations.
+ * @typeParam TEntity - API entity type emitted for create/update events
+ */
+interface CrudLifecycleConfig<TEntity> {
+  /** Emitted when a new entity is inserted */
+  created: EventSubjectDefinition<TEntity>;
+  /** Emitted when an existing entity is updated */
+  updated: EventSubjectDefinition<TEntity>;
+  /** Emitted when an entity is deleted */
+  deleted: EventSubjectDefinition<{
+    id: string;
+  }>;
+}
+/**
+ * Configuration for creating standard CRUD handlers.
+ *
+ * Type safety is enforced at the call site and validated at runtime through Zod schemas.
+ * @typeParam TTable - Drizzle SQLite table type (unconstrained for flexibility)
+ * @typeParam ApiType - API response entity type
+ * @typeParam InputType - API input entity type (defaults to ApiType)
+ * @typeParam DbRow - Database row type (explicitly specified for type safety)
+ */
+interface DrizzleCrudConfig<TTable extends SQLiteTable, ApiType, TIdField extends ColumnKey<TTable> = ColumnKey<TTable>, InputType extends Record<TIdField, string> & Record<string, unknown> = (ApiType extends Record<TIdField, string> ? ApiType : Record<TIdField, string> & Record<string, unknown>), TSingularKey extends string = string> {
+  /** Drizzle table definition */
+  table: TimestampedTable<TTable>;
+  /** Storage subjects object with get, set, delete properties */
+  subjects: {
+    /** Subject for getting a single entity by ID */get: RequestSubjectDefinition<{
+      id: string;
+    }, Record<TSingularKey, ApiType | null>>; /** Subject for creating or updating an entity */
+    set: RequestSubjectDefinition<Record<TSingularKey, InputType>, {
+      id: string;
+    }>; /** Subject for deleting an entity by ID */
+    delete: RequestSubjectDefinition<{
+      id: string;
+    }, {
+      deleted: boolean;
+    }>;
+  };
+  /** Primary key field name on the table */
+  idField: TIdField;
+  /** Response key for single entity (e.g., 'profile') */
+  singularKey: TSingularKey;
+  /** Maps database row to API type */
+  mapper: (row: TableRow<TTable>) => ApiType;
+  /** Maps API input to database values for insert/update */
+  toDbValues: (input: InputType) => Partial<TableInsert<TTable>>;
+  /**
+   * Optional conflict target columns for upsert identity.
+   *
+   * Defaults to the primary key column ({@link idField}). Override this when
+   * the table has a natural-key unique index that should govern upsert identity
+   * instead of the synthetic PK. The callback receives the table so callers can
+   * reference column objects directly.
+   *
+   * **PK mutation:** When a conflict fires on the natural key and the incoming
+   * `id` differs from the stored PK, the handler updates the PK column to the
+   * incoming `id` (and returns it). Callers that enable this option must
+   * tolerate non-stable primary keys across upserts.
+   * @example
+   * ```ts
+   * // extension_configs has uniqueIndex('uniq_extension_configs_name_scope')
+   * conflictTarget: (t) => [t.extensionName, t.scope],
+   * ```
+   */
+  conflictTarget?: (table: TTable) => (SQLiteColumn | SQL)[];
+  /**
+   * Optional lifecycle event configuration.
+   *
+   * When provided, the factory emits created/updated/deleted events after
+   * successful mutations via wrapper handlers.
+   */
+  lifecycle?: CrudLifecycleConfig<ApiType>;
+}
+/**
+ * Configuration for creating a list handler.
+ *
+ * Type safety is enforced at the call site and validated at runtime through Zod schemas.
+ * @typeParam TTable - Drizzle SQLite table type (unconstrained for flexibility)
+ * @typeParam ApiType - API response entity type
+ * @typeParam QueryPayload - Query payload type
+ * @typeParam DbRow - Database row type (explicitly specified for type safety)
+ */
+interface DrizzleListConfig<TTable extends SQLiteTable, ApiType, QueryPayload extends Record<string, unknown> = Record<string, unknown>, TPluralKey extends string = string, TSubject extends RequestSubjectDefinition<QueryPayload, Record<TPluralKey, ApiType[]>> = RequestSubjectDefinition<QueryPayload, Record<TPluralKey, ApiType[]>>> {
+  /** Drizzle table definition */
+  table: TTable;
+  /** List subject from storage namespace */
+  subject: TSubject;
+  /** Response key for entity array (e.g., 'profiles') */
+  pluralKey: TPluralKey;
+  /** Maps database row to API type */
+  mapper: (row: TableRow<TTable>) => ApiType;
+  /** Builds query predicates from payload */
+  buildPredicates: (payload: QueryPayload, table: TTable) => SQL[];
+}
+//#endregion
+//#region packages/storage/handlers/src/drizzle/crud-handlers.d.ts
+/**
+ * Creates standard get, set, delete handlers for a Drizzle table.
+ * @param config - CRUD handler configuration.
+ * @returns Function that registers handlers and returns cleanup.
+ */
+declare function createDrizzleCrudHandlers<TTable extends SQLiteTable, ApiType extends Record<string, unknown>, TIdField extends Extract<keyof TTable['_']['columns'], string> = Extract<keyof TTable['_']['columns'], string>, InputType extends Record<TIdField, string> & Record<string, unknown> = (ApiType extends Record<TIdField, string> ? ApiType : Record<TIdField, string> & Record<string, unknown>), TSingularKey extends string = string>(config: DrizzleCrudConfig<TTable, ApiType, TIdField, InputType, TSingularKey>): (bus: IMakaioBus, db: MakaioDatabase) => () => void;
+//#endregion
+//#region packages/storage/handlers/src/drizzle/list-handler.d.ts
+/**
+ * Creates a list handler with customizable query predicates.
+ *
+ * Type safety is maintained at the call site through DrizzleListConfig type
+ * parameters and runtime Zod schema validation.
+ * @param config - List handler configuration
+ * @returns Function that registers the handler and returns cleanup
+ * @example
+ * ```typescript
+ * const registerList = createDrizzleListHandler({
+ *   table: profileDefinitions,
+ *   subject: ProfileStorageSubjects.list,
+ *   pluralKey: 'profiles',
+ *   mapper: mapProfile,
+ *   buildPredicates: (payload, table) => [
+ *     ...buildScopePredicates(table, payload.projectId),
+ *     ...(payload.name ? [eq(table.name, payload.name)] : []),
+ *   ],
+ * });
+ *
+ * const cleanup = registerList(bus, db);
+ * ```
+ */
+declare function createDrizzleListHandler<TTable extends SQLiteTable, ApiType, QueryPayload extends Record<string, unknown> = Record<string, unknown>, TPluralKey extends string = string>(config: DrizzleListConfig<TTable, ApiType, QueryPayload, TPluralKey>): (bus: IMakaioBus, db: MakaioDatabase) => () => void;
+//#endregion
+//#region packages/storage/handlers/src/drizzle/scope-predicates.d.ts
+/**
+ * Table with a scope column for two-tier scoping.
+ */
+interface ScopeTable {
+  /** Scope column for filtering (default or projectId) */
+  scope: Column;
+}
+/**
+ * Builds standard scope predicates for two-tier scoping (default | projectId).
+ *
+ * When projectId is provided: returns both default and project-scoped entities.
+ * When projectId is undefined: returns only default-scoped entities.
+ * @param table - Table with 'scope' column
+ * @param projectId - Optional project ID for scoping
+ * @returns Array of SQL predicates
+ * @example
+ * ```typescript
+ * const predicates = buildScopePredicates(profileDefinitions, 'proj-123');
+ * // Returns: [inArray(profileDefinitions.scope, ['default', 'proj-123'])]
+ *
+ * const predicates = buildScopePredicates(profileDefinitions, undefined);
+ * // Returns: [eq(profileDefinitions.scope, 'default')]
+ * ```
+ */
+declare function buildScopePredicates<T extends ScopeTable>(table: T, projectId: string | undefined): SQL[];
+//#endregion
+export { DrizzleCrudConfig as a, CrudLifecycleConfig as i, createDrizzleListHandler as n, DrizzleListConfig as o, createDrizzleCrudHandlers as r, buildScopePredicates as t };

package/dist/index-PdUSmPT2.d.mts

@@ -0,0 +1,180 @@
+//#region packages/contracts/src/common/focus-context.d.ts
+/**
+ * Shared focus context type for navigation results.
+ *
+ * This type is used across multiple packages to define focus contexts
+ * for the web/app surface. It's centralized here to avoid duplication.
+ * @packageDocumentation
+ */
+/**
+ * Focus context types for navigation results.
+ *
+ * Represents the different focus areas available in the web/app interface.
+ * Used by slash commands, navigation results, and the focus store.
+ *
+ * The focus store implementation is in `@makaio/ui-hooks`.
+ */
+type FocusContext = 'chat' | 'git' | 'review' | 'planning' | 'settings';
+//#endregion
+//#region packages/contracts/src/common/action-intent.d.ts
+/**
+ * Describes a UI side effect that an action handler intends to produce.
+ *
+ * Action handlers return an `ActionIntent` rather than executing effects directly.
+ * The framework's intent executor interprets and dispatches each kind.
+ *
+ * SEAM: New intent kinds are added here. UI executors add the corresponding
+ * cases without leaking renderer dependencies into service packages.
+ * @example
+ * ```typescript
+ * const intent: ActionIntent = { kind: 'clipboard', text: commit.hash };
+ * const compound: ActionIntent = {
+ *   kind: 'compound',
+ *   intents: [
+ *     { kind: 'clipboard', text: commit.hash },
+ *     { kind: 'feedback', message: 'Hash copied', variant: 'success' },
+ *   ],
+ * };
+ * ```
+ */
+type ActionIntent = {
+  readonly kind: 'noop';
+} | {
+  readonly kind: 'clipboard';
+  readonly text: string;
+  readonly feedback?: string;
+} | {
+  readonly kind: 'navigate';
+  readonly target: FocusContext;
+} | {
+  readonly kind: 'openEditor';
+  readonly filePath: string;
+  readonly line?: number;
+  readonly column?: number;
+} | {
+  readonly kind: 'openPage';
+  readonly pageId: string;
+  readonly internalRoute?: string;
+} | {
+  readonly kind: 'busRequest';
+  readonly subject: string;
+  readonly payload?: Record<string, unknown>;
+} | {
+  readonly kind: 'feedback';
+  readonly message: string;
+  readonly variant?: 'info' | 'success' | 'warning' | 'error';
+} | {
+  readonly kind: 'confirm';
+  readonly title: string;
+  readonly message: string;
+  readonly onConfirmIntent: ActionIntent;
+} | {
+  readonly kind: 'compound';
+  readonly intents: readonly ActionIntent[];
+}
+/**
+ * Open a diff view for a file.
+ *
+ * - `commitId` is `null` for working-tree diffs (right side is read from disk).
+ * - `status` is the git file status character (A/M/D/R/…) for commit contexts.
+ * - `parentCount` drives empty-tree handling for root commits.
+ * - `originalPath` carries the rename origin when the file was renamed.
+ * - `variant` is the working-tree section ('staged' | 'unstaged' | 'untracked' | 'conflicted').
+ */
+| {
+  readonly kind: 'viewDiff';
+  readonly filePath: string;
+  readonly commitId: string | null;
+  readonly status?: string;
+  readonly parentCount?: number;
+  readonly originalPath?: string;
+  readonly variant?: string;
+}
+/**
+ * Show file content at a specific commit in the inline file viewer panel.
+ * Only valid for commit-context files.
+ */
+| {
+  readonly kind: 'viewAtCommit';
+  readonly filePath: string;
+  readonly commitId: string;
+}
+/**
+ * Show blame annotations for a file at a specific commit in the inline blame panel.
+ * Only valid for commit-context files.
+ */
+| {
+  readonly kind: 'viewBlame';
+  readonly filePath: string;
+  readonly commitId: string;
+}
+/**
+ * Compare a file across revisions using the diff viewer.
+ *
+ * Equivalent to `viewDiff` but with `useEmptyTreeForRoot = true` — root commits
+ * are shown as full-add diffs against the empty tree. For working-tree contexts,
+ * untracked files are silently skipped.
+ *
+ * - `commitId` is `null` for working-tree compare.
+ * - `status`, `parentCount`, `originalPath`, `variant` carry the same semantics as `viewDiff`.
+ */
+| {
+  readonly kind: 'compareVersions';
+  readonly filePath: string;
+  readonly commitId: string | null;
+  readonly status?: string;
+  readonly parentCount?: number;
+  readonly originalPath?: string;
+  readonly variant?: string;
+};
+//#endregion
+//#region packages/contracts/src/common/surface.d.ts
+/**
+ * Surface type definitions shared across all packages.
+ *
+ * These are the canonical surface types used throughout the system.
+ * Both the contracts-level page metadata and the framework-level
+ * page definitions reference these types.
+ * @packageDocumentation
+ */
+/**
+ * Rendering surface identifiers.
+ *
+ * Each surface represents a distinct runtime environment:
+ * - 'web': Browser-based React DOM rendering
+ * - 'mobile': React Native rendering (iOS/Android)
+ * - 'electron': Desktop Electron rendering (superset of web)
+ * - 'electrobun': Desktop Electrobun rendering (Bun-native alternative to Electron)
+ * - 'tray': Lightweight tray popover canvas (subset of desktop)
+ *
+ * SEAM: New surfaces can be added here as the platform expands.
+ */
+type SurfaceType = 'web' | 'mobile' | 'electron' | 'electrobun' | 'tray';
+/**
+ * Page surface visibility configuration.
+ *
+ * Controls which rendering surfaces a page appears on:
+ * - `'all'`: Available on every surface (default when omitted)
+ * - `SurfaceType[]`: Restricted to listed surfaces only
+ * @example
+ * ```typescript
+ * // Available everywhere
+ * surfaces: 'all'
+ *
+ * // Web and electron only
+ * surfaces: ['web', 'electron']
+ *
+ * // Mobile only
+ * surfaces: ['mobile']
+ * ```
+ */
+type SurfaceVisibility = 'all' | SurfaceType[];
+/**
+ * Check if a page is visible on a given surface.
+ * @param visibility - Page surface visibility configuration
+ * @param surface - Surface to check against
+ * @returns True if the page should be visible on the surface
+ */
+declare function isSurfaceVisible(visibility: SurfaceVisibility | undefined, surface: SurfaceType): boolean;
+//#endregion
+export { FocusContext as a, ActionIntent as i, SurfaceVisibility as n, isSurfaceVisible as r, SurfaceType as t };

package/dist/index-SzSiyG61.d.mts

@@ -0,0 +1,117 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+
+//#region packages/kernel/src/providers/storage.d.ts
+/**
+ * Cleanup handle returned by storage registration.
+ */
+interface StorageCleanup {
+  /** Unregister all storage handlers from the bus. */
+  cleanup: () => void;
+  /** Database handle, if this provider uses a database (e.g., Drizzle). */
+  db?: unknown;
+}
+/**
+ * Platform-specific storage backend.
+ * Registers bus handlers that respond to storage namespace subjects.
+ */
+interface StorageProvider {
+  /**
+   * Register storage handlers on the bus.
+   * Called before app.start() in the composition root.
+   * @param bus - Bus instance to register handlers on
+   * @param machineId - Machine identifier for storage scoping
+   */
+  registerHandlers(bus: IMakaioBus, machineId: string): Promise<StorageCleanup>;
+  /** Release storage resources (close DB connections, etc.). */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/providers/transport.d.ts
+/**
+ * Platform-specific bus transport (WebSocket server, client, none).
+ */
+interface TransportProvider {
+  /**
+   * Attach transport to the bus.
+   *
+   * For server transports, the HTTP server and Hono app are passed via
+   * constructor options — the provider only wires the WebSocket upgrade
+   * handler onto them.
+   * @param bus - Bus instance to attach transport to.
+   * @param machineId - Machine identifier for transport identification.
+   */
+  connect(bus: IMakaioBus, machineId: string): Promise<void>;
+  /** Disconnect and release transport resources. */
+  disconnect(): Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/providers/identity.d.ts
+/**
+ * Machine identity resolved by the platform.
+ */
+interface MachineIdentity {
+  /** Unique machine identifier. */
+  readonly machineId: string;
+}
+/**
+ * Platform-specific machine identity resolution.
+ * Node: persisted in ~/.makaio/keys/
+ * Container/Framework: ephemeral crypto.randomUUID()
+ */
+interface IdentityProvider {
+  /** Load or generate the machine identity. */
+  load(): Promise<MachineIdentity>;
+}
+//#endregion
+//#region packages/kernel/src/providers/memory-storage.d.ts
+/**
+ * No-op storage provider.
+ *
+ * Satisfies the {@link StorageProvider} interface when no platform-specific storage
+ * (e.g., Drizzle) is needed.
+ */
+declare class MemoryStorageProvider implements StorageProvider {
+  /**
+   * Returns a no-op cleanup handle.
+   *
+   * In-memory bus handler registration is performed by individual service
+   * storage factories before service construction.
+   * @param _bus - Unused bus instance
+   * @param _machineId - Unused machine identifier
+   * @returns A no-op cleanup handle
+   */
+  registerHandlers(_bus: IMakaioBus, _machineId: string): Promise<StorageCleanup>;
+  /** Nothing to dispose for in-memory storage. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/providers/no-transport.d.ts
+/**
+ * No-op transport provider for in-process-only bus usage.
+ * Used by framework users who don't need cross-process communication.
+ */
+declare class NoTransportProvider implements TransportProvider {
+  /**
+   * No-op — no transport to connect.
+   * @param _bus - Unused bus instance.
+   * @param _machineId - Unused machine identifier.
+   */
+  connect(_bus: IMakaioBus, _machineId: string): Promise<void>;
+  /** Nothing to disconnect. */
+  disconnect(): Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/providers/ephemeral-identity.d.ts
+/**
+ * Ephemeral identity provider — generates a new random UUID on each load.
+ * Used by framework users and containers that don't persist machine identity.
+ */
+declare class EphemeralIdentityProvider implements IdentityProvider {
+  /**
+   * Generate a fresh random UUID as the machine identity.
+   * @returns A new ephemeral machine identity
+   */
+  load(): Promise<MachineIdentity>;
+}
+//#endregion
+export { MachineIdentity as a, StorageProvider as c, IdentityProvider as i, NoTransportProvider as n, TransportProvider as o, MemoryStorageProvider as r, StorageCleanup as s, EphemeralIdentityProvider as t };