@lumpcode/cli-utils 0.0.12 → 0.0.14

package/README.md

@@ -1,6 +1,6 @@
 # @lumpcode/cli-utils
 
-Published npm package: **types**, **`define*` helpers**, and **runtime utilities** for authoring Lumpcode lump configs and recipes.
+**Types**, **`define*` helpers**, and **runtime utilities** for authoring Lumpcode lump configs and recipes.
 
 Re-exports all of [`@lumpcode/cli-types`](https://www.npmjs.com/package/@lumpcode/cli-types) plus runtime helpers bundled from `@lumpcode/cli` sources at build time (`cli-types` stays an external dependency at publish).
 
@@ -15,9 +15,28 @@ npm install @lumpcode/cli-utils
 ## Usage
 
 ```ts
-import { defineConfig, normalizeSteps, type LumpJsConfig } from '@lumpcode/cli-utils';
+import {
+  defineConfig,
+  normalizeSteps,
+  type CursorPresetLumpVariables,
+  type CursorPresetStepVariables,
+  type LumpJsConfig,
+  type StepFn,
+} from '@lumpcode/cli-utils';
+
+export default defineConfig<
+  CursorPresetLumpVariables & { myHookFlag: boolean },
+  CursorPresetStepVariables & { myHookFlag: boolean }
+>({
+  baseBranch: 'main',
+  command: 'cursor',
+  lumpVariables: { model: 'auto', myHookFlag: true },
+  steps: [{ promptTemplate: 'Do the work.', stepVariables: { newChat: true } }],
+});
 ```
 
+`defineConfig` (and the other variable-carrying `define*` helpers) take independent generics `<V, SV>` for lump and step variable bags. Preset option contracts (`CursorPreset*`, `CopilotPreset*`, `PresetSessionStepVariables`, …) are closed TypeScript types — intersect with your own keys via `& Extra`.
+
 ## Build
 
 From the monorepo root:

package/dist/index.cjs

@@ -80,7 +80,7 @@ async function readYamlList(filePath) {
 function normalizeSteps({ prompt: originalPrompt, jsSteps: originalJsSteps, }) {
     const { prompt, jsSteps } = normalizePromptAndSteps({
         prompt: originalPrompt,
-        jsSteps: originalJsSteps
+        jsSteps: originalJsSteps,
     });
     if (jsSteps && Array.isArray(jsSteps)) {
         return jsSteps;
@@ -94,6 +94,10 @@ function normalizeSteps({ prompt: originalPrompt, jsSteps: originalJsSteps, }) {
 }
 function normalizePromptAndSteps({ prompt, jsSteps, }) {
     if (jsSteps !== undefined && !Array.isArray(jsSteps)) {
+        // Solo dynamic steps fn must stay in the steps walk, not become promptFn.
+        if (typeof jsSteps === 'function') {
+            return { prompt, jsSteps: [jsSteps] };
+        }
         return { prompt: jsSteps, jsSteps: undefined };
     }
     return { prompt, jsSteps };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export * from '@lumpcode/cli-types';
-import { CodeBasePath, MaybePromise, Maybe, Context, ContextStatus, Step, PromptFn, PostCommandExecFn, PromptFnInput, LumpVariables, RunLumpInput, GitCommitMessageFn } from '@lumpcode/core';
+import { LumpVariables, CodeBasePath, MaybePromise, Maybe, Context, ContextStatus, StepVariables, PromptFnInput, PostCommandExecFn, Step, PromptFn, RunLumpInput, GitCommitMessageFn } from '@lumpcode/core';
 
 type CommandTag = string;
 
-type ContextMatchFn = (params: {
+type ContextMatchFn<V extends LumpVariables = LumpVariables> = (params: {
     codeBasePath: CodeBasePath;
     codeBasePaths: CodeBasePath[];
-    lumpVariables: Record<string, unknown>;
+    lumpVariables: V;
 }) => MaybePromise<Maybe<{
     contextName: Context['name'];
     filePathVariableName: string;
@@ -29,30 +29,34 @@ type FilePathOrString = FilePath | string;
 
 type MergeObjs<T, U> = Omit<T, keyof U> & U;
 
-type LumpJsConfigStep = MergeObjs<Step, {
+type LumpJsConfigStepsFn<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = (input: Omit<PromptFnInput<V, SV>, 'stepVariables'>) => MaybePromise<LumpJsConfigSteps<V, SV> | LumpJsConfigStepsItem<V, SV>>;
+type LumpJsConfigStepsItem<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = LumpJsConfigStep<V, SV> | LumpJsConfigStepsFn<V, SV> | LumpJsConfigStep<V, SV>['promptTemplate'];
+type LumpJsConfigSteps<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = Array<LumpJsConfigStepsItem<V, SV>>;
+
+type LumpJsConfigPostCommandExecFn<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = (input: Parameters<PostCommandExecFn<V, SV>>[0]) => MaybePromise<void | LumpJsConfigSteps<V, SV> | LumpJsConfigStepsItem<V, SV>>;
+
+type LumpJsConfigStep<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = MergeObjs<Step<V, SV>, {
     promptTemplate?: FilePathOrString;
-    promptFn?: FilePath | PromptFn;
-    postCommandExecFn?: FilePath | PostCommandExecFn;
-    command?: CommandTag | FilePath | Step['commandFn'];
+    promptFn?: FilePath | PromptFn<V, SV>;
+    postCommandExecFn?: FilePath | LumpJsConfigPostCommandExecFn<V, SV>;
+    command?: CommandTag | FilePath | Step<V, SV>['commandFn'];
 }>;
 
-type LumpJsConfigSteps = Array<LumpJsConfigStep | ((input: Exclude<PromptFnInput, 'stepVariables'>) => MaybePromise<LumpJsConfigSteps>) | LumpJsConfigStep['promptTemplate']>;
-
-type LumpJsConfigSoloStep = LumpJsConfigStep | LumpJsConfigStep['promptTemplate'] | LumpJsConfigStep['promptFn'];
-type LumpJsConfig<V extends LumpVariables = LumpVariables> = MergeObjs<Omit<{
-    [K in keyof RunLumpInput<V>]?: NonNullable<RunLumpInput<V>[K]> extends Function ? (RunLumpInput<V>[K] | FilePath) : RunLumpInput<V>[K];
+type LumpJsConfigSoloStep<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = LumpJsConfigStep<V, SV> | LumpJsConfigStep<V, SV>['promptTemplate'] | LumpJsConfigStep<V, SV>['promptFn'];
+type LumpJsConfig<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = MergeObjs<Omit<{
+    [K in keyof RunLumpInput<V, SV>]?: NonNullable<RunLumpInput<V, SV>[K]> extends Function ? (RunLumpInput<V, SV>[K] | FilePath) : RunLumpInput<V, SV>[K];
 }, 'gitCommitMessageFn' | 'projectRoot' | 'branchFn' | 'baseBranch' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'gitAddCommandFn' | 'gitCommitCommandFn' | 'gitPushCommandFn'>, {
-    baseBranch?: RunLumpInput<V>['baseBranch'];
+    baseBranch?: RunLumpInput<V, SV>['baseBranch'];
     /** Which integration line this lump is discovered and scheduled on (defaults to primary branch from local.json). */
     discoveryBranch?: string;
-    command?: LumpJsConfigStep['command'];
+    command?: LumpJsConfigStep<V, SV>['command'];
     contextListJson?: FilePath | Record<string, string>;
-    contextMatchFn?: FilePath | ContextMatchFn;
+    contextMatchFn?: FilePath | ContextMatchFn<V>;
     contextOptionsFn?: FilePath | ContextOptionsFn;
     disabled?: boolean | (() => MaybePromise<boolean>) | FilePath;
     maximumNumberOfConcurrentBranches?: number;
-    prompt?: LumpJsConfigSoloStep;
-    steps?: LumpJsConfigSteps | LumpJsConfigSoloStep;
+    prompt?: LumpJsConfigSoloStep<V, SV>;
+    steps?: LumpJsConfigSteps<V, SV> | LumpJsConfigStepsItem<V, SV>;
     registerCommands?: string[];
     keepHistory?: boolean;
     verbose?: boolean;
@@ -78,9 +82,68 @@ declare function getLumpCommitPrefixForLump(input: {
 /** Reads a YAML file as a flat list; returns `[]` when missing or not an array. */
 declare function readYamlList<T>(filePath: string): Promise<T[]>;
 
-declare function normalizeSteps({ prompt: originalPrompt, jsSteps: originalJsSteps, }: {
-    prompt: LumpJsConfig['prompt'];
-    jsSteps: LumpJsConfig['steps'];
-}): LumpJsConfigSteps;
+declare function normalizeSteps<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>({ prompt: originalPrompt, jsSteps: originalJsSteps, }: {
+    prompt: LumpJsConfig<V, SV>['prompt'];
+    jsSteps: LumpJsConfig<V, SV>['steps'];
+}): LumpJsConfigSteps<V, SV>;
+
+type PresetSessionStepVariables = {
+    newChat?: boolean;
+    chatIdIndex?: string | null;
+};
+
+type CursorAgentPermissions = {
+    cursorConfigDir?: string;
+};
+type CursorPresetLumpVariables = {
+    model?: string;
+    agentPermissions?: CursorAgentPermissions;
+};
+type CursorPresetStepVariables = CursorPresetLumpVariables & PresetSessionStepVariables;
+
+type CopilotAgentPermissions = {
+    writablePaths?: readonly string[];
+    denyShell?: readonly string[];
+};
+type CopilotPresetLumpVariables = {
+    model?: string;
+    agentPermissions?: CopilotAgentPermissions;
+};
+type CopilotPresetStepVariables = CopilotPresetLumpVariables & PresetSessionStepVariables;
+
+type ClaudeCodeAgentPermissions = {
+    permissionMode?: 'default' | 'acceptEdits' | 'plan' | 'auto' | 'dontAsk' | 'bypassPermissions';
+    allowedTools?: readonly string[];
+    disallowedTools?: readonly string[];
+    bare?: boolean;
+    addDirs?: readonly string[];
+};
+type ClaudeCodePresetLumpVariables = {
+    model?: string;
+    agentPermissions?: ClaudeCodeAgentPermissions;
+};
+type ClaudeCodePresetStepVariables = ClaudeCodePresetLumpVariables & PresetSessionStepVariables;
+
+type OpenCodeAgentPermissions = {
+    auto?: boolean;
+    agent?: string;
+};
+type OpenCodePresetLumpVariables = {
+    model?: string;
+    agentPermissions?: OpenCodeAgentPermissions;
+};
+type OpenCodePresetStepVariables = OpenCodePresetLumpVariables & PresetSessionStepVariables;
+
+type CodexAgentPermissions = {
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    dangerouslyBypassApprovalsAndSandbox?: boolean;
+    addDirs?: readonly string[];
+};
+type CodexPresetLumpVariables = {
+    model?: string;
+    agentPermissions?: CodexAgentPermissions;
+};
+type CodexPresetStepVariables = CodexPresetLumpVariables & PresetSessionStepVariables;
 
 export { getContextStatus, getGitCommitMessage, getLumpCommitPrefixForLump, makeGitCommitMessageFnFromLumpName, normalizeSteps, readYamlList };
+export type { ClaudeCodeAgentPermissions, ClaudeCodePresetLumpVariables, ClaudeCodePresetStepVariables, CodexAgentPermissions, CodexPresetLumpVariables, CodexPresetStepVariables, CopilotAgentPermissions, CopilotPresetLumpVariables, CopilotPresetStepVariables, CursorAgentPermissions, CursorPresetLumpVariables, CursorPresetStepVariables, OpenCodeAgentPermissions, OpenCodePresetLumpVariables, OpenCodePresetStepVariables, PresetSessionStepVariables };

package/dist/index.js

@@ -57,7 +57,7 @@ async function readYamlList(filePath) {
 function normalizeSteps({ prompt: originalPrompt, jsSteps: originalJsSteps, }) {
     const { prompt, jsSteps } = normalizePromptAndSteps({
         prompt: originalPrompt,
-        jsSteps: originalJsSteps
+        jsSteps: originalJsSteps,
     });
     if (jsSteps && Array.isArray(jsSteps)) {
         return jsSteps;
@@ -71,6 +71,10 @@ function normalizeSteps({ prompt: originalPrompt, jsSteps: originalJsSteps, }) {
 }
 function normalizePromptAndSteps({ prompt, jsSteps, }) {
     if (jsSteps !== undefined && !Array.isArray(jsSteps)) {
+        // Solo dynamic steps fn must stay in the steps walk, not become promptFn.
+        if (typeof jsSteps === 'function') {
+            return { prompt, jsSteps: [jsSteps] };
+        }
         return { prompt: jsSteps, jsSteps: undefined };
     }
     return { prompt, jsSteps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumpcode/cli-utils",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Types, defineX helpers, and runtime utilities for Lumpcode lump configs and recipes",
   "keywords": [
     "lumpcode",
@@ -39,11 +39,12 @@
   "scripts": {
     "prepublishOnly": "npm run build",
     "clean": "rm -rf dist",
-    "build": "rollup -c"
+    "build": "rollup -c",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@lumpcode/cli-types": "^0.0.12",
-    "@lumpcode/core": "^0.0.12",
+    "@lumpcode/cli-types": "^0.0.14",
+    "@lumpcode/core": "^0.0.14",
     "js-yaml": "^5.0.0"
   },
   "devDependencies": {
@@ -53,6 +54,7 @@
     "rollup": "^4.52.5",
     "rollup-plugin-dts": "^6.1.1",
     "tslib": "^2.8.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
   }
 }