@lumpcode/core 0.1.0 → 0.2.0

package/README.md

@@ -248,23 +248,25 @@ type GitCommitMessageFn = (input: {
 
 Maps a context to its normalized git commit message. **The returned message must be unique per context** -- it is the source of truth used to track whether a context has already been processed (see [Context Tracking with Git Commits](#context-tracking-with-git-commits)).
 
-### `gitAddCommandFn`
+### `gitAddCommitFn`
 
-**Type:** `GitAddCommandFn` -- **Default:** `git add .`
+**Type:** `GitAddCommitFn` -- **Default:** ``git add . && git commit --allow-empty -m <commitMessage>``
 
-Customize the git add command. Receives `{ baseBranch, branchName, contextList, workspacePath, context }` and is invoked **once per context**, right before that context's commit.
+Per-context add+commit. Receives `{ baseBranch, branchName, workspacePath, context, commitMessage }` (no `contextList`) and returns a `Success` / `Failure` result:
 
-### `gitCommitCommandFn`
+| Return | Behavior |
+| --- | --- |
+| `success(string)` | Core runs that shell string with `cwd: workspacePath` |
+| `success(null \| undefined)` | No-op (injector already did the work, or intentional skip) |
+| `success('')` / `failure(msg)` / throw | Hard-fail the run with `reason: 'gitAddCommitFailed'` |
 
-**Type:** `GitCommitCommandFn` -- **Default:** ``git commit -m "${commitMessage}"``
+Invoked **once per context** after `teardownFn`, producing exactly one commit per context on the work branch.
 
-Customize the git commit command. Receives the same input as `gitAddCommandFn` plus `{ commitMessage }`. Invoked **once per context**, producing exactly one commit per context on the work branch.
+### `gitPushFn`
 
-### `gitPushCommandFn`
+**Type:** `GitPushFn` -- **Default:** ``git push origin <branchName>``
 
-**Type:** `GitPushCommandFn` -- **Default:** ``git push origin ${branchName}``
-
-Customize the git push command. Invoked **once per branch**, after all per-context commits are made.
+Once-per-branch push after all per-context add+commits succeed. Same Success / Failure payload rules as `gitAddCommitFn`, except failures are **log-only** (the run stays successful).
 
 ### `setupWorkspaceFn`
 
@@ -275,7 +277,7 @@ Prepares the workspace before prompt execution. It returns an object with two fi
 - `command` — the shell command to run (e.g. checkout the base branch, fetch, create the work branch).
 - `workspacePath` — the directory where all subsequent operations (prompt execution, git add/commit/push) will take place. The default implementation returns `'.'`, so those commands run with `cwd: '.'` (the **host process's current working directory**). If your process's cwd is not `projectRoot`, pass an absolute path (e.g. `projectRoot` or a worktree path) so behavior is unambiguous.
 
-> **Where commands run:** `setupWorkspaceFn` is the only function whose returned `command` runs at `projectRoot`. All other function parameters that return commands (`gitAddCommandFn`, `gitCommitCommandFn`, `gitPushCommandFn`, `commandFn`, `teardownWorkspaceFn`) execute their commands at `workspacePath`.
+> **Where commands run:** `setupWorkspaceFn` is the only function whose returned `command` runs at `projectRoot`. All other function parameters that return commands (`gitAddCommitFn`, `gitPushFn`, `commandFn`, `teardownWorkspaceFn`) execute their commands at `workspacePath`.
 
 The default implementation command checks out the base branch, fetches, pulls, deletes and re-creates the work branch (with `cwd: projectRoot` for this setup command only):
 
@@ -422,7 +424,7 @@ const steps: Steps = [
 
 ## Context Tracking with Git Commits
 
-Lumpcode uses normalized git commit messages to record which contexts have already been processed. Each completed context contributes **exactly one commit** whose subject equals `gitCommitMessageFn({ context, ... })`. On every subsequent call to `runLump`, contexts whose normalized commit message is already present on a remote branch are skipped so the run only works on what remains. This lets you call `runLump` repeatedly (e.g. in a cron job) and each invocation picks up where the previous one left off, progressively working through the full context list without ever re-processing a context.
+Lumpcode uses normalized git commit messages to record which contexts have already been processed. Each completed context contributes **exactly one commit** whose message contains the string returned by `gitCommitMessageFn({ context, ... })` (written as the subject; still matched if squash moves it into the body). On every subsequent call to `runLump`, contexts whose marker is already present on a remote branch are skipped so the run only works on what remains. This lets you call `runLump` repeatedly (e.g. in a cron job) and each invocation picks up where the previous one left off, progressively working through the full context list without ever re-processing a context.
 
 > If you'd rather not wire up your own scheduler, [@lumpcode/cli](https://www.npmjs.com/package/@lumpcode/cli) ships a built-in daemon (`lumpcode start`) that calls `runLump` on a tick, with concurrent-branch limits and per-lump enable/disable already wired in.
 
@@ -434,7 +436,7 @@ By default, a context named `my_component_ts` produces a commit with the subject
 LUMP:my_component_ts
 ```
 
-You can customize this via the `[gitCommitMessageFn](#gitcommitmessagefn)` parameter. The returned subject **must be unique per context** -- it is the only thing tying the commit back to its context.
+You can customize this via the `[gitCommitMessageFn](#gitcommitmessagefn)` parameter. The returned string **must be unique per context** -- it is the only thing tying the commit back to its context. Status matches that string anywhere in the full commit message, as long as it is not a prefix of a longer `[A-Za-z0-9_-]*` token (`foo` does not match `foo-bar`).
 
 ### Context statuses
 
@@ -458,7 +460,7 @@ A context with `dependsOnContexts` is only eligible when **all** of its listed d
 
 ```bash
 git fetch --all
-git log --remotes=origin --grep="^LUMP:" --format='%H %s'
+git log --remotes=origin -F --grep="LUMP:" --format='%H %s'
 ```
 
 **Check if a specific context has been processed (any remote ref):**
@@ -510,10 +512,10 @@ flowchart TD
     LoopStart --> Setup["setupFn()"]
     Setup --> ExecPrompts["Execute steps sequentially"]
     ExecPrompts --> Teardown["teardownFn()"]
-    Teardown --> AddCommit["git add + git commit -m gitCommitMessageFn(context)"]
+    Teardown --> AddCommit["gitAddCommitFn (commitMessage from gitCommitMessageFn)"]
     AddCommit --> LoopCheck{"More contexts?"}
     LoopCheck -->|Yes| LoopStart
-    LoopCheck -->|No| Push["gitPushCommandFn (branch only)"]
+    LoopCheck -->|No| Push["gitPushFn (branch only)"]
     Push --> TeardownWorkspace["teardownWorkspaceFn()"]
     TeardownWorkspace --> Done["Return Success or Failure"]
 ```

package/dist/helpers/execAsync/main.d.ts

@@ -1,14 +1,19 @@
-export declare function execAsync(command: string, options?: {
-    cwd?: string;
-}): Promise<import("../..").Failure<{
+import type { Failure, Success } from '../../types';
+export type ExecAsyncFailureReason = 'timeout' | 'exit';
+export type ExecAsyncFailure = {
     message: string;
+    reason: ExecAsyncFailureReason;
     info: {
         command: string;
-        stdout: any;
-        stderr: any;
+        stdout: unknown;
+        stderr: unknown;
     };
-}> | import("../..").Success<{
-    stdout: any;
-    stderr: any;
-}>>;
+};
+export declare function execAsync(command: string, options?: {
+    cwd?: string;
+    timeoutMillis?: number;
+}): Promise<Success<{
+    stdout: string;
+    stderr: string;
+}> | Failure<ExecAsyncFailure>>;
 //# sourceMappingURL=main.d.ts.map

package/dist/helpers/execAsync/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/execAsync/main.ts"],"names":[],"mappings":"AAMA,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;IA4B1E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/execAsync/main.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAQpD,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,IAAI,EAAE;QACF,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACnB,CAAC;CACL,CAAC;AAoBF,wBAAsB,SAAS,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CA4BlF"}

package/dist/helpers/executeStepsForContextList/main.d.ts

@@ -1,19 +1,14 @@
-import { ContextList, ContextRunState, ExecuteStepsFailureData, Failure, Logger, LumpVariables, StepVariables } from "../../types";
+import { ContextList, ContextRunState, Failure, Logger, LumpVariables, StepVariables, Success } from "../../types";
 import type { RunLumpInput } from '../../usages';
-export type ExecuteStepsForContextListParams<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = Required<Pick<RunLumpInput<V, SV>, 'baseBranch' | 'branchFn' | 'lumpVariables' | 'steps' | 'setupFn' | 'teardownFn' | 'gitAddCommandFn' | 'gitCommitCommandFn' | 'gitPushCommandFn' | 'gitCommitMessageFn' | 'projectRoot' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'getKeepHistoryFilePathFn'>> & {
+export type ExecuteStepsForContextListParams<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = Required<Pick<RunLumpInput<V, SV>, 'baseBranch' | 'branchFn' | 'lumpVariables' | 'steps' | 'setupFn' | 'teardownFn' | 'gitAddCommitFn' | 'gitPushFn' | 'gitCommitMessageFn' | 'projectRoot' | 'setupWorkspaceFn' | 'teardownWorkspaceFn' | 'getKeepHistoryFilePathFn'>> & {
     contextList: ContextList;
     logger?: Logger;
     /** When aborted, in-flight commands are killed and the step walk stops (ignores continueOnError). */
     signal?: AbortSignal;
 };
-export declare function executeStepsForContextList<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>({ baseBranch, branchFn, lumpVariables, contextList, gitAddCommandFn, gitCommitCommandFn, gitPushCommandFn, gitCommitMessageFn, projectRoot, steps, setupFn, setupWorkspaceFn, teardownFn, teardownWorkspaceFn, getKeepHistoryFilePathFn, logger: loggerInput, signal, }: ExecuteStepsForContextListParams<V, SV>): Promise<Failure<{
+export declare function executeStepsForContextList<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>({ baseBranch, branchFn, lumpVariables, contextList, gitAddCommitFn, gitPushFn, gitCommitMessageFn, projectRoot, steps, setupFn, setupWorkspaceFn, teardownFn, teardownWorkspaceFn, getKeepHistoryFilePathFn, logger: loggerInput, signal, }: ExecuteStepsForContextListParams<V, SV>): Promise<Failure<{
     message: string;
-    info: {
-        command: string;
-        stdout: any;
-        stderr: any;
-    };
-}> | Failure<ExecuteStepsFailureData> | import("../..").Success<{
+}> | Success<{
     branchName: string;
     contextNames: string[];
     contextRunStateList: ContextRunState[];

package/dist/helpers/executeStepsForContextList/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/executeStepsForContextList/main.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,OAAO,EACP,MAAM,EACN,aAAa,EAMb,aAAa,EAChB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA4BjD,MAAM,MAAM,gCAAgC,CACxC,CAAC,SAAS,aAAa,GAAG,aAAa,EACvC,EAAE,SAAS,aAAa,GAAG,aAAa,IACxC,QAAQ,CAAC,IAAI,CACb,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,EACjB,YAAY,GACZ,UAAU,GACV,eAAe,GACf,OAAO,GACP,SAAS,GACT,YAAY,GACZ,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,aAAa,GACb,kBAAkB,GAClB,qBAAqB,GACrB,0BAA0B,CAC/B,CAAC,GAAG;IACD,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB,CAAA;AAED,wBAAsB,0BAA0B,CAC5C,CAAC,SAAS,aAAa,GAAG,aAAa,EACvC,EAAE,SAAS,aAAa,GAAG,aAAa,EAC1C,EACE,UAAU,EACV,QAAQ,EACR,aAAa,EACb,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,KAAK,EACL,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,GACT,EAAE,gCAAgC,CAAC,CAAC,EAAE,EAAE,CAAC;;;;;;;;;;;IAuUzC;AAED,MAAM,MAAM,gCAAgC,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/executeStepsForContextList/main.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,WAAW,EACX,eAAe,EAEf,OAAO,EACP,MAAM,EACN,aAAa,EAMb,aAAa,EACb,OAAO,EACV,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAuGjD,MAAM,MAAM,gCAAgC,CACxC,CAAC,SAAS,aAAa,GAAG,aAAa,EACvC,EAAE,SAAS,aAAa,GAAG,aAAa,IACxC,QAAQ,CAAC,IAAI,CACb,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,EACjB,YAAY,GACZ,UAAU,GACV,eAAe,GACf,OAAO,GACP,SAAS,GACT,YAAY,GACZ,gBAAgB,GAChB,WAAW,GACX,oBAAoB,GACpB,aAAa,GACb,kBAAkB,GAClB,qBAAqB,GACrB,0BAA0B,CAC/B,CAAC,GAAG;IACD,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB,CAAA;AAED,wBAAsB,0BAA0B,CAC5C,CAAC,SAAS,aAAa,GAAG,aAAa,EACvC,EAAE,SAAS,aAAa,GAAG,aAAa,EAC1C,EACE,UAAU,EACV,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,KAAK,EACL,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,GACT,EAAE,gCAAgC,CAAC,CAAC,EAAE,EAAE,CAAC;;;;;;IA6VzC;AAED,MAAM,MAAM,gCAAgC,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC,CAAC"}

package/dist/helpers/getContextStatus/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/getContextStatus/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAKpE,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAAE,MAAM,EAAE;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwEzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/helpers/getContextStatus/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAUpE,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAAE,MAAM,EAAE;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwEzB"}