silvery 0.19.2 → 0.21.0

package/dist/steps-Bp2uNqnn.d.mts

@@ -0,0 +1,202 @@
+//#region packages/ag-react/src/ui/progress/step-node.d.ts
+/**
+ * Step node tree structure for declarative steps
+ *
+ * Parses the user's declarative object structure into an internal tree
+ * that can be rendered and executed.
+ */
+/**
+ * A single step in the tree
+ */
+interface StepNode {
+  /** Display label (auto-generated or custom) */
+  label: string;
+  /** Object key from the declaration */
+  key: string;
+  /** Work function (if leaf node) */
+  work?: (...args: unknown[]) => unknown;
+  /** Child steps (if group node) */
+  children?: StepNode[];
+  /** Indentation level for display */
+  indent: number;
+}
+/**
+ * What users can declare as a step value
+ */
+type StepValue = ((...args: unknown[]) => unknown) | [string, (...args: unknown[]) => unknown] | StepsDef;
+/**
+ * The declarative structure users provide
+ */
+type StepsDef = {
+  [key: string]: StepValue;
+};
+//#endregion
+//#region packages/ag-react/src/ui/progress/als-context.d.ts
+/**
+ * Context available to work functions during step execution
+ */
+interface StepContext {
+  /** Update progress on current step */
+  progress(current: number, total: number): void;
+  /** Create a sub-step (auto-completes previous sub-step) */
+  sub(label: string): void;
+  /** Get current step label (for debugging) */
+  readonly label: string;
+}
+/**
+ * Get the current step context
+ *
+ * Safe to call anywhere - returns a no-op context when called outside
+ * of a steps() execution context.
+ *
+ * @example
+ * ```typescript
+ * async function processFiles(files: string[]) {
+ *   for (let i = 0; i < files.length; i++) {
+ *     step().progress(i + 1, files.length);
+ *     await process(files[i]);
+ *   }
+ * }
+ *
+ * // In tests (no steps context)
+ * await processFiles(["a.md", "b.md"]);  // step() returns no-op, no errors
+ *
+ * // In production (with steps context)
+ * await steps({ process: processFiles }).run();  // Shows progress
+ * ```
+ */
+declare function step(): StepContext;
+//#endregion
+//#region packages/ag-react/src/ui/progress/declarative.d.ts
+/**
+ * Options for run() and pipe() execution
+ */
+interface ExecuteOptions$1 {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean;
+}
+/**
+ * Extract the return type from a generator or async generator
+ */
+type GeneratorReturn<T> = T extends Generator<unknown, infer R, unknown> ? R : T extends AsyncGenerator<unknown, infer R, unknown> ? R : T;
+/**
+ * Unwrap the result type, handling generators specially
+ */
+type UnwrapResult<T> = Awaited<GeneratorReturn<Awaited<T>>>;
+/**
+ * Result type: maps step keys to their return values
+ */
+type StepResults<T extends StepsDef> = { [K in keyof T]: T[K] extends ((...args: unknown[]) => infer R) ? UnwrapResult<R> : T[K] extends [string, (...args: unknown[]) => infer R] ? UnwrapResult<R> : T[K] extends StepsDef ? StepResults<T[K]> : unknown };
+/**
+ * The runner object returned by steps()
+ */
+interface StepsRunner<T extends StepsDef> {
+  /** Internal: the parsed step nodes (for testing) */
+  readonly _steps: StepNode[];
+  /**
+   * Execute all steps sequentially
+   * @returns Results keyed by step name
+   */
+  run(options?: ExecuteOptions$1): Promise<StepResults<T>>;
+  /**
+   * Execute all steps in a pipeline (each receives previous result)
+   * @returns Final step's result
+   */
+  pipe(options?: ExecuteOptions$1): Promise<unknown>;
+  /**
+   * Manually signal completion (for manual execution mode)
+   */
+  done(options?: {
+    clear?: boolean;
+  }): void;
+}
+//#endregion
+//#region packages/ag-react/src/ui/progress/steps.d.ts
+/** Progress update (object form) */
+interface ProgressUpdate {
+  current?: number;
+  total?: number;
+}
+/** Declare all sub-steps upfront (optional, yield as first value) */
+interface DeclareSteps {
+  declare: string[];
+}
+/** What generators can yield */
+type StepYield = string | ProgressUpdate | DeclareSteps;
+/**
+ * Controller for creating and updating sub-steps
+ *
+ * Passed to work functions that need to report sub-step progress.
+ */
+interface StepController {
+  /** Create a new sub-step (auto-completes previous sub-step) */
+  new (label: string): void;
+  /** Update progress on current sub-step */
+  progress(current: number, total: number): void;
+  /** Explicitly complete current sub-step (optional - new() auto-completes) */
+  done(): void;
+}
+/** Work function types */
+type SyncWork<T> = () => T;
+type AsyncWork<T> = () => PromiseLike<T>;
+type SyncGeneratorWork<T> = () => Generator<StepYield, T, unknown>;
+type AsyncGeneratorWork<T> = () => AsyncGenerator<StepYield, T, unknown>;
+/** Work function with step controller for sub-step progress */
+type WorkWithStep<T> = (step: StepController) => T | PromiseLike<T>;
+type WorkFn<T> = SyncWork<T> | AsyncWork<T> | SyncGeneratorWork<T> | AsyncGeneratorWork<T> | WorkWithStep<T>;
+/** Options for execute() */
+interface ExecuteOptions {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean;
+}
+interface StepBuilder {
+  /**
+   * Add a step to run
+   *
+   * @param title - Display title for this step
+   * @param work - Function to execute. Can be:
+   *   - Sync function: `() => result`
+   *   - Async function: `async () => result`
+   *   - Sync generator: `function* () { yield "sub-step"; return result; }`
+   *   - Async generator: `async function* () { yield "sub-step"; return result; }`
+   *
+   * Generators can yield:
+   *   - `"string"` - Creates a new sub-step with that label
+   *   - `{ current: N, total: M }` - Updates progress on current sub-step
+   */
+  run<T>(title: string, work: WorkFn<T>): StepBuilder;
+  /**
+   * Execute all steps in sequence
+   * @param options - Execution options
+   * @returns Results keyed by step title
+   */
+  execute(options?: ExecuteOptions): Promise<Record<string, unknown>>;
+}
+/**
+ * Create a step runner
+ *
+ * @overload Declarative mode - pass an object to declare steps upfront
+ * @overload Fluent mode - chain steps with .run() and execute with .execute()
+ *
+ * @example Declarative mode (recommended)
+ * ```typescript
+ * const loader = steps({
+ *   loadModules,
+ *   loadRepo: { discover, parse },
+ * });
+ * const results = await loader.run({ clear: true });
+ * ```
+ *
+ * @example Fluent mode
+ * ```typescript
+ * await steps()
+ *   .run("Step 1", doStep1)
+ *   .run("Step 2", doStep2)
+ *   .execute();
+ * ```
+ */
+declare function steps<T extends StepsDef>(def: T): StepsRunner<T>;
+declare function steps(): StepBuilder;
+//#endregion
+export { StepContext as a, StepsDef as c, StepsRunner as i, StepBuilder as n, step as o, steps as r, StepNode as s, ExecuteOptions as t };
+//# sourceMappingURL=steps-Bp2uNqnn.d.mts.map

package/dist/steps-Bp2uNqnn.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps-Bp2uNqnn.d.mts","names":[],"sources":["../packages/ag-react/src/ui/progress/step-node.ts","../packages/ag-react/src/ui/progress/als-context.ts","../packages/ag-react/src/ui/progress/declarative.ts","../packages/ag-react/src/ui/progress/steps.ts"],"mappings":";;AAUA;;;;;;;;UAAiB,QAAA;EAWJ;EATX,KAAA;EAYM;EATN,GAAA;EAeU;EAZV,IAAA,OAAW,IAAA;;EAGX,QAAA,GAAW,QAAA;EAUJ;EAPP,MAAA;AAAA;;;AAcF;KARY,SAAA,QACH,IAAA,wCACQ,IAAA,2BACb,QAAA;;;;KAKQ,QAAA;EAAA,CACT,GAAA,WAAc,SAAA;AAAA;;;;;;UCzBA,WAAA;EDUT;ECRN,QAAA,CAAS,OAAA,UAAiB,KAAA;EDchB;ECXV,GAAA,CAAI,KAAA;;WAGK,KAAA;AAAA;;;;;;;;;;AAgDX;;;;;;;;ACtCA;;;;;iBDsCgB,IAAA,CAAA,GAAQ,WAAA;;;;;;UCtCP,gBAAA;EFRT;EEUN,KAAA;AAAA;;;;KAMG,eAAA,MACH,CAAA,SAAU,SAAA,8BACN,CAAA,GACA,CAAA,SAAU,cAAA,8BACR,CAAA,GACA,CAAA;;;;KAKH,YAAA,MAAkB,OAAA,CAAQ,eAAA,CAAgB,OAAA,CAAQ,CAAA;AFZvD;;;AAAA,KEiBK,WAAA,WAAsB,QAAA,kBACb,CAAA,GAAI,CAAA,CAAE,CAAA,eAAe,IAAA,2BAC7B,YAAA,CAAa,CAAA,IACb,CAAA,CAAE,CAAA,uBAAwB,IAAA,2BACxB,YAAA,CAAa,CAAA,IACb,CAAA,CAAE,CAAA,UAAW,QAAA,GACX,WAAA,CAAY,CAAA,CAAE,CAAA;;;AD/CxB;UCsDiB,WAAA,WAAsB,QAAA;;WAE5B,MAAA,EAAQ,QAAA;EDtDjB;;;;EC4DA,GAAA,CAAI,OAAA,GAAU,gBAAA,GAAiB,OAAA,CAAQ,WAAA,CAAY,CAAA;EDtD1C;;;AAgDX;ECYE,IAAA,CAAK,OAAA,GAAU,gBAAA,GAAiB,OAAA;;;;EAKhC,IAAA,CAAK,OAAA;IAAY,KAAA;EAAA;AAAA;;;;UCrBT,cAAA;EACR,OAAA;EACA,KAAA;AAAA;;UAIQ,YAAA;EACR,OAAA;AAAA;;KAIG,SAAA,YAAqB,cAAA,GAAiB,YAAA;;;;;;UAO1B,cAAA;EDzCX;EAAA,KC2CC,KAAA;ED3CuC;EC8C5C,QAAA,CAAS,OAAA,UAAiB,KAAA;ED5CpB;EC+CN,IAAA;AAAA;AD/CO;AAAA,KCmDJ,QAAA,YAAoB,CAAA;AAAA,KACpB,SAAA,YAAqB,WAAA,CAAY,CAAA;AAAA,KACjC,iBAAA,YAA6B,SAAA,CAAU,SAAA,EAAW,CAAA;AAAA,KAClD,kBAAA,YAA8B,cAAA,CAAe,SAAA,EAAW,CAAA;;KAExD,YAAA,OAAmB,IAAA,EAAM,cAAA,KAAmB,CAAA,GAAI,WAAA,CAAY,CAAA;AAAA,KAE5D,MAAA,MACD,QAAA,CAAS,CAAA,IACT,SAAA,CAAU,CAAA,IACV,iBAAA,CAAkB,CAAA,IAClB,kBAAA,CAAmB,CAAA,IACnB,YAAA,CAAa,CAAA;;UASA,cAAA;EDnEM;ECqErB,KAAA;AAAA;AAAA,UAGe,WAAA;EDxEuC;;AAAA;;;;;;;;;;;;ECuFtD,GAAA,IAAO,KAAA,UAAe,IAAA,EAAM,MAAA,CAAO,CAAA,IAAK,WAAA;ED7ElC;;;;;ECoFN,OAAA,CAAQ,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA0B7B,KAAA,WAAgB,QAAA,CAAA,CAAU,GAAA,EAAK,CAAA,GAAI,WAAA,CAAY,CAAA;AAAA,iBAC/C,KAAA,CAAA,GAAS,WAAA"}