@lumpcode/recipes 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +1,20 @@
 import { CommandDescriptor, MaybePromise, PostCommandExecFn, Step } from '@lumpcode/core';
-import { LumpVariables, GetContextListFnInput, GetContextListFn, StepVariables, CommandFn, LumpJsConfig, LumpJsConfigSteps, MaybePromise as MaybePromise$1, Context } from '@lumpcode/cli-utils';
+import { LumpVariables, PostSetupWorkspaceFnInput, PostTeardownWorkspaceFn, GetContextListFnInput, GetContextListFn, StepVariables, CommandFn, LumpJsConfig, LumpJsConfigSteps, MaybePromise as MaybePromise$1, Context, PromptFn } 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;
 
+declare const OPEN_PR_PROVIDERS: readonly ["github"];
+type OpenPrProvider = (typeof OPEN_PR_PROVIDERS)[number];
+type OpenPrPostTeardownOptions<V extends LumpVariables = LumpVariables> = {
+    provider: OpenPrProvider;
+    /** Overrides the lump name parsed from `lump/<lumpName>/…` branches. */
+    lumpName?: string;
+    title?: (input: PostSetupWorkspaceFnInput<V>) => string;
+    body?: (input: PostSetupWorkspaceFnInput<V>) => string;
+};
+declare function openPrPostTeardown<V extends LumpVariables = LumpVariables>(options: OpenPrPostTeardownOptions<V>): PostTeardownWorkspaceFn<V>;
+
 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>;
@@ -92,9 +103,12 @@ type DoneBacklogItem<T extends BaseBacklogItem = BaseBacklogItem> = T & {
 
 type FolderBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> = {
     backlogItemsDir: string;
+    /** When true, umbrella parents with tickets are emitted for wrap-up (featureBacklog). */
+    includeUmbrellaParents?: boolean;
     /**
      * `folderName` is the path relative to `todo/`: the item folder, or
-     * `<parent>/tickets/<ticket>` when the parent has a `tickets/` directory.
+     * `<parent>/tickets/<ticket>` when the parent is an umbrella
+     * (`tickets/` exists or completed tickets exist).
      */
     parseItem?: (item: BaseBacklogItem, folderName: string, raw: unknown) => Item;
     parseContext?: (item: Item, folderName: string) => MaybePromise$1<{
@@ -102,9 +116,22 @@ type FolderBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem
         ignored?: boolean;
     }>;
 };
-/** Path relative to `todo/`, using `/` so it is stable in context variables. */
-declare function listTodoRelativeDirs(todoDir: string): Promise<string[]>;
-declare function folderBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem, V extends LumpVariables = LumpVariables>({ backlogItemsDir, parseItem, parseContext, }: FolderBacklogContextsOptions<Item>): GetContextListFn<V>;
+type ListTodoRelativeDirsOptions = {
+    includeUmbrellaParents?: boolean;
+};
+/** Live and completed ticket folder names for an umbrella parent, sorted uniquely. */
+declare function listUmbrellaTicketNames(input: {
+    todoDir: string;
+    parentName: string;
+}): Promise<string[]>;
+/**
+ * Path relative to `todo/`, using `/` so it is stable in context variables.
+ * A top-level folder is an umbrella (never itself an item) when it has live
+ * tickets, a leftover `tickets/` directory, or tickets already under
+ * sibling `completed/<name>/tickets/`.
+ */
+declare function listTodoRelativeDirs(todoDir: string, options?: ListTodoRelativeDirsOptions): Promise<string[]>;
+declare function folderBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem, V extends LumpVariables = LumpVariables>({ backlogItemsDir, includeUmbrellaParents, parseItem, parseContext, }: FolderBacklogContextsOptions<Item>): GetContextListFn<V>;
 
 /** Moves a finished backlog item folder from todo/ to the same relative path under completed/. */
 declare function folderSetTaskDoneStep<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(input: {
@@ -174,6 +201,8 @@ type BacklogItemResolution<StageName extends string> = {
 type BacklogOptions<Item extends BaseBacklogItem, V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables, Stages extends Record<string, BacklogStageDefinition<V, SV>> = Record<string, BacklogStageDefinition<V, SV>>> = {
     configUrl: string | URL;
     backlogItemsDir?: string;
+    /** When true, umbrella parents with tickets are emitted for wrap-up (featureBacklog). */
+    includeUmbrellaParents?: boolean;
     stages: Stages;
     parseItem?: (item: BaseBacklogItem, folderName: string, raw: unknown) => Item;
     resolveItem(input: {
@@ -192,41 +221,75 @@ declare const BACKLOG_ITEM_DIR_VAR = "BACKLOG_ITEM_DIR";
 declare function backlog<Item extends BaseBacklogItem, V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables, Stages extends Record<string, BacklogStageDefinition<V, SV>> = Record<string, BacklogStageDefinition<V, SV>>>(options: BacklogOptions<Item, V, SV, Stages>): LumpJsConfig<V, SV>;
 declare const backlogRecipe: typeof backlog;
 
-type FeatureBacklogWorkflow = 'tdd' | 'directImpl' | 'manual';
-type FeatureBacklogRunnableWorkflow = Exclude<FeatureBacklogWorkflow, 'manual'>;
+declare const FEATURE_BACKLOG_WORKFLOW_STAGES: readonly ["req", "testPlan", "testImpl", "impl", "directImpl"];
+type FeatureBacklogWorkflowStage = (typeof FEATURE_BACKLOG_WORKFLOW_STAGES)[number];
+type FeatureBacklogWorkflow = readonly FeatureBacklogWorkflowStage[];
+type FeatureBacklogTerminalStage = 'impl' | 'directImpl';
+declare const DEFAULT_FEATURE_BACKLOG_WORKFLOW: readonly ["req", "testPlan", "testImpl"];
+declare const DEFAULT_PRIMARY_DISCOVERY_BRANCH = "dev";
+declare const DEFAULT_ITEM_DISCOVERY_BRANCH_PREFIX = "feature";
+declare const FEATURE_BACKLOG_RESERVED_NAME_SUFFIXES: readonly ["_req", "_testPlan", "_testImpl"];
 type FeatureBacklogItem = BaseBacklogItem & {
-    manualReq?: boolean;
     workflow?: FeatureBacklogWorkflow;
+    manual?: boolean;
     completedAt?: string;
     /** Path relative to `backlogItems/todo/`; tickets live at `<parent>/tickets/<name>`. */
     todoRelativeDir: string;
     /** Parent todo folder name when this item is a ticket. */
     parentName?: string;
 };
-type FeatureBacklogStage = 'makeReq' | 'makeTestPlan' | 'testImpl' | 'implementation' | 'directImpl';
+type FeatureBacklogStage = 'req' | 'testPlan' | 'testImpl' | 'impl' | 'directImpl' | 'completion';
 type FeatureBacklogContextVariables = {
     TASK_NAME: string;
     TASK: string;
     BACKLOG_ITEMS_DIR: string;
     BACKLOG_ITEM_DIR: string;
     BACKLOG_STAGE: FeatureBacklogStage;
+    WORKFLOW?: string;
     REQ_FILE?: string;
     TEST_PLAN_FILE?: string;
 };
+type FeatureBacklogPromptStage = Exclude<FeatureBacklogStage, 'completion'>;
+type FeatureBacklogPromptFns<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = {
+    [K in FeatureBacklogPromptStage]?: PromptFn<V, SV>;
+};
 type FeatureBacklogOptions<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = {
     configUrl: string | URL;
     implValidateCommand?: ValidationCommandFn<V, SV> | string;
     backlogItemsDir?: string;
-} & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps'>;
-declare const FEATURE_BACKLOG_WORKFLOWS: readonly ["tdd", "directImpl", "manual"];
-declare function parseFeatureWorkflow(itemName: string, raw: unknown): FeatureBacklogWorkflow | undefined;
+    primaryDiscoveryBranch?: string;
+    itemDiscoveryBranchPrefix?: string;
+    promptFns?: FeatureBacklogPromptFns<V, SV>;
+} & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps' | 'discoveryBranch' | 'discoveryBranches'>;
+
+declare function resolveFeatureBacklogDiscoveryOptions(options: {
+    primaryDiscoveryBranch?: string;
+    itemDiscoveryBranchPrefix?: string;
+}): {
+    primaryDiscoveryBranch: string;
+    itemDiscoveryBranchPrefix: string;
+};
+
 declare function resolveFeatureBacklogItem(input: {
     item: FeatureBacklogItem;
     paths: BacklogPaths;
     projectRoot: string;
     discoveryBranch: string;
+    primaryDiscoveryBranch: string;
+    itemDiscoveryBranchPrefix: string;
 }): Promise<BacklogItemResolution<FeatureBacklogStage>>;
+
+declare function parseFeatureWorkflow(itemName: string, raw: unknown): FeatureBacklogWorkflow | undefined;
+
+declare const defaultReqPrompt: PromptFn;
+declare function defaultReqFixPrompt(prevValidateCommandResult?: string | null): PromptFn;
+declare const defaultTestPlanPrompt: PromptFn;
+declare function defaultTestPlanFixPrompt(prevValidateCommandResult?: string | null): PromptFn;
+declare const defaultTestImplPrompt: PromptFn;
+declare const defaultImplPrompt: PromptFn;
+declare const defaultDirectImplPrompt: PromptFn;
+
 declare const featureBacklog: <V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(options: FeatureBacklogOptions<V, SV>) => LumpJsConfig<V, SV>;
 
-export { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, FEATURE_BACKLOG_WORKFLOWS, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, listTodoRelativeDirs, lumpPathAndName, normalizeMaybePromGetter, parseFeatureWorkflow, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
-export type { AbstractionBacklogOptions, AbstractionFinderOptions, AbstractionFinderScanCommand, BacklogItemResolution, BacklogOptions, BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogRunnableWorkflow, FeatureBacklogStage, FeatureBacklogWorkflow, FolderBacklogContextsOptions, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, MaybePromGetter, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };
+export { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, DEFAULT_FEATURE_BACKLOG_WORKFLOW, DEFAULT_ITEM_DISCOVERY_BRANCH_PREFIX, DEFAULT_PRIMARY_DISCOVERY_BRANCH, FEATURE_BACKLOG_RESERVED_NAME_SUFFIXES, FEATURE_BACKLOG_WORKFLOW_STAGES, OPEN_PR_PROVIDERS, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defaultDirectImplPrompt, defaultImplPrompt, defaultReqFixPrompt, defaultReqPrompt, defaultTestImplPrompt, defaultTestPlanFixPrompt, defaultTestPlanPrompt, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, listTodoRelativeDirs, listUmbrellaTicketNames, lumpPathAndName, normalizeMaybePromGetter, openPrPostTeardown, parseFeatureWorkflow, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogDiscoveryOptions, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
+export type { AbstractionBacklogOptions, AbstractionFinderOptions, AbstractionFinderScanCommand, BacklogItemResolution, BacklogOptions, BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogPromptFns, FeatureBacklogPromptStage, FeatureBacklogStage, FeatureBacklogTerminalStage, FeatureBacklogWorkflow, FeatureBacklogWorkflowStage, FolderBacklogContextsOptions, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, ListTodoRelativeDirsOptions, MaybePromGetter, OpenPrPostTeardownOptions, OpenPrProvider, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };