@tarcisiopgs/lisa 1.13.1 → 1.14.0

package/README.md

@@ -86,6 +86,98 @@ Lisa follows a deterministic pipeline:
 
 ---
 
+## Writing Issues
+
+Issue quality is the single biggest factor in PR quality. Lisa validates issues before accepting them — vague tickets without clear criteria are skipped automatically (labelled `needs-spec`). A well-structured issue gives the AI agent everything it needs to deliver a clean implementation on the first try.
+
+### What Lisa looks for
+
+At minimum, the issue description must contain **acceptance criteria**. Lisa detects them by looking for:
+
+- Markdown checklists (`- [ ]`)
+- Keywords: `acceptance criteria`, `expected`, `should`, `deve`, `critérios`
+
+Issues without these are rejected. Beyond validation, the agent also consumes **relevant files**, **technical constraints**, and **stack information** when present in the description — so including them leads to better results.
+
+### Feature
+
+```markdown
+Title: Add rate limiting to /api/users endpoint
+
+Description:
+Implement rate limiting on the `/api/users` endpoint to prevent abuse.
+
+Relevant files:
+- src/routes/users.ts
+- src/middleware/auth.ts
+
+Acceptance criteria:
+- [ ] Requests exceeding 100/min per IP return HTTP 429
+- [ ] Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) included in all responses
+- [ ] Rate limit state stored in Redis (use existing connection from src/lib/redis.ts)
+- [ ] Existing tests still pass
+
+Stack: Express, Redis
+```
+
+### Bug fix
+
+```markdown
+Title: Login redirect loop when session expires
+
+Description:
+Users report being stuck in an infinite redirect loop after their session expires.
+The issue is in the session middleware — it redirects to /login, but /login also
+checks for a valid session and redirects back.
+
+Steps to reproduce:
+1. Log in
+2. Wait for session to expire (or manually clear the session cookie)
+3. Navigate to any protected route
+
+Relevant files:
+- src/middleware/session.ts
+- src/routes/auth.ts
+
+Expected behavior:
+- [ ] Expired sessions redirect to /login without a loop
+- [ ] /login route should not require an active session
+- [ ] After login, user is redirected back to the originally requested page
+```
+
+### Refactor
+
+```markdown
+Title: Extract email sending into a dedicated service
+
+Description:
+Email sending logic is duplicated across 3 controllers. Extract it into a
+shared service.
+
+Relevant files:
+- src/controllers/auth.ts (lines 45-67: welcome email)
+- src/controllers/orders.ts (lines 120-145: order confirmation)
+- src/controllers/support.ts (lines 30-55: ticket confirmation)
+
+Acceptance criteria:
+- [ ] New EmailService class in src/services/email.ts
+- [ ] All 3 controllers use the shared service instead of inline email logic
+- [ ] Existing tests still pass
+- [ ] No new dependencies added
+```
+
+### What makes a good issue
+
+| Do | Don't |
+|---|---|
+| List specific files the agent should read | Say "fix the bug" with no context |
+| Include acceptance criteria as a checklist | Describe the desired outcome vaguely |
+| Mention the stack or libraries to use | Assume the agent knows your preferences |
+| Describe expected behavior for bug fixes | Provide only steps to reproduce |
+| Scope to a single deliverable | Bundle multiple unrelated changes |
+
+---
+
 ## Issue Sources
 
 Lisa integrates with **7 project trackers** out of the box:
@@ -150,14 +242,14 @@ Lisa delivers pull requests and merge requests to **4 platforms**:
 | GitLab | `gitlab` | `GITLAB_TOKEN` | Merge Request |
 | Bitbucket | `bitbucket` | `BITBUCKET_TOKEN` + `BITBUCKET_USERNAME` | Pull Request |
 
-Set `github` in your config (or pass `--github` at runtime) to select the delivery method:
+Set `platform` in your config (or pass `--platform` at runtime) to select the delivery method:
 
 ```yaml
-github: gitlab   # or: cli, token, bitbucket
+platform: gitlab   # or: cli, token, bitbucket
 ```
 
 ```bash
-lisa run --github bitbucket   # override at runtime
+lisa run --platform bitbucket   # override at runtime
 ```
 
 Each platform appends a `🤖 Resolved by lisa` attribution comment to the PR/MR after creation.
@@ -174,9 +266,9 @@ npm install -g @tarcisiopgs/lisa
 
 ```bash
 # PR/MR delivery — set one based on your platform
-export GITHUB_TOKEN=""       # GitHub — or have `gh` CLI authenticated (github: cli or token)
-export GITLAB_TOKEN=""       # GitLab MR creation (github: gitlab)
-export BITBUCKET_TOKEN=""    # Bitbucket PR creation (github: bitbucket)
+export GITHUB_TOKEN=""       # GitHub — or have `gh` CLI authenticated (platform: cli or token)
+export GITLAB_TOKEN=""       # GitLab MR creation (platform: gitlab)
+export BITBUCKET_TOKEN=""    # Bitbucket PR creation (platform: bitbucket)
 export BITBUCKET_USERNAME="" # Bitbucket username (required with BITBUCKET_TOKEN)
 
 # Required when source = linear
@@ -205,10 +297,6 @@ export GITHUB_TOKEN=""     # same token used for PR creation
 export JIRA_BASE_URL=""        # e.g. https://yourcompany.atlassian.net
 export JIRA_EMAIL=""           # Atlassian account email
 export JIRA_API_TOKEN=""       # Atlassian API token
-
-# Optional — anonymous crash reporting (disabled by default)
-export LISA_TELEMETRY=1        # enable anonymous crash/error reporting
-export LISA_NO_TELEMETRY=1     # disable reporting (overrides LISA_TELEMETRY and config)
 ```
 
 ## Commands
@@ -226,8 +314,11 @@ export LISA_NO_TELEMETRY=1     # disable reporting (overrides LISA_TELEMETRY and
 | `lisa run --provider NAME` | Override AI provider |
 | `lisa run --source NAME` | Override issue source |
 | `lisa run --label NAME` | Override label filter |
-| `lisa run --github METHOD` | Override PR platform (`cli`, `token`, `gitlab`, or `bitbucket`) |
+| `lisa run --platform METHOD` | Override PR platform (`cli`, `token`, `gitlab`, or `bitbucket`) |
 | `lisa run --no-bell` | Disable terminal bell on issue completion/failure |
+| `lisa run --lifecycle MODE` | Lifecycle mode: `auto` (default), `skip`, or `validate-only` |
+| `lisa run --lifecycle-timeout N` | Startup timeout per resource in seconds (default: 30) |
+| `lisa run --demo` | Run animated demo with fake issues to preview the TUI |
 | `lisa init` | Create `.lisa/config.yaml` interactively (offers pre-defined templates) |
 | `lisa config` | Edit config interactively |
 | `lisa config --show` | Print current config as JSON |
@@ -253,7 +344,7 @@ When running in an interactive terminal, `lisa run` renders a real-time Kanban b
 └──────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘
 ```
 
-In-progress cards show a live elapsed timer and the last action taken by the provider. A global progress bar in the header tracks overall session progress. When the loop is paused, active cards display a visual pause indicator. The detail view includes a scroll bar when output overflows and shows the active model name in the sidebar.
+In-progress cards show a live elapsed timer and the last action taken by the provider. When the loop is paused, active cards display a visual pause indicator. The detail view includes a scroll bar when output overflows and shows the active model name in the sidebar.
 
 ### Keyboard shortcuts
 
@@ -289,7 +380,7 @@ source_config:
   in_progress: In Progress
   done: In Review
 
-github: cli          # "cli" (gh), "token" (GITHUB_TOKEN), "gitlab" (GITLAB_TOKEN), or "bitbucket" (BITBUCKET_TOKEN)
+platform: cli        # "cli" (gh), "token" (GITHUB_TOKEN), "gitlab" (GITLAB_TOKEN), or "bitbucket" (BITBUCKET_TOKEN)
 workspace: .
 base_branch: main
 
@@ -320,9 +411,10 @@ overseer:
 validation:
   require_acceptance_criteria: true  # skip issues without detectable acceptance criteria (default: true)
 
-# Optional — anonymous crash/error reporting (disabled by default)
-telemetry:
-  enabled: true  # set via `lisa init` prompt or LISA_TELEMETRY=1; override with LISA_NO_TELEMETRY=1
+# Optional — control infrastructure lifecycle
+lifecycle:
+  mode: auto             # "auto" (default), "skip", or "validate-only"
+  timeout: 30            # seconds to wait per resource (default: 30)
 ```
 
 ### Source-Specific Fields
@@ -463,11 +555,24 @@ validation:
   require_acceptance_criteria: false
 ```
 
-> **Note:** The `needs-spec` label must exist in your issue tracker before Lisa can apply it. Create it manually if it does not exist — Lisa will log a warning if the label is missing.
+> **Note:** For Linear, Lisa auto-creates the `needs-spec` label if it does not exist. For other trackers, the label must exist before Lisa can apply it — Lisa will log a warning if it is missing.
 
 ### Infrastructure Auto-Discovery
 
-Lisa auto-discovers Docker Compose services in each repository and starts them before handing control to the agent. If a `docker-compose.yml` / `compose.yml` is present, Lisa reads port mappings and starts the services, waiting for each port to become ready.
+Lisa auto-discovers Docker Compose services and ORM/migration tools in each repository and starts them before handing control to the agent.
+
+**Docker Compose** — If a `docker-compose.yml` / `compose.yml` is present, Lisa reads port mappings and starts the services, waiting for each port to become ready.
+
+**ORM/Migration setup** — Lisa detects and runs migration commands automatically:
+
+| Tool | Commands |
+|------|----------|
+| Prisma | `npx prisma generate`, `npx prisma db push` |
+| Drizzle | `npx drizzle-kit push` |
+| TypeORM | `npx typeorm migration:run` |
+| Sequelize | `npx sequelize-cli db:migrate` |
+
+**Environment files** — If `.env.example` exists but `.env` doesn't, Lisa copies it automatically before starting infrastructure.
 
 **Dynamic port allocation** prevents collisions when multiple Lisa instances run in parallel. Add `port_range` and `port_env_var` to any discovered or manually configured resource:
 
@@ -488,10 +593,45 @@ When `port_range` is set, Lisa scans ports `check_port` through `check_port + po
 
 If no free port is found within the range, Lisa logs a clear error and aborts the session.
 
+**Lifecycle modes** control how Lisa handles infrastructure:
+
+| Mode | Behavior |
+|------|----------|
+| `auto` (default) | Discover, start, and tear down infrastructure automatically |
+| `skip` | Skip all infrastructure management — assume services are already running |
+| `validate-only` | Check that required ports are available but don't start or stop services |
+
 ### Auto-Detection
 
 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`).
 
+### Project Context Analysis
+
+Before building the prompt for the AI agent, Lisa automatically analyzes the project and injects rich context into the prompt:
+
+- **Quality scripts** — detects `lint`, `typecheck`, `check`, `format`, `test`, `build`, `ci` scripts from `package.json`
+- **Test patterns** — discovers test file location (colocated vs separate directory), style (describe/it vs top-level test), mocking libraries (`vi.mock`, `jest.mock`, fixtures), and includes example code from the first test file found
+- **Code tools** — reads configuration from Biome (`biome.json`), ESLint (`.eslintrc.*`, `eslint.config.*`), and Prettier (`.prettierrc.*`, `prettier.config.*`)
+- **Project structure** — generates a tree view of immediate subdirectories and their children
+- **Environment type** — classifies the project as CLI, Mobile (React Native/Flutter), Web, Server, Library, or Unknown
+
+This context is formatted as a `## Project Context` section in the implementation prompt, giving the agent immediate understanding of the codebase conventions without exploration.
+
+### API Client Generator Detection
+
+Lisa detects API client generators in the project and enriches the agent prompt with generation details — input spec location, output directory, and the command to regenerate clients:
+
+| Generator | Config Files |
+|-----------|-------------|
+| Orval | `orval.config.ts/js`, `.orvalrc`, `.orvalrc.json/js/ts` |
+| Kubb | `kubb.config.ts/js/mjs` |
+| hey-api | `openapi-ts.config.ts/js/mjs` |
+| openapi-generator | `openapitools.json`, `.openapi-generator/` |
+| swagger-codegen | `swagger-codegen-config.json` |
+| openapi-typescript | detected from `package.json` dependencies |
+
+When a generator is detected, the agent receives the config file path, whether the spec is a live URL or local file, the output directory, and the `package.json` script (or `npx` command) to run the generator.
+
 ## License
 
 [MIT](LICENSE)

package/dist/chunk-72CYGBT4.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+// src/output/terminal.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var SPINNER_INTERVAL_MS = 80;
+var spinnerTimer = null;
+var spinnerFrame = 0;
+function isTTY() {
+  return process.stdout.isTTY === true;
+}
+function writeOSC(title) {
+  process.stdout.write(`\x1B]0;${title}\x07`);
+}
+function setTitle(title) {
+  if (!isTTY()) return;
+  writeOSC(title);
+}
+function startSpinner(message) {
+  if (!isTTY()) return;
+  stopSpinner();
+  spinnerFrame = 0;
+  writeOSC(`${SPINNER_FRAMES[0]} Lisa \u2014 ${message}`);
+  spinnerTimer = setInterval(() => {
+    spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
+    writeOSC(`${SPINNER_FRAMES[spinnerFrame]} Lisa \u2014 ${message}`);
+  }, SPINNER_INTERVAL_MS);
+}
+function stopSpinner(message) {
+  if (spinnerTimer) {
+    clearInterval(spinnerTimer);
+    spinnerTimer = null;
+  }
+  if (!isTTY()) return;
+  if (message) {
+    writeOSC(message);
+  }
+}
+function notify(count = 1) {
+  if (!isTTY()) return;
+  process.stdout.write("\x07".repeat(count));
+}
+function resetTitle() {
+  if (!isTTY()) return;
+  writeOSC("");
+}
+
+export {
+  setTitle,
+  startSpinner,
+  stopSpinner,
+  notify,
+  resetTitle
+};

package/dist/{chunk-JSRHJYX2.js → chunk-Z6CNJAZF.js}

@@ -1,48 +1,7 @@
 #!/usr/bin/env node
-
-// src/output/terminal.ts
-var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
-var SPINNER_INTERVAL_MS = 80;
-var spinnerTimer = null;
-var spinnerFrame = 0;
-function isTTY() {
-  return process.stdout.isTTY === true;
-}
-function writeOSC(title) {
-  process.stdout.write(`\x1B]0;${title}\x07`);
-}
-function setTitle(title) {
-  if (!isTTY()) return;
-  writeOSC(title);
-}
-function startSpinner(message) {
-  if (!isTTY()) return;
-  stopSpinner();
-  spinnerFrame = 0;
-  writeOSC(`${SPINNER_FRAMES[0]} Lisa \u2014 ${message}`);
-  spinnerTimer = setInterval(() => {
-    spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
-    writeOSC(`${SPINNER_FRAMES[spinnerFrame]} Lisa \u2014 ${message}`);
-  }, SPINNER_INTERVAL_MS);
-}
-function stopSpinner(message) {
-  if (spinnerTimer) {
-    clearInterval(spinnerTimer);
-    spinnerTimer = null;
-  }
-  if (!isTTY()) return;
-  if (message) {
-    writeOSC(message);
-  }
-}
-function notify(count = 1) {
-  if (!isTTY()) return;
-  process.stdout.write("\x07".repeat(count));
-}
-function resetTitle() {
-  if (!isTTY()) return;
-  writeOSC("");
-}
+import {
+  notify
+} from "./chunk-72CYGBT4.js";
 
 // src/ui/state.ts
 import { EventEmitter } from "events";
@@ -639,25 +598,25 @@ async function checkPrMergedByUrl(prUrl) {
   }
   return false;
 }
-function stopMergePolling(issueId) {
-  const interval = activePolls.get(issueId);
+function stopMergePolling(key) {
+  const interval = activePolls.get(key);
   if (interval !== void 0) {
     clearInterval(interval);
-    activePolls.delete(issueId);
+    activePolls.delete(key);
   }
 }
 function startMergePolling(issueId, prUrl) {
-  if (activePolls.has(issueId)) return;
+  if (activePolls.has(prUrl)) return;
   const intervalId = setInterval(() => {
     checkPrMergedByUrl(prUrl).then((merged) => {
       if (merged) {
-        stopMergePolling(issueId);
+        stopMergePolling(prUrl);
         kanbanEmitter.emit("issue:merged", issueId);
       }
     }).catch(() => {
     });
   }, MERGE_POLL_INTERVAL_MS);
-  activePolls.set(issueId, intervalId);
+  activePolls.set(prUrl, intervalId);
 }
 var KanbanEmitter = class extends EventEmitter {
 };
@@ -689,7 +648,10 @@ function useKanbanState(bellEnabled) {
     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", outputLog: "" }];
+        return [
+          ...prev,
+          { id: issue.id, title: issue.title, column: "backlog", prUrls: [], outputLog: "" }
+        ];
       });
     };
     const onStarted = (issueId) => {
@@ -702,20 +664,21 @@ function useKanbanState(bellEnabled) {
             hasError: false,
             skipped: false,
             killed: false,
+            prUrls: [],
             pausedAt: void 0,
             pauseAccumulated: 0
           } : c
         )
       );
     };
-    const onDone = (issueId, prUrl) => {
+    const onDone = (issueId, prUrls) => {
       setCards(
         (prev) => prev.map(
-          (c) => c.id === issueId ? { ...c, column: "done", prUrl, finishedAt: Date.now() } : c
+          (c) => c.id === issueId ? { ...c, column: "done", prUrls, finishedAt: Date.now() } : c
         )
       );
-      if (prUrl) {
-        startMergePolling(issueId, prUrl);
+      for (const url of prUrls) {
+        startMergePolling(issueId, url);
       }
     };
     const onMerged = (issueId) => {
@@ -840,11 +803,6 @@ export {
   ok,
   divider,
   banner,
-  setTitle,
-  startSpinner,
-  stopSpinner,
-  notify,
-  resetTitle,
   GitHubIssuesSource,
   GitLabIssuesSource,
   kanbanEmitter,