npm - @tarcisiopgs/lisa - Versions diffs - 1.5.0 → 1.6.0 - Mend

@tarcisiopgs/lisa 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,91 +1,77 @@
 # Lisa
 <p align="center">
-  <img src="src/assets/lisa.png" width="200" alt="Lisa" />
+  <img src="assets/lisa.png" width="200" alt="Lisa" />
 </p>
-While the Ralphs of the world flooded GitHub with mindless agent loops — brute-forcing their way through issues with no context, no workflow awareness, and no regard for the mess they leave behind — Lisa takes a different approach. She reads the issue, understands the workspace, picks the right repo, creates the branch, validates her work, and opens the PR. Then she moves on to the next one. When there's nothing left to do, she stops.
-Named after the smartest Simpson, Lisa is an autonomous issue resolver that connects your project tracker (Linear or Trello) to an AI coding agent (Claude Code, Gemini CLI, or OpenCode) and delivers pull requests via GitHub. No MCP servers. No prompt chains. No blind retries. Just structured, end-to-end execution.
-## Why Lisa?
+<p align="center">
+  <strong>Label an issue. Walk away. Come back to a PR.</strong>
+</p>
-Most AI agent loops work like Ralph — they grab an issue, throw it at a model, and hope for the best. If it fails, retry. If there's nothing to do, keep polling. Every cycle burns tokens, every retry burns money, and you get no visibility into what went wrong.
+<p align="center">
+  Lisa is an autonomous issue resolver that turns your backlog into pull requests — no babysitting required.
+</p>
-Lisa is deterministic. She follows a structured pipeline with clear stages (fetch, activate, implement, validate, PR, update) and stops when the work is done. This means:
+---
-- **Token efficiency** — Each issue gets one focused prompt with full context. No wasted retries, no speculative exploration, no idle polling.
-- **Multi-repo awareness** — Lisa plans across multiple repos, executes in the correct order (e.g., backend before frontend), and creates one PR per repo.
-- **Model fallback** — Configure a chain of models (`claude → gemini → opencode`). Transient errors (429, quota, timeout) trigger the next model; non-transient errors stop the chain.
-- **Workflow integration** — Issues move through your board in real time (Backlog → In Progress → In Review). Your team always knows what's being worked on.
-- **Self-healing** — Orphan issues (stuck in "In Progress" from interrupted runs) are automatically recovered on startup. Pre-push hook failures trigger the agent to fix and retry.
-- **Guardrails** — Past failures are logged and injected into future prompts so the agent avoids repeating mistakes.
+<!-- Add a GIF or screen recording of the full pipeline here (fetch → implement → PR) -->
-## Install
+## Quickstart
 ```bash
 npm install -g @tarcisiopgs/lisa
+lisa init
+lisa run
 ```
-## Environment Variables
-```bash
-# Required (at least one)
-export GITHUB_TOKEN=""    # or have `gh` CLI authenticated
-# Required when source = linear
-export LINEAR_API_KEY=""
+That's it. Lisa picks up the next labeled issue, implements it, pushes a branch, opens a pull request, and moves the ticket to "In Review" — all without you touching it.
-# Required when source = trello
-export TRELLO_API_KEY=""
-export TRELLO_TOKEN=""
-```
+## Try it safely first
-## Quick Start
+Before letting Lisa touch real issues, verify your configuration with `--dry-run`. No issues will be fetched, no code will be written, no PRs will be created.
 ```bash
-# Interactive setup
-lisa init
+lisa run --once --dry-run
+```
-# Run continuously until all labeled issues are done
-lisa run
+Example output:
-# Single issue
-lisa run --once
+```
+[dry-run] Would fetch issue from linear (Engineering/Web App)
+[dry-run] Workflow mode: worktree
+[dry-run] Models priority: claude/claude-sonnet-4-6
+[dry-run] Then implement, push, create PR, and update issue status
+```
-# Specific issue by identifier or URL
-lisa run --issue INT-150
+If the output looks correct, you're ready to run Lisa for real.
-# Process up to N issues
-lisa run --limit 5
+## What Lisa Does
-# Preview without executing
-lisa run --dry-run
+Lisa follows a deterministic pipeline:
-# Override provider for a single run
-lisa run --provider gemini --once
+```
+┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐    ┌────┐    ┌────────┐
+│  Fetch   │───▶│ Activate │───▶│ Implement │───▶│ Validate │───▶│ PR │───▶│ Update │
+└─────────┘    └──────────┘    └───────────┘    └──────────┘    └────┘    └────────┘
 ```
-## Commands
+1. **Fetch** — Pulls the next issue from Linear, Trello, Plane, Shortcut, GitLab Issues, GitHub Issues, or Jira matching the configured label, team, and project. Issues are sorted by priority. Blocked issues are skipped.
+2. **Activate** — Moves the issue to `in_progress` so your team knows it's being worked on.
+3. **Implement** — Builds a structured prompt with full issue context and sends it to the AI agent. The agent works in a worktree or branch, implements the change, and commits.
+4. **Validate** — Runs the project's test suite. If tests fail, the session is aborted and the issue reverts.
+5. **PR** — Pushes the branch and creates a pull request referencing the original issue. If pre-push hooks fail, Lisa re-invokes the agent to fix the errors and retries.
+6. **Update** — Moves the issue to the `done` status and removes the pickup label.
+7. **Next** — Picks the next issue. When there are no more matching issues, Lisa stops.
-| Command | Description |
-|---------|-------------|
-| `lisa run` | Run the agent loop |
-| `lisa run --once` | Process a single issue |
-| `lisa run --issue ID` | Process a specific issue by identifier or URL |
-| `lisa run --limit N` | Process up to N issues |
-| `lisa run --dry-run` | Preview without executing |
-| `lisa run --provider NAME` | Override AI provider |
-| `lisa run --source NAME` | Override issue source (linear, trello) |
-| `lisa run --label NAME` | Override label filter |
-| `lisa run --github METHOD` | Override GitHub method (cli, token) |
-| `lisa run --json` | Output as JSON lines |
-| `lisa run --quiet` | Suppress non-essential output |
-| `lisa config` | Interactive config wizard |
-| `lisa config --show` | Show current config |
-| `lisa config --set key=value` | Set a config value |
-| `lisa init` | Create `.lisa/config.yaml` |
-| `lisa status` | Show session stats |
+### What makes it different
+- **Deterministic, not hopeful** — Each issue follows a structured pipeline with clear stages. No blind retries, no speculative loops.
+- **Token efficiency** — Each issue gets one focused prompt. No wasted retries, no idle polling.
+- **Multi-repo awareness** — Plans across multiple repos, executes in the correct order, creates one PR per repo.
+- **Model fallback** — Configure a chain of models. Transient errors (429, quota, timeout) trigger the next model automatically.
+- **Workflow integration** — Issues move through your board in real time. Your team always knows what's being worked on.
+- **Self-healing** — Orphan issues stuck in "In Progress" are recovered on startup. Pre-push failures trigger the agent to fix and retry.
+- **Guardrails** — Past failures are logged and injected into future prompts so the agent avoids repeating mistakes.
 ## Providers
@@ -94,14 +80,16 @@ lisa run --provider gemini --once
 | Claude Code | `claude` | `--dangerously-skip-permissions` |
 | Gemini CLI | `gemini` | `--yolo` |
 | OpenCode | `opencode` | implicit in `run` |
+| GitHub Copilot CLI | `copilot` | `--allow-all` |
+| Cursor Agent | `agent` | `--force` |
+| Goose | `goose` | implicit in `run` |
+| Aider | `aider` | `--yes-always` |
 At least one provider must be installed and available in your PATH.
-All providers use `child_process.spawn` with `sh -c`. Prompts are written to a temp file and passed via `$(cat file)` to avoid argument length limits. Output streams to both stdout and the session log file in real time.
 ### Fallback Chain
-Configure a fallback chain in the `models` array. Lisa tries each model in order — transient errors (429, quota, timeout, network) trigger the next model. Non-transient errors stop the chain immediately.
+Configure multiple models — Lisa tries each in order. Transient errors (429, quota, timeout, network) trigger the next model; non-transient errors stop the chain.
 ```yaml
 provider: claude
@@ -111,26 +99,67 @@ models:
   - claude-haiku-4-5    # fallback 2
 ```
-If `models` is not set, Lisa uses the provider's default model.
+## Install
+```bash
+npm install -g @tarcisiopgs/lisa
+```
+## Environment Variables
+```bash
+# Required (at least one)
+export GITHUB_TOKEN=""    # or have `gh` CLI authenticated
-## Workflow Modes
+# Required when source = linear
+export LINEAR_API_KEY=""
-### Branch
+# Required when source = trello
+export TRELLO_API_KEY=""
+export TRELLO_TOKEN=""
-The AI agent creates a branch directly in your current checkout, implements the changes, and pushes. Simple setup, works everywhere.
+# Required when source = plane
+export PLANE_API_TOKEN=""
+export PLANE_BASE_URL=""  # optional; defaults to https://api.plane.so
+export PLANE_WORKSPACE="" # optional; fallback when team is not set in config
-### Worktree
+# Required when source = shortcut
+export SHORTCUT_API_TOKEN=""
-Lisa creates an isolated [git worktree](https://git-scm.com/docs/git-worktree) for each issue under `.worktrees/`. The agent works inside the worktree without touching your main checkout. After the PR is created, the worktree is cleaned up automatically.
+# Required when source = gitlab-issues
+export GITLAB_TOKEN=""
+export GITLAB_BASE_URL=""  # optional; defaults to https://gitlab.com
-**Native worktree support** — When using Claude Code, Lisa delegates worktree lifecycle directly to the provider via the `--worktree` flag. Lisa auto-detects whether the primary provider supports native worktrees and uses the appropriate mode. Other providers use Lisa-managed worktrees.
+# Required when source = github-issues
+export GITHUB_TOKEN=""     # same token used for PR creation
-**Multi-repo workspaces** — When multiple repos are configured, Lisa uses a two-phase flow:
+# Required when source = jira
+export JIRA_BASE_URL=""        # e.g. https://yourcompany.atlassian.net
+export JIRA_EMAIL=""           # Atlassian account email
+export JIRA_API_TOKEN=""       # Atlassian API token
+```
-1. **Planning phase** — A planning agent analyzes the issue and produces a `.lisa-plan.json` with ordered steps (one per affected repo), determining which repos need changes and in what order (e.g., backend API before frontend consumer).
-2. **Execution phase** — Lisa executes each step sequentially, creating one worktree and one PR per repo. Cross-repo context (branch names, PR URLs from previous steps) is passed to each subsequent step so the agent can reference them.
+## Commands
-Worktree mode is ideal when you want to keep working in the repo while Lisa resolves issues in the background.
+| Command | Description |
+|---------|-------------|
+| `lisa run` | Run the agent loop |
+| `lisa run --once` | Process a single issue |
+| `lisa run --once --dry-run` | **Recommended first step** — preview config without executing |
+| `lisa run --issue ID` | Process a specific issue by identifier or URL |
+| `lisa run --limit N` | Process up to N issues |
+| `lisa run --dry-run` | Preview without executing |
+| `lisa run --provider NAME` | Override AI provider |
+| `lisa run --source NAME` | Override issue source (linear, trello, plane, shortcut, gitlab-issues, github-issues, jira) |
+| `lisa run --label NAME` | Override label filter |
+| `lisa run --github METHOD` | Override GitHub method (cli, token) |
+| `lisa run --json` | Output as JSON lines |
+| `lisa run --quiet` | Suppress non-essential output |
+| `lisa config` | Interactive config wizard |
+| `lisa config --show` | Show current config |
+| `lisa config --set key=value` | Set a config value |
+| `lisa init` | Create `.lisa/config.yaml` |
+| `lisa status` | Show session stats |
 ## Configuration
@@ -179,14 +208,80 @@ overseer:
 ### Source-Specific Fields
-| Field | Linear | Trello |
-|-------|--------|--------|
-| `team` | Team name | Board name |
-| `project` | Project name | — |
-| `pick_from` | Status to pick issues from | List to pick cards from |
-| `label` | Label to filter issues | Label to filter cards |
-| `in_progress` | In-progress status | In-progress column |
-| `done` | Destination status after PR | Destination column after PR |
+| Field | Linear | Trello | Plane | Shortcut | GitLab Issues | GitHub Issues | Jira |
+|-------|--------|--------|-------|----------|---------------|---------------|------|
+| `team` | Team name | Board name | Workspace slug | Group name (optional) | Project path (`namespace/project`) or numeric ID | `owner/repo` | Project key (e.g. `ENG`) |
+| `project` | Project name | — | Project identifier or UUID | — | — | — | — |
+| `pick_from` | Status to pick issues from | List to pick cards from | State name to pick issues from | Workflow state to pick stories from | — | — | Status to pick issues from |
+| `label` | Label to filter issues | Label to filter cards | Label to filter issues | Label to filter stories | Label to filter issues | Label to filter issues | Label to filter issues |
+| `in_progress` | In-progress status | In-progress column | In-progress state name | In-progress workflow state | Label to apply on activate | Label to apply on activate | In-progress status name |
+| `done` | Destination status after PR | Destination column after PR | Done state name | Done workflow state | Closes the issue | Closes the issue | Destination status after PR |
+Plane example:
+```yaml
+source: plane
+source_config:
+  team: my-workspace       # workspace slug (or set PLANE_WORKSPACE env var)
+  project: DEV             # project identifier or UUID
+  label: ready             # issues with this label are picked up
+  pick_from: Todo          # state to fetch issues from
+  in_progress: In Progress # state set when Lisa starts working
+  done: Done               # state set after PR is created
+```
+Shortcut example:
+```yaml
+source: shortcut
+source_config:
+  label: ready              # stories with this label are picked up
+  pick_from: Ready for Development  # workflow state to fetch stories from
+  in_progress: In Progress  # state set when Lisa starts working
+  done: Done                # state set after PR is created
+```
+GitLab Issues example:
+```yaml
+source: gitlab-issues
+source_config:
+  team: my-org/my-repo     # namespace/project path or numeric project ID
+  label: ready              # issues with this label are picked up
+  in_progress: in-progress  # label applied when Lisa starts working
+  done: ""                  # issue is closed after PR (value unused)
+```
+GitHub Issues example:
+```yaml
+source: github-issues
+source_config:
+  team: my-org/my-repo     # owner/repo
+  label: ready              # issues with this label are picked up
+  in_progress: in-progress  # label applied when Lisa starts working
+  done: ""                  # issue is closed after PR (value unused)
+```
+Jira example:
+```yaml
+source: jira
+source_config:
+  team: ENG                # Jira project key
+  label: lisa              # label to filter issues
+  pick_from: Backlog       # status to pick issues from
+  in_progress: In Progress # status applied when Lisa starts working
+  done: In Review          # status applied after PR is created
+```
+### Workflow Modes
+**Branch** — The AI agent creates a branch directly in your current checkout, implements the changes, and pushes. Simple setup, works everywhere.
+**Worktree** — Lisa creates an isolated [git worktree](https://git-scm.com/docs/git-worktree) for each issue under `.worktrees/`. The agent works in the worktree without touching your main checkout. After the PR is created, the worktree is cleaned up automatically. Ideal when you want to keep working in the repo while Lisa resolves issues in the background.
+**Multi-repo worktree** — When multiple repos are configured, Lisa runs a two-phase flow: a planning agent produces a `.lisa-plan.json` with ordered steps, then Lisa executes each step sequentially — one worktree and one PR per repo. Cross-repo context (branch names, PR URLs) is passed to each subsequent step.
 ### Lifecycle Resources
@@ -209,46 +304,22 @@ repos:
         - "npx prisma db push"
 ```
-Lisa starts resources before the agent runs, waits for the port to be ready, runs setup commands, then stops everything after the session. In multi-repo workflows, resources are started and stopped per repo step.
-## How It Works
-```
-┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐    ┌────┐    ┌────────┐
-│  Fetch   │───▶│ Activate │───▶│ Implement │───▶│ Validate │───▶│ PR │───▶│ Update │
-└─────────┘    └──────────┘    └───────────┘    └──────────┘    └────┘    └────────┘
-```
-1. **Fetch** — Pulls the next issue from Linear or Trello matching the configured label, team, and project. Issues are sorted by priority. Blocked issues (with unresolved dependencies) are skipped.
-2. **Activate** — Moves the issue to `in_progress` so your team knows it's being worked on.
-3. **Implement** — Builds a structured prompt with full issue context and sends it to the AI agent. The agent works in a worktree or branch, implements the change, runs validation, and commits.
-4. **Validate** — Runs the project's test suite. If tests fail, the session is aborted and the issue reverts.
-5. **PR** — Pushes the branch and creates a pull request referencing the original issue. If pre-push hooks fail, Lisa re-invokes the agent to fix the errors and retries (up to 2 recovery attempts).
-6. **Update** — Moves the issue to the `done` status and removes the pickup label in a single atomic operation.
-7. **Next** — Picks the next issue. When there are no more matching issues, Lisa stops.
+Lisa starts resources before the agent runs, waits for the port to be ready, runs setup commands, then stops everything after the session.
 ### Recovery Mechanisms
-- **Orphan recovery** — On startup, Lisa scans for issues stuck in `in_progress` from previous interrupted runs and reverts them to `pick_from`.
+- **Orphan recovery** — On startup, Lisa scans for issues stuck in `in_progress` from interrupted runs and reverts them to `pick_from`.
 - **Push recovery** — If `git push` fails due to pre-push hooks (linter, typecheck, tests), Lisa re-invokes the agent with the error output and retries the push.
 - **Signal handling** — SIGINT/SIGTERM gracefully revert the active issue to its previous status before exiting.
 - **Guardrails** — Failed sessions are logged to `.lisa/guardrails.md` and injected into future prompts so the agent avoids repeating the same mistakes.
 ### Overseer
-Lisa can detect stuck providers — agents that appear to be running but are making no progress. When enabled, the overseer periodically checks `git status` in the working directory. If no changes are detected within the `stuck_threshold`, the provider process is killed and the error is eligible for fallback to the next model in the chain.
-### Test Runner and Package Manager Auto-Detection
-Lisa auto-detects `vitest` or `jest` in the project's `package.json` dependencies. It also detects the package manager from lockfiles (`bun.lockb`/`bun.lock` → `bun`, `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, otherwise `npm`). When a test runner is found, mandatory test instructions are injected into the agent prompt with the correct test command (e.g., `bun run test`, `pnpm run test`).
-### PR Body Formatting
-Agent-produced PR descriptions are automatically sanitized before creating the pull request: HTML tags are stripped, `*` bullets are normalized to `-`, and wall-of-text (single-line) descriptions are split into bullet points at sentence boundaries. Agents are also instructed to follow a structured markdown template (What / Why / Key changes / Testing).
+When enabled, the overseer periodically checks `git status` in the working directory. If no changes are detected within `stuck_threshold` seconds, the provider process is killed and the error is eligible for fallback to the next model.
-### Terminal Integration
+### Auto-Detection
-Lisa updates the terminal title to reflect the current activity (fetching, implementing, pushing, cooling down) and plays a bell notification when a session completes. This works in any terminal that supports OSC title sequences.
+Lisa auto-detects `vitest` or `jest` from `package.json` dependencies and injects the correct test command into the agent prompt. It also detects the package manager from lockfiles (`bun.lockb`/`bun.lock` → `bun`, `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, otherwise `npm`).
 ## License

package/dist/chunk-KAME5MG7.js ADDED Viewed

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// src/ui/state.ts
+import { EventEmitter } from "events";
+import { useEffect, useState } from "react";
+var KanbanEmitter = class extends EventEmitter {
+};
+var kanbanEmitter = new KanbanEmitter();
+function useKanbanState() {
+  const [cards, setCards] = useState([]);
+  useEffect(() => {
+    const onQueued = (issue) => {
+      setCards((prev) => {
+        if (prev.some((c) => c.id === issue.id)) return prev;
+        return [...prev, { id: issue.id, title: issue.title, column: "backlog" }];
+      });
+    };
+    const onStarted = (issueId) => {
+      setCards(
+        (prev) => prev.map(
+          (c) => c.id === issueId ? { ...c, column: "in_progress", startedAt: Date.now(), hasError: false } : c
+        )
+      );
+    };
+    const onDone = (issueId, prUrl) => {
+      setCards(
+        (prev) => prev.map((c) => c.id === issueId ? { ...c, column: "done", prUrl } : c)
+      );
+    };
+    const onReverted = (issueId) => {
+      setCards(
+        (prev) => prev.map(
+          (c) => c.id === issueId ? { ...c, column: "backlog", startedAt: void 0, hasError: true } : c
+        )
+      );
+    };
+    kanbanEmitter.on("issue:queued", onQueued);
+    kanbanEmitter.on("issue:started", onStarted);
+    kanbanEmitter.on("issue:done", onDone);
+    kanbanEmitter.on("issue:reverted", onReverted);
+    return () => {
+      kanbanEmitter.off("issue:queued", onQueued);
+      kanbanEmitter.off("issue:started", onStarted);
+      kanbanEmitter.off("issue:done", onDone);
+      kanbanEmitter.off("issue:reverted", onReverted);
+    };
+  }, []);
+  return { cards };
+}
+export {
+  kanbanEmitter,
+  useKanbanState
+};