@allternit/gizzi-code 1.0.0

package/src/bootstrap/state.js

@@ -0,0 +1,261 @@
+/**
+ * @fileoverview Bootstrap state management for gizzi-code integration
+ * @module bootstrap/state
+ *
+ * Manages application initialization state, loading phases, and bootstrap
+ * lifecycle events. Provides centralized state tracking during application startup.
+ */
+/**
+ * Valid loading phase transitions
+ * @constant {Record<LoadingPhase, readonly LoadingPhase[]>}
+ */
+export const VALID_PHASE_TRANSITIONS = {
+    idle: ['initializing'],
+    initializing: ['loading_config', 'error'],
+    loading_config: ['connecting', 'error'],
+    connecting: ['authenticating', 'error'],
+    authenticating: ['ready', 'error'],
+    ready: ['idle', 'initializing'],
+    error: ['idle', 'initializing'],
+};
+/**
+ * Initial bootstrap state
+ * @constant {BootstrapState}
+ */
+const INITIAL_STATE = {
+    phase: 'idle',
+    progress: 0,
+    isComplete: false,
+    hasError: false,
+    error: null,
+    startTime: null,
+    endTime: null,
+    messages: [],
+    config: {},
+    services: [],
+};
+// Module-level state (singleton pattern)
+let currentState = { ...INITIAL_STATE };
+const listeners = new Set();
+/**
+ * Gets the current bootstrap state
+ * @returns {Readonly<BootstrapState>} The current bootstrap state (immutable)
+ * @example
+ * ```typescript
+ * const state = getBootstrapState();
+ * if (state.phase === 'ready') {
+ *   console.log('Application is ready');
+ * }
+ * ```
+ */
+export function getBootstrapState() {
+    return Object.freeze({ ...currentState });
+}
+/**
+ * Sets the bootstrap state with partial updates
+ * Automatically notifies all registered listeners
+ *
+ * @param {Partial<BootstrapState>} updates - Partial state updates to apply
+ * @returns {Readonly<BootstrapState>} The updated state
+ * @throws {Error} If attempting an invalid phase transition
+ * @example
+ * ```typescript
+ * setBootstrapState({ phase: 'initializing', progress: 10 });
+ * ```
+ */
+export function setBootstrapState(updates) {
+    // Validate phase transition if phase is being updated
+    if (updates.phase && updates.phase !== currentState.phase) {
+        if (!isValidPhaseTransition(currentState.phase, updates.phase)) {
+            throw new Error(`Invalid phase transition from '${currentState.phase}' to '${updates.phase}'. ` +
+                `Valid transitions: ${VALID_PHASE_TRANSITIONS[currentState.phase].join(', ')}`);
+        }
+    }
+    // Create new state with updates
+    const previousState = currentState;
+    currentState = {
+        ...currentState,
+        ...updates,
+        // Merge nested objects carefully
+        config: updates.config ? { ...currentState.config, ...updates.config } : currentState.config,
+        messages: updates.messages ?? currentState.messages,
+        services: updates.services ?? currentState.services,
+    };
+    // Update computed fields
+    currentState = {
+        ...currentState,
+        isComplete: currentState.phase === 'ready',
+        hasError: currentState.phase === 'error' || currentState.error !== null,
+    };
+    // Notify listeners (async to avoid blocking)
+    queueMicrotask(() => {
+        listeners.forEach((listener) => {
+            try {
+                listener(currentState);
+            }
+            catch (error) {
+                console.error('Bootstrap state listener error:', error);
+            }
+        });
+    });
+    // Log state change in development
+    if (process.env.NODE_ENV === 'development') {
+        console.debug('[BootstrapState]', previousState.phase, '->', currentState.phase);
+    }
+    return Object.freeze({ ...currentState });
+}
+/**
+ * Subscribes to bootstrap state changes
+ *
+ * @param {StateChangeListener} listener - Callback function to invoke on state changes
+ * @returns {() => void} Unsubscribe function
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeToBootstrapState((state) => {
+ *   console.log('Phase:', state.phase);
+ * });
+ * // Later: unsubscribe();
+ * ```
+ */
+export function subscribeToBootstrapState(listener) {
+    listeners.add(listener);
+    // Immediately notify with current state
+    listener(currentState);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/**
+ * Resets the bootstrap state to initial values
+ * Useful for testing or re-initializing the application
+ *
+ * @param {boolean} [notifyListeners=true] - Whether to notify listeners of the reset
+ * @returns {Readonly<BootstrapState>} The reset state
+ */
+export function resetBootstrapState(notifyListeners = true) {
+    currentState = { ...INITIAL_STATE };
+    if (notifyListeners) {
+        queueMicrotask(() => {
+            listeners.forEach((listener) => {
+                try {
+                    listener(currentState);
+                }
+                catch (error) {
+                    console.error('Bootstrap state listener error:', error);
+                }
+            });
+        });
+    }
+    return Object.freeze({ ...currentState });
+}
+/**
+ * Starts the bootstrap process
+ * Sets phase to 'initializing' and records start time
+ *
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function startBootstrap() {
+    return setBootstrapState({
+        phase: 'initializing',
+        startTime: new Date(),
+        progress: 5,
+    });
+}
+/**
+ * Reports a bootstrap error
+ * Sets phase to 'error' and records error details
+ *
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {string} [details] - Optional error details
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function setBootstrapError(code, message, details) {
+    const error = {
+        code,
+        message,
+        timestamp: new Date(),
+        details,
+        phase: currentState.phase,
+    };
+    return setBootstrapState({
+        phase: 'error',
+        error,
+        endTime: new Date(),
+    });
+}
+/**
+ * Completes the bootstrap process
+ * Sets phase to 'ready' and records completion time
+ *
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function completeBootstrap() {
+    return setBootstrapState({
+        phase: 'ready',
+        progress: 100,
+        endTime: new Date(),
+    });
+}
+/**
+ * Validates if a phase transition is allowed
+ *
+ * @param {LoadingPhase} from - Current phase
+ * @param {LoadingPhase} to - Target phase
+ * @returns {boolean} Whether the transition is valid
+ */
+function isValidPhaseTransition(from, to) {
+    return VALID_PHASE_TRANSITIONS[from].includes(to);
+}
+/**
+ * Gets the estimated time remaining for bootstrap
+ *
+ * @returns {number | null} Estimated milliseconds remaining, or null if not available
+ */
+export function getEstimatedTimeRemaining() {
+    if (!currentState.startTime || currentState.progress === 0) {
+        return null;
+    }
+    const elapsed = Date.now() - currentState.startTime.getTime();
+    const progressRemaining = 100 - currentState.progress;
+    const estimatedTotal = (elapsed / currentState.progress) * 100;
+    return Math.max(0, (estimatedTotal * progressRemaining) / 100);
+}
+/**
+ * Adds a message to the bootstrap state
+ *
+ * @param {TypedMessage} message - The message to add
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function addBootstrapMessage(message) {
+    return setBootstrapState({
+        messages: [...currentState.messages, message],
+    });
+}
+/**
+ * Registers a service as initialized
+ *
+ * @param {string} serviceName - Name of the service
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function registerService(serviceName) {
+    if (currentState.services.includes(serviceName)) {
+        return getBootstrapState();
+    }
+    return setBootstrapState({
+        services: [...currentState.services, serviceName],
+    });
+}
+// Default export
+export default {
+    getBootstrapState,
+    setBootstrapState,
+    subscribeToBootstrapState,
+    resetBootstrapState,
+    startBootstrap,
+    completeBootstrap,
+    setBootstrapError,
+    addBootstrapMessage,
+    registerService,
+    getEstimatedTimeRemaining,
+};

package/src/bootstrap/state.ts

@@ -0,0 +1,371 @@
+/**
+ * @fileoverview Bootstrap state management for gizzi-code integration
+ * @module bootstrap/state
+ *
+ * Manages application initialization state, loading phases, and bootstrap
+ * lifecycle events. Provides centralized state tracking during application startup.
+ */
+
+import type { TypedMessage } from '../types/message';
+
+/**
+ * Loading phase identifiers for the bootstrap process
+ * @typedef {'idle' | 'initializing' | 'loading_config' | 'connecting' | 'authenticating' | 'ready' | 'error'} LoadingPhase
+ */
+export type LoadingPhase =
+  | 'idle'
+  | 'initializing'
+  | 'loading_config'
+  | 'connecting'
+  | 'authenticating'
+  | 'ready'
+  | 'error';
+
+/**
+ * Valid loading phase transitions
+ * @constant {Record<LoadingPhase, readonly LoadingPhase[]>}
+ */
+export const VALID_PHASE_TRANSITIONS: Readonly<Record<LoadingPhase, readonly LoadingPhase[]>> = {
+  idle: ['initializing'],
+  initializing: ['loading_config', 'error'],
+  loading_config: ['connecting', 'error'],
+  connecting: ['authenticating', 'error'],
+  authenticating: ['ready', 'error'],
+  ready: ['idle', 'initializing'],
+  error: ['idle', 'initializing'],
+} as const;
+
+/**
+ * Bootstrap error structure
+ * @interface BootstrapError
+ */
+export interface BootstrapError {
+  /** Error code for programmatic handling */
+  readonly code: string;
+
+  /** Human-readable error message */
+  readonly message: string;
+
+  /** Error timestamp */
+  readonly timestamp: Date;
+
+  /** Optional error details or stack trace */
+  readonly details?: string;
+
+  /** Phase where the error occurred */
+  readonly phase: LoadingPhase;
+}
+
+/**
+ * Bootstrap state interface tracking initialization progress
+ * @interface BootstrapState
+ */
+export interface BootstrapState {
+  /** Current loading phase */
+  readonly phase: LoadingPhase;
+
+  /** Overall progress percentage (0-100) */
+  readonly progress: number;
+
+  /** Whether the application has completed bootstrap */
+  readonly isComplete: boolean;
+
+  /** Whether an error has occurred during bootstrap */
+  readonly hasError: boolean;
+
+  /** Current error if any */
+  readonly error: BootstrapError | null;
+
+  /** Timestamp when bootstrap started */
+  readonly startTime: Date | null;
+
+  /** Timestamp when bootstrap completed */
+  readonly endTime: Date | null;
+
+  /** Messages collected during initialization */
+  readonly messages: readonly TypedMessage[];
+
+  /** Configuration data loaded during bootstrap */
+  readonly config: Readonly<Record<string, unknown>>;
+
+  /** Services initialized during bootstrap */
+  readonly services: readonly string[];
+}
+
+/**
+ * Initial bootstrap state
+ * @constant {BootstrapState}
+ */
+const INITIAL_STATE: BootstrapState = {
+  phase: 'idle',
+  progress: 0,
+  isComplete: false,
+  hasError: false,
+  error: null,
+  startTime: null,
+  endTime: null,
+  messages: [],
+  config: {},
+  services: [],
+} as const;
+
+/**
+ * Listener callback type for state changes
+ * @typedef {(state: BootstrapState) => void} StateChangeListener
+ */
+type StateChangeListener = (state: BootstrapState) => void;
+
+// Module-level state (singleton pattern)
+let currentState: BootstrapState = { ...INITIAL_STATE };
+const listeners: Set<StateChangeListener> = new Set();
+
+/**
+ * Gets the current bootstrap state
+ * @returns {Readonly<BootstrapState>} The current bootstrap state (immutable)
+ * @example
+ * ```typescript
+ * const state = getBootstrapState();
+ * if (state.phase === 'ready') {
+ *   console.log('Application is ready');
+ * }
+ * ```
+ */
+export function getBootstrapState(): Readonly<BootstrapState> {
+  return Object.freeze({ ...currentState });
+}
+
+/**
+ * Sets the bootstrap state with partial updates
+ * Automatically notifies all registered listeners
+ *
+ * @param {Partial<BootstrapState>} updates - Partial state updates to apply
+ * @returns {Readonly<BootstrapState>} The updated state
+ * @throws {Error} If attempting an invalid phase transition
+ * @example
+ * ```typescript
+ * setBootstrapState({ phase: 'initializing', progress: 10 });
+ * ```
+ */
+export function setBootstrapState(updates: Partial<BootstrapState>): Readonly<BootstrapState> {
+  // Validate phase transition if phase is being updated
+  if (updates.phase && updates.phase !== currentState.phase) {
+    if (!isValidPhaseTransition(currentState.phase, updates.phase)) {
+      throw new Error(
+        `Invalid phase transition from '${currentState.phase}' to '${updates.phase}'. ` +
+          `Valid transitions: ${VALID_PHASE_TRANSITIONS[currentState.phase].join(', ')}`
+      );
+    }
+  }
+
+  // Create new state with updates
+  const previousState = currentState;
+  currentState = {
+    ...currentState,
+    ...updates,
+    // Merge nested objects carefully
+    config: updates.config ? { ...currentState.config, ...updates.config } : currentState.config,
+    messages: updates.messages ?? currentState.messages,
+    services: updates.services ?? currentState.services,
+  };
+
+  // Update computed fields
+  currentState = {
+    ...currentState,
+    isComplete: currentState.phase === 'ready',
+    hasError: currentState.phase === 'error' || currentState.error !== null,
+  };
+
+  // Notify listeners (async to avoid blocking)
+  queueMicrotask(() => {
+    listeners.forEach((listener) => {
+      try {
+        listener(currentState);
+      } catch (error) {
+        console.error('Bootstrap state listener error:', error);
+      }
+    });
+  });
+
+  // Log state change in development
+  if (process.env.NODE_ENV === 'development') {
+    console.debug('[BootstrapState]', previousState.phase, '->', currentState.phase);
+  }
+
+  return Object.freeze({ ...currentState });
+}
+
+/**
+ * Subscribes to bootstrap state changes
+ *
+ * @param {StateChangeListener} listener - Callback function to invoke on state changes
+ * @returns {() => void} Unsubscribe function
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeToBootstrapState((state) => {
+ *   console.log('Phase:', state.phase);
+ * });
+ * // Later: unsubscribe();
+ * ```
+ */
+export function subscribeToBootstrapState(listener: StateChangeListener): () => void {
+  listeners.add(listener);
+
+  // Immediately notify with current state
+  listener(currentState);
+
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Resets the bootstrap state to initial values
+ * Useful for testing or re-initializing the application
+ *
+ * @param {boolean} [notifyListeners=true] - Whether to notify listeners of the reset
+ * @returns {Readonly<BootstrapState>} The reset state
+ */
+export function resetBootstrapState(notifyListeners = true): Readonly<BootstrapState> {
+  currentState = { ...INITIAL_STATE };
+
+  if (notifyListeners) {
+    queueMicrotask(() => {
+      listeners.forEach((listener) => {
+        try {
+          listener(currentState);
+        } catch (error) {
+          console.error('Bootstrap state listener error:', error);
+        }
+      });
+    });
+  }
+
+  return Object.freeze({ ...currentState });
+}
+
+/**
+ * Starts the bootstrap process
+ * Sets phase to 'initializing' and records start time
+ *
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function startBootstrap(): Readonly<BootstrapState> {
+  return setBootstrapState({
+    phase: 'initializing',
+    startTime: new Date(),
+    progress: 5,
+  });
+}
+
+/**
+ * Reports a bootstrap error
+ * Sets phase to 'error' and records error details
+ *
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {string} [details] - Optional error details
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function setBootstrapError(
+  code: string,
+  message: string,
+  details?: string
+): Readonly<BootstrapState> {
+  const error: BootstrapError = {
+    code,
+    message,
+    timestamp: new Date(),
+    details,
+    phase: currentState.phase,
+  };
+
+  return setBootstrapState({
+    phase: 'error',
+    error,
+    endTime: new Date(),
+  });
+}
+
+/**
+ * Completes the bootstrap process
+ * Sets phase to 'ready' and records completion time
+ *
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function completeBootstrap(): Readonly<BootstrapState> {
+  return setBootstrapState({
+    phase: 'ready',
+    progress: 100,
+    endTime: new Date(),
+  });
+}
+
+/**
+ * Validates if a phase transition is allowed
+ *
+ * @param {LoadingPhase} from - Current phase
+ * @param {LoadingPhase} to - Target phase
+ * @returns {boolean} Whether the transition is valid
+ */
+function isValidPhaseTransition(from: LoadingPhase, to: LoadingPhase): boolean {
+  return VALID_PHASE_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Gets the estimated time remaining for bootstrap
+ *
+ * @returns {number | null} Estimated milliseconds remaining, or null if not available
+ */
+export function getEstimatedTimeRemaining(): number | null {
+  if (!currentState.startTime || currentState.progress === 0) {
+    return null;
+  }
+
+  const elapsed = Date.now() - currentState.startTime.getTime();
+  const progressRemaining = 100 - currentState.progress;
+  const estimatedTotal = (elapsed / currentState.progress) * 100;
+
+  return Math.max(0, (estimatedTotal * progressRemaining) / 100);
+}
+
+/**
+ * Adds a message to the bootstrap state
+ *
+ * @param {TypedMessage} message - The message to add
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function addBootstrapMessage(message: TypedMessage): Readonly<BootstrapState> {
+  return setBootstrapState({
+    messages: [...currentState.messages, message],
+  });
+}
+
+/**
+ * Registers a service as initialized
+ *
+ * @param {string} serviceName - Name of the service
+ * @returns {Readonly<BootstrapState>} The updated state
+ */
+export function registerService(serviceName: string): Readonly<BootstrapState> {
+  if (currentState.services.includes(serviceName)) {
+    return getBootstrapState();
+  }
+
+  return setBootstrapState({
+    services: [...currentState.services, serviceName],
+  });
+}
+
+// Default export
+export default {
+  getBootstrapState,
+  setBootstrapState,
+  subscribeToBootstrapState,
+  resetBootstrapState,
+  startBootstrap,
+  completeBootstrap,
+  setBootstrapError,
+  addBootstrapMessage,
+  registerService,
+  getEstimatedTimeRemaining,
+};

package/src/context/pack-builder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gizzi Context Pack Builder
+ *
+ * Builds structured context packs from workspace files
+ * Production-quality implementation matching Allternit platform
+ */
+import type { ContextPack, ScheduledTask, WorkspaceFile } from '../workspace/types';
+export declare function classifyFile(filePath: string): WorkspaceFile['type'];
+export declare function parseSoulMd(content: string): {
+    trustTiers: ContextPack['trustTiers'];
+    identity: Partial<ContextPack['identity']>;
+};
+export declare function parseHeartbeatMd(content: string): ScheduledTask[];
+export declare function buildSystemPrompt(pack: ContextPack): string;
+export interface BuildContextPackOptions {
+    sessionId: string;
+    agentId: string;
+    agentName: string;
+    files: Map<string, string>;
+}
+export declare function buildContextPack(options: BuildContextPackOptions): ContextPack;
+export declare function getStartupTasks(pack: ContextPack): ScheduledTask[];
+export declare function requiresPermission(pack: ContextPack, action: string): boolean;
+export declare function shouldRefreshContext(pack: ContextPack): boolean;