@lumpcode/recipes 0.0.12

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import { CommandDescriptor, MaybePromise, PostCommandExecFn, Step } from '@lumpcode/core';
+import { GetContextListFnInput, GetContextListFn, CommandFn, LumpJsConfig, LumpJsConfigSteps, LumpVariables, MaybePromise as MaybePromise$1, Context } from '@lumpcode/cli-utils';
+
+/** Run a shell script via `sh -c` (portable on Unix-like systems and Git Bash on Windows). */
+declare function shellCommand(script: string): CommandDescriptor;
+
+type MaybePromGetter<T, P = void> = T | ((input: P) => MaybePromise<T>);
+declare function normalizeMaybePromGetter<T, P = void>(maybePromGetter: MaybePromGetter<T, P>): (input: P) => MaybePromise<T>;
+declare function normalizeMaybePromGetter<T, P = void>(maybePromGetter: MaybePromGetter<T, P> | undefined, defaultValue: T): (input?: P) => MaybePromise<T>;
+
+type ContextVariables = Record<string, string | number | boolean>;
+type EphemeralContextListFnOptions = {
+    contextCount?: MaybePromGetter<number, GetContextListFnInput>;
+    contextName?: MaybePromGetter<string, {
+        index: number;
+        count: number;
+    }>;
+    variables?: MaybePromGetter<ContextVariables, {
+        contextName: string;
+        index: number;
+        count: number;
+    }>;
+};
+declare function ephemeralContextListFn(options?: EphemeralContextListFnOptions): GetContextListFn;
+
+type StepIndex = number | number[];
+type ValidationCommandFnInput = Parameters<CommandFn>[0] & {
+    currentIteration: number;
+    prevValidateCommandResult: string | null;
+    contextRunStateIsOkFlagKey: string;
+};
+type ValidationCommandFn = (input: ValidationCommandFnInput) => MaybePromise<CommandDescriptor | null | undefined>;
+type IsValidationCommandResultOkInput = Parameters<PostCommandExecFn>[0] & {
+    currentIteration: number;
+};
+type GetFirstStepsInput = {
+    currentIteration: number;
+    prevValidateCommandResult: string | null;
+    prevValidateCommandDescriptor: CommandDescriptor | null;
+};
+type GetRecursiveStepsOptions = {
+    maxIterations?: number;
+    validationCommandFn?: ValidationCommandFn;
+    isValidationCommandResultOk?: (input: IsValidationCommandResultOkInput) => boolean;
+    getFirstSteps?: (input: GetFirstStepsInput) => LumpJsConfig['steps'];
+    currentIteration?: number;
+    prevValidateCommandResult?: string | null;
+    prevValidateCommandDescriptor?: CommandDescriptor | null;
+    contextRunStateIsOkFlagKey?: string;
+};
+/** Agent prompt(s) followed by a validation command, retried until checks pass or `maxIterations` is reached. */
+declare function getRecursiveSteps({ maxIterations, validationCommandFn, isValidationCommandResultOk, getFirstSteps, currentIteration, prevValidateCommandResult, prevValidateCommandDescriptor, contextRunStateIsOkFlagKey, }: GetRecursiveStepsOptions): LumpJsConfigSteps;
+
+declare function defaultFixSteps(input: GetFirstStepsInput): LumpJsConfig['steps'];
+interface RetryUntilGreenInput {
+    steps: LumpJsConfig['steps'];
+    fixSteps?: typeof defaultFixSteps;
+    validationCommandFn: ValidationCommandFn;
+    isValidationCommandResultOk?: (input: IsValidationCommandResultOkInput) => boolean;
+    contextRunStateIsOkFlagKey?: GetRecursiveStepsOptions['contextRunStateIsOkFlagKey'];
+    maxIterations?: GetRecursiveStepsOptions['maxIterations'];
+}
+/** Work steps, validation command, and optional fix steps — retried until checks pass or `maxIterations`. */
+declare function retryUntilGreen({ steps, fixSteps, validationCommandFn, isValidationCommandResultOk, contextRunStateIsOkFlagKey, maxIterations, }: RetryUntilGreenInput): LumpJsConfigSteps;
+
+declare function lumpPathAndName(configUrl: string | URL): [lumpPath: string, lumpName: string];
+
+/** Resolves git project root from a lump `config.ts` module URL. */
+declare function projectRootFromConfigUrl(configUrl: string | URL): string;
+
+/** Fails the context when the artifact referenced by a context variable was not created. */
+declare function requireArtifactStep(artifactPathVarName: string): Step;
+
+type BacklogPaths$1 = {
+    lumpPath: string;
+    lumpName: string;
+    backlogFilePath: string;
+    doneFilePath: string;
+};
+declare function resolveBacklogPaths(configUrl: string | URL, overrides?: {
+    backlogFilePath?: string;
+    doneFilePath?: string;
+}): BacklogPaths$1;
+
+/** Moves a finished backlog item from BACKLOG.yml to DONE.yml after the context completes. */
+declare const setTaskDoneStep: (input: {
+    backlogVarName: string;
+    doneVarName: string;
+}) => Step;
+
+type ImplValidateCommand = string | CommandDescriptor | ValidationCommandFn;
+declare function resolveImplValidateCommand(implValidateCommand: ImplValidateCommand): ValidationCommandFn;
+
+type Recipe<Options, V extends LumpVariables = LumpVariables> = (options: Options) => LumpJsConfig<V>;
+declare function defineRecipe<Options, V extends LumpVariables = LumpVariables>(recipe: Recipe<Options, V>): Recipe<Options, V>;
+
+type BaseBacklogItem = {
+    name: string;
+    task: string;
+    priority: number;
+    dependsOn?: string[];
+};
+type DoneBacklogItem<T extends BaseBacklogItem = BaseBacklogItem> = T & {
+    completedAt: string;
+};
+
+type YmlBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> = {
+    backlogFilePath: string;
+    parseItem?: (item: BaseBacklogItem, index: number, raw: unknown) => Item;
+    parseContext?: (item: Item, index: number) => MaybePromise$1<{
+        parsed?: Partial<Context>;
+        ignored?: boolean;
+    }>;
+};
+declare function ymlBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem>({ backlogFilePath, parseItem, parseContext, }: YmlBacklogContextsOptions<Item>): GetContextListFn;
+
+/** Validates and normalizes one YAML backlog row; throws on invalid input. */
+declare function validateBaseBacklogItem(raw: unknown, index: number): BaseBacklogItem;
+
+type AbstractionBacklogOptions = {
+    implValidateCommand?: ValidationCommandFn | string;
+    /** Lump config module URL — pass `import.meta.url` from `config.ts`. */
+    configUrl: string | URL;
+} & Omit<LumpJsConfig, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps'>;
+declare const abstractionBacklog: Recipe<AbstractionBacklogOptions>;
+
+type AbstractionFinderOptions = {
+    scanDirectories: string[];
+    customPrompt?(): string;
+    maxPendingAbstractions?: number;
+    backlogFilePath: string;
+    doneFilePath?: string;
+    prdDirPath?: string;
+} & LumpJsConfig;
+declare const abstractionFinder: Recipe<AbstractionFinderOptions>;
+
+type BacklogStageDefinition = {
+    steps: NonNullable<LumpJsConfig['steps']>;
+    completion: 'keepPending' | 'moveToDone';
+};
+type BacklogPaths = {
+    lumpPath: string;
+    lumpName: string;
+    backlogFilePath: string;
+    doneFilePath: string;
+};
+type BacklogItemResolution<StageName extends string> = {
+    ignored: true;
+} | {
+    stage: StageName;
+    contextName?: string;
+    variables?: LumpVariables;
+    additionalDependsOnContexts?: string[];
+};
+type BacklogOptions<Item extends BaseBacklogItem, Stages extends Record<string, BacklogStageDefinition>> = {
+    configUrl: string | URL;
+    backlogFilePath?: string;
+    doneFilePath?: string;
+    stages: Stages;
+    parseItem?: (item: BaseBacklogItem, index: number, raw: unknown) => Item;
+    resolveItem(input: {
+        item: Item;
+        paths: BacklogPaths;
+    }): MaybePromise<BacklogItemResolution<Extract<keyof Stages, string>>>;
+} & Omit<LumpJsConfig, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps'>;
+declare const BACKLOG_STAGE_VAR = "BACKLOG_STAGE";
+declare const BACKLOG_TASK_NAME_VAR = "TASK_NAME";
+declare const BACKLOG_TASK_VAR = "TASK";
+declare const BACKLOG_FILE_VAR = "BACKLOG_FILE";
+declare const BACKLOG_DONE_FILE_VAR = "DONE_FILE";
+
+declare function backlog<Item extends BaseBacklogItem, Stages extends Record<string, BacklogStageDefinition>>(options: BacklogOptions<Item, Stages>): LumpJsConfig;
+declare const backlogRecipe: Recipe<BacklogOptions<BaseBacklogItem, Record<string, BacklogStageDefinition>>>;
+
+type FeatureBacklogItem = BaseBacklogItem & {
+    manualPrd?: boolean;
+};
+type FeatureBacklogStage = 'makePrd' | 'makeTestPlan' | 'testImpl' | 'implementation';
+type FeatureBacklogContextVariables = {
+    TASK_NAME: string;
+    TASK: string;
+    BACKLOG_FILE: string;
+    DONE_FILE: string;
+    BACKLOG_STAGE: FeatureBacklogStage;
+    PRD_FILE?: string;
+    TEST_PLAN_FILE?: string;
+};
+type FeatureBacklogOptions = {
+    configUrl: string | URL;
+    baseBranch: string;
+    implValidateCommand: ValidationCommandFn | string;
+    backlogFilePath?: string;
+    doneFilePath?: string;
+} & Omit<LumpJsConfig, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps' | 'baseBranch'>;
+declare function resolveFeatureBacklogItem(item: FeatureBacklogItem, paths: BacklogPaths$1, projectRoot: string, lumpName: string, baseBranch: string): Promise<BacklogItemResolution<FeatureBacklogStage>>;
+declare const featureBacklog: Recipe<FeatureBacklogOptions>;
+
+export { BACKLOG_DONE_FILE_VAR, BACKLOG_FILE_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, getRecursiveSteps, lumpPathAndName, normalizeMaybePromGetter, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
+export type { AbstractionBacklogOptions, AbstractionFinderOptions, BacklogItemResolution, BacklogOptions, BacklogPaths$1 as BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogStage, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, MaybePromGetter, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };