@lumpcode/core 0.0.5 → 0.0.6

package/README.md

@@ -1,12 +1,14 @@
 # @lumpcode/core
 
-The core engine of Lumpcode mainly exporting the `runLump` function.
+The core engine of Lumpcode, mainly exporting the `runLump` function.
 
-`runLump` orchestrates prompts across multiple **contexts** — each context is a unit of work (often a file or a logical group of files). Lumpcode scans your codebase, builds a list of contexts, filters out those already completed (each completed context is materialized as exactly one normalized commit on a remote branch), then runs your prompts on the rest, managing git branches and commits and tracking progress via normalized commit messages.
+`runLump` drives one **agent loop** over a context list in a single invocation. Each context is a unit of work (often a file or a logical group of files). Lumpcode scans your codebase, builds a list of contexts, filters out those already completed (each completed context is materialized as exactly one normalized commit on a remote branch), then runs your prompts on the rest, managing git branches and commits and tracking progress via normalized commit messages.
+
+**Agent loop campaigns** (`.lumpcode/lumps/` configs, daemon scheduling, `lump-status`, `clean`) are CLI-only. Core runs one agent loop per `runLump` call; use your own scheduler or the CLI to manage campaigns.
 
 `runLump` is very configurable but comes with sensible default behaviors.
 
-> **Tip:** for a much smoother end-to-end experience — project bootstrap, an isolated working copy, an always-on daemon that calls `runLump` on a schedule, per-lump enable/disable, and built-in lump/context status — use the [Lumpcode CLI](https://lumpcode.com/cli) (based on the core package). It's the recommended way to drive this engine in real projects; this package is for basic usage on small projects.
+> **Important:** `@lumpcode/core` is the engine only. For **agent loop campaign** management (project bootstrap, `.lumpcode/lumps/` configs, background daemon, status, and cleanup), use the [Lumpcode CLI](../apps/cli/README.md) (`npm install -g @lumpcode/cli`).
 
 ## Installation
 
@@ -76,8 +78,8 @@ interface Context {
 }
 ```
 
-- **`priority`** — Lower values are processed first. Defaults to `0`.
-- **`dependsOnContexts`** — An array of context names that must have a `finished` status before this context is eligible to run. If any dependency has not finished yet (`toDo` or `branchPushed`), the context is excluded from the current batch. If a dependency name doesn't exist in the context list at all, the context is also blocked (safe default).
+- `**priority**` — Lower values are processed first. Defaults to `0`.
+- `**dependsOnContexts**` — Context names that must be `finished` before this context is eligible. If any dependency is still `toDo` or `branchPushed`, the context is excluded from the current batch. Core resolves each entry marker commit with your `gitCommitMessageFn`. The [Lumpcode CLI](../apps/cli/README.md) can wire **cross-lump** dependencies between lumps in the same project — see [CLI lump config](../apps/cli/DOCS/lump-config.md#context-ordering-and-cross-lump-dependencies).
 
 ### CodeBasePath
 
@@ -98,13 +100,15 @@ A mutable `Record<string, unknown>` that persists across prompt executions withi
 
 An array of `Step` objects that are executed sequentially for each context. Each `Step` groups the following fields:
 
-| Field | Type | Description |
-|---|---|---|
-| `promptFn` | `PromptFn \| undefined` | Optional. Generates the prompt string from the current context, run state, and variables. When omitted, `commandFn` receives an empty prompt string. |
-| `commandFn` | `CommandFn` | Required. Returns `{ executable, args, env? }` to run a subprocess, or `null` / `undefined` to skip execution while still running `postCommandExecFn`. Optional `env` merges over the parent process environment for that command only. |
-| `stepVariables` | `StepVariables \| undefined` | Optional extra variables passed into `promptFn`, `commandFn`, and `postCommandExecFn`. |
-| `postCommandExecFn` | `PostCommandExecFn \| undefined` | Optional hook called after the command finishes, receiving the command output. |
-| `timeoutMillis` | `number \| undefined` | Maximum time in milliseconds allowed for the command execution. Defaults to `1800000` (30 minutes). |
+
+| Field               | Type                            | Description                                                                                                                                                                                                                             |
+| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `promptFn`          | `PromptFn | undefined`          | Optional. Generates the prompt string from the current context, run state, and variables. When omitted, `commandFn` receives an empty prompt string.                                                                                    |
+| `commandFn`         | `CommandFn`                     | Required. Returns `{ executable, args, env? }` to run a subprocess, or `null` / `undefined` to skip execution while still running `postCommandExecFn`. Optional `env` merges over the parent process environment for that command only. |
+| `stepVariables`     | `StepVariables | undefined`     | Optional extra variables passed into `promptFn`, `commandFn`, and `postCommandExecFn`.                                                                                                                                                  |
+| `postCommandExecFn` | `PostCommandExecFn | undefined` | Optional hook called after the command finishes, receiving the command output.                                                                                                                                                          |
+| `timeoutMillis`     | `number | undefined`            | Maximum time in milliseconds allowed for the command execution. Defaults to `1800000` (30 minutes).                                                                                                                                     |
+
 
 Elements in the array can also be **functions** that return more `Steps` at runtime, enabling dynamic and recursive prompt chains. See [Recursive Steps](#recursive-steps) for details.
 
@@ -118,7 +122,7 @@ Elements in the array can also be **functions** that return more `Steps` at runt
 
 Absolute path to the root of the project Lumpcode will operate on. This directory is scanned to build the list of `CodeBasePath` entries.
 
-We recommend pointing `projectRoot` to a **separate copy** of your project rather than the directory you are manually working in, so that Lumpcode's git operations don't interfere with your own work. Where prompts and git commands actually run is determined by [`setupWorkspaceFn`](#setupworkspacefn) (see `workspacePath` there). The [Lumpcode CLI](https://lumpcode.com/cli) handles this isolated copy for you.
+We recommend pointing `projectRoot` to a **separate copy** of your project rather than the directory you are manually working in, so that Lumpcode's git operations don't interfere with your own work. Where prompts and git commands actually run is determined by `[setupWorkspaceFn](#setupworkspacefn)` (see `workspacePath` there). The [Lumpcode CLI](../apps/cli/README.md) handles this isolated copy for you.
 
 #### `baseBranch`
 
@@ -181,7 +185,7 @@ See [Logging](#logging) below.
 
 When this function returns a non-empty path for a context, the engine appends one JSON object per prompt step (after each successful agent command) to that file. The file is a JSON array; each element has the same shape as `postCommandExecFn` input (`commandResult`, `context`, `prompt`, `stepIndex`, `contextRunState`, `lumpVariables`, optional `stepVariables`, `projectRoot`). Parent directories are created with `mkdir(..., { recursive: true })` before the initial `[]` write.
 
-The Lumpcode CLI sets this from lump config **`keepHistory: true`**, writing to `.lumpcode/lumps/<lumpName>/history/<contextName>.json`. Library callers can supply a custom function for other paths or naming.
+The Lumpcode CLI sets this from lump config `**keepHistory: true`**, writing to `.lumpcode/lumps/<lumpName>/history/<contextName>.json`. Library callers can supply a custom function for other paths or naming.
 
 ## Advanced Parameters
 
@@ -226,7 +230,7 @@ Called after each context finishes. Use it for cleanup or logging.
 
 ### `gitCommitMessageFn`
 
-**Type:** `GitCommitMessageFn` -- **Default:** `` `LUMP:${context.name}` ``
+**Type:** `GitCommitMessageFn` -- **Default:** ``LUMP:${context.name}``
 
 ```typescript
 type GitCommitMessageFn = (input: {
@@ -246,13 +250,13 @@ Customize the git add command. Receives `{ baseBranch, branchName, contextList,
 
 ### `gitCommitCommandFn`
 
-**Type:** `GitCommitCommandFn` -- **Default:** `` `git commit -m "${commitMessage}"` ``
+**Type:** `GitCommitCommandFn` -- **Default:** ``git commit -m "${commitMessage}"``
 
 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.
 
 ### `gitPushCommandFn`
 
-**Type:** `GitPushCommandFn` -- **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.
 
@@ -288,7 +292,7 @@ Cleans up the workspace after all contexts on a branch are done. The default swi
 
 ## Logging
 
-Operational runtime output uses a small shared **`Logger`** type exported from `@lumpcode/core`:
+Operational runtime output uses a small shared `**Logger`** type exported from `@lumpcode/core`:
 
 ```typescript
 type Logger = {
@@ -300,11 +304,11 @@ type Logger = {
 };
 ```
 
-- **`createConsoleLogger({ verbose?, json?, prefix? })`** — console-backed implementation (`error` always prints; `verbose` gated by `verbose`; when `json: true`, non-error levels are suppressed).
-- **`noopLogger`** — no-op logger for tests.
-- **`formatExecFailureMessage({ label, failure })`** — user-facing shell/git failure strings.
+- `**createConsoleLogger({ verbose?, json?, prefix? })**` — console-backed implementation (`error` always prints; `verbose` gated by `verbose`; when `json: true`, non-error levels are suppressed).
+- `**noopLogger**` — no-op logger for tests.
+- `**formatExecFailureMessage({ label, failure })**` — user-facing shell/git failure strings.
 
-Pass **`logger`** on `RunLumpInput`. When omitted, the engine uses `createConsoleLogger({})` (operational errors/warnings/progress only; no verbose detail unless the logger you pass enables it).
+Pass `**logger**` on `RunLumpInput`. When omitted, the engine uses `createConsoleLogger({})` (operational errors/warnings/progress only; no verbose detail unless the logger you pass enables it).
 
 ## Return Value
 
@@ -414,7 +418,7 @@ const steps: Steps = [
 
 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.
 
-> If you'd rather not wire up your own scheduler, the [Lumpcode CLI](https://lumpcode.com/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.
+> If you'd rather not wire up your own scheduler, the [Lumpcode CLI](../apps/cli/README.md) 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.
 
 ### Commit message naming
 
@@ -424,17 +428,21 @@ 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 subject **must be unique per context** -- it is the only thing tying the commit back to its context.
 
 ### Context statuses
 
+CLI users: marker format is `LUMP: <lumpName> - <contextName>` — see [concepts.md](../apps/cli/DOCS/concepts.md).
+
 When filtering contexts, Lumpcode resolves each context's normalized commit message to one of three statuses:
 
-| Status | Meaning | Effect |
-|---|---|---|
-| `toDo` | No commit with the context's normalized message exists on any remote ref. | Will be processed (unless blocked by `dependsOnContexts`). |
-| `branchPushed` | A commit with the context's normalized message exists on a remote branch other than the base branch. | Skipped. |
-| `finished` | A commit with the context's normalized message is reachable from `origin/<baseBranch>`. | Skipped. |
+
+| Status         | Meaning                                                                                              | Effect                                                     |
+| -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `toDo`         | No commit with the context's normalized message exists on any remote ref.                            | Will be processed (unless blocked by `dependsOnContexts`). |
+| `branchPushed` | A commit with the context's normalized message exists on a remote branch other than the base branch. | Skipped.                                                   |
+| `finished`     | A commit with the context's normalized message is reachable from `origin/<baseBranch>`.              | Skipped.                                                   |
+
 
 A context with `dependsOnContexts` is only eligible when **all** of its listed dependencies have the `finished` status. This means the dependency's commit must be reachable from the remote base branch. Contexts stuck at `branchPushed` do not satisfy the dependency.
 
@@ -504,6 +512,5 @@ flowchart TD
     TeardownWorkspace --> Done["Return Success or Failure"]
 ```
 
-## Going further
 
-`@lumpcode/core` is the engine. The [Lumpcode CLI](https://lumpcode.com/cli) wraps it with everything you'd otherwise have to build yourself: project bootstrap, a managed working copy isolated from your IDE, a background daemon, status/cleanup commands, authentication, and a single-binary distribution. Reach for it whenever you want the full experience.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lumpcode/core",
-  "version": "0.0.5",
-  "description": "Core engine for Lumpcode — programmatic batch coding workflows over contexts using git for tracking",
+  "version": "0.0.6",
+  "description": "Core engine for Lumpcode agent loops — runLump orchestrates prompts across contexts with git-tracked progress",
   "license": "Apache-2.0",
   "author": "",
   "type": "module",