📝 Add docstrings to feat/issue-12-upstream-lifecycle-controls

src/cli/create-runtime.ts

@@ -4,7 +4,12 @@ import { SecretResolver } from "../secrets/secret-resolver.js";
 import { MultiUpstreamProcessManager } from "../upstream/multi-upstream-process-manager.js";
 import { UpstreamProcessManager } from "../upstream/upstream-process-manager.js";
 
-/** Validates configuration before resolving secrets or constructing upstream runtime state. */
+/**
+ * Loads configuration, resolves its secrets, and constructs the runtime managers.
+ *
+ * @param configPath - Path to the configuration file
+ * @returns The resolved configuration, upstream process manager, and profile manager
+ */
 export async function createRuntime(configPath: string) {
   const config = await loadConfig(configPath);
   const resolver = new SecretResolver({

src/config/env-expand.ts

@@ -2,7 +2,14 @@ import { MiftahError } from "../utils/errors.js";
 
 const environmentReference = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 
-/** Expands references and returns the values sourced from the environment for diagnostic redaction. */
+/**
+ * Expands environment variable references in configuration values and collects their resolved values.
+ *
+ * @param values - Configuration values that may contain `${NAME}` references
+ * @param environment - Environment variables used to resolve references
+ * @returns The expanded values and the unique resolved environment values
+ * @throws `MiftahError` if a referenced environment variable is undefined
+ */
 export function expandEnvironmentReferencesWithSecretValues(
   values: Record<string, string>,
   environment: NodeJS.ProcessEnv = process.env
@@ -27,7 +34,13 @@ export function expandEnvironmentReferencesWithSecretValues(
   return { values: expandedValues, secretValues: [...secretValues] };
 }
 
-/** Expands environment references while retaining the established value-only public result. */
+/**
+ * Expands environment variable references in string values.
+ *
+ * @param values - Key-value pairs whose values may contain `${NAME}` references.
+ * @param environment - Environment variables used to resolve references.
+ * @returns The values with environment variable references replaced by their resolved values.
+ */
 export function expandEnvironmentReferences(
   values: Record<string, string>,
   environment: NodeJS.ProcessEnv = process.env

src/upstream/upstream-process-manager.ts

@@ -805,6 +805,14 @@ export class UpstreamProcessManager {
   }
 }
 
+/**
+ * Resolves with the promise value or fails when the timeout elapses.
+ *
+ * @param timeoutMs - The maximum time to wait in milliseconds
+ * @param code - The error code used when the timeout elapses
+ * @param message - The error message used when the timeout elapses
+ * @returns The resolved value of `promise`
+ */
 async function withTimeout<T>(
   promise: Promise<T>,
   timeoutMs: number,