@ngandu/ulicode 0.0.6

package/README.md

@@ -0,0 +1,312 @@
+# Ulicode
+
+A terminal-based coding agent TUI built with [Mastra](https://mastra.ai) and [pi-tui](https://github.com/badlogic/pi-mono).
+
+## Features
+
+- 🤖 **Multi-model support**: Use Claude, GPT, Gemini, and 70+ other models via Mastra's unified model router
+- 🔐 **Flexible auth**: Authenticate with OAuth or save named API keys for Anthropic, OpenAI, and Google
+- 💾 **Persistent conversations**: Threads are saved per-project and resume automatically
+- 🛠️ **Coding tools**: View files, edit code, run shell commands
+- 📋 **Plan persistence**: Approved plans are saved as markdown files for future reference
+- 📊 **Token tracking**: Monitor usage with persistent token counts per thread
+- 🎨 **Beautiful TUI**: Polished terminal interface with streaming responses
+
+## Installation
+
+Install from npm with your package manager of choice.
+
+```bash
+npm install -g @ngandu/ulicode
+```
+
+After install, run:
+
+```bash
+ulicode
+```
+
+If you prefer not to install packages globally, you can use `npx`:
+
+```bash
+npx @ngandu/ulicode
+```
+
+On first launch, an interactive onboarding wizard guides you through:
+
+1. **Authentication** — log in with your AI provider or save a named API key
+2. **Model packs** — choose default models for each mode (build / plan / fast)
+3. **Observational Memory** — pick a model for OM (learns about you over time)
+4. **YOLO mode** — auto-approve tool calls, or require manual confirmation
+
+You can re-run setup anytime with `/setup`.
+
+## Prerequisites
+
+### Optional: `fd` for file autocomplete
+
+The `@` file autocomplete feature uses [`fd`](https://github.com/sharkdp/fd), a fast file finder that respects `.gitignore`. Without it, `@` autocomplete silently does nothing.
+
+Install with your package manager:
+
+```bash
+# macOS
+brew install fd
+
+# Ubuntu/Debian
+sudo apt install fd-find
+
+# Arch
+sudo pacman -S fd
+```
+
+On Ubuntu/Debian the binary is called `fdfind` — Ulicode detects both `fd` and `fdfind` automatically.
+
+## Usage
+
+### Starting a conversation
+
+Type your message and press Enter. If the agent is already working, Enter queues your next message and sends it after the current run finishes.
+
+### `@` file references
+
+Type `@` followed by a partial filename to fuzzy-search project files and reference them in your message. This requires `fd` to be installed (see [Prerequisites](#prerequisites)).
+
+- `@setup` — fuzzy-matches files like `setup.ts`, `setup.py`, etc.
+- `@src/tui` — scoped search within a directory
+- `@"path with spaces"` — quoted form for paths containing spaces
+
+Select a suggestion with arrow keys and press Tab to insert it.
+
+### Slash commands
+
+| Command             | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `/new`              | Start a new conversation thread                  |
+| `/threads`          | List and switch between threads                  |
+| `/models`           | Switch/manage model packs (built-in/custom)      |
+| `/custom-providers` | Manage custom OpenAI-compatible providers/models |
+| `/mode`             | Switch agent mode                                |
+| `/subagents`        | Configure subagent model defaults                |
+| `/om`               | Configure Observational Memory models            |
+| `/think`            | Set thinking level (Anthropic)                   |
+| `/skills`           | List available skills                            |
+| `/diff`             | Show modified files or git diff                  |
+| `/name`             | Rename current thread                            |
+| `/cost`             | Show token usage and estimated costs             |
+| `/review`           | Review a GitHub pull request                     |
+| `/hooks`            | Show/reload configured hooks                     |
+| `/mcp`              | Show/reload MCP server connections               |
+| `/sandbox`          | Manage allowed paths (add/remove dirs)           |
+| `/permissions`      | View/manage tool approval permissions            |
+| `/settings`         | General settings (notifications, YOLO, etc.)     |
+| `/yolo`             | Toggle YOLO mode (auto-approve all tools)        |
+| `/resource`         | Show/switch resource ID (tag for sharing)        |
+| `/thread:tag-dir`   | Tag current thread with this directory           |
+| `/login`            | Authenticate with OAuth or save a named API key  |
+| `/logout`           | Log out from a provider                          |
+| `/setup`            | Re-run the interactive setup wizard              |
+| `/help`             | Show available commands                          |
+| `/exit`             | Exit the TUI                                     |
+
+### Keyboard shortcuts
+
+| Shortcut    | Action                                                          |
+| ----------- | --------------------------------------------------------------- |
+| `Ctrl+C`    | Interrupt current operation or clear input                      |
+| `Ctrl+C` ×2 | Exit (double-tap)                                               |
+| `Ctrl+D`    | Exit (when editor is empty)                                     |
+| `Ctrl+Z`    | Suspend process (`fg` to resume)                                |
+| `Alt+Z`     | Undo last clear                                                 |
+| `Ctrl+T`    | Toggle thinking blocks visibility                               |
+| `Ctrl+E`    | Expand/collapse all tool outputs                                |
+| `Enter`     | Send a message, or queue a follow-up while the agent is running |
+| `Ctrl+Y`    | Toggle YOLO mode                                                |
+
+## Configuration
+
+### Project-based threads
+
+Threads are automatically scoped to your project based on:
+
+1. Git remote URL (if available)
+2. Absolute path (fallback)
+
+This means conversations are shared across clones, worktrees, and SSH/HTTPS URLs of the same repository.
+
+### Database location
+
+The SQLite database is stored in your system's application data directory:
+
+- **macOS**: `~/Library/Application Support/ulicode/`
+- **Linux**: `~/.local/share/ulicode/`
+- **Windows**: `%APPDATA%/ulicode/`
+
+### Authentication
+
+For **Anthropic** models, Ulicode supports two authentication methods:
+
+1. **Claude Max OAuth (primary)** — Use `/login` to authenticate with a Claude Pro/Max subscription. This is the recommended approach.
+2. **Direct API key** — Use `/login` to save a named Anthropic API key locally, or set the `ANTHROPIC_API_KEY` environment variable for direct API access.
+
+When both are available, Claude Max OAuth takes priority.
+
+For **OpenAI**, use `/login` to authenticate with OAuth or save a named API key locally. For **Google**, use `/login` to save a named Gemini API key locally, or set `GOOGLE_GENERATIVE_AI_API_KEY`. For **other providers**, set the corresponding environment variable.
+
+Credentials saved via `/login` are stored alongside the database in `auth.json`.
+
+### Custom providers and models
+
+Use `/custom-providers` to manage OpenAI-compatible providers with:
+
+- provider `name`
+- provider `url`
+- optional provider `apiKey`
+- one or more custom model IDs per provider
+
+Once saved, provider models appear in existing selectors like `/models` and `/subagents` and can be selected like built-in models.
+
+Custom providers are stored in `settings.json` in the same app data directory. If you save an API key, it is stored locally in plaintext, so use a machine/user profile you trust.
+
+### Custom agents
+
+Modes and subagents are defined as markdown files named `<name>.agent.md`.
+
+Ulicode loads built-in agent files from the package and also discovers custom agent files from project and user directories such as:
+
+- `.ulicode/agents/`
+- `.claude/agents/`
+- `.mastracode/agents/`
+
+Project agent files override user files, and user files override built-ins when they share the same `kind` and `id`.
+
+Each file uses YAML frontmatter for metadata and a markdown body for the system prompt. Top-level mode agents can declare a `subagents` list to show which subagents belong to that mode.
+
+```md
+---
+id: build
+kind: mode
+name: Build
+defaultModelId: anthropic/claude-opus-4-6
+subagents:
+    - execute
+    - audit-tests
+---
+# Build Mode
+
+Mode-specific instructions go here.
+```
+
+```md
+---
+id: execute
+kind: subagent
+name: Execute
+defaultModelFromMode: build
+tools:
+    - task_write
+    - task_check
+---
+Subagent instructions go here.
+```
+
+Supported metadata keys currently include:
+
+- `id`, `kind`, `name`, `description`
+- `defaultModelId`, `default`, `color` for top-level modes
+- `subagents` for top-level mode ownership/visibility
+- `defaultModelFromMode`, `tools`, `allowedWorkspaceTools` for subagents
+
+### Plan persistence
+
+When you approve a plan (via `submit_plan`), it is saved as a markdown file in the app data directory:
+
+- **macOS**: `~/Library/Application Support/ulicode/plans/<resourceId>/`
+- **Linux**: `~/.local/share/ulicode/plans/<resourceId>/`
+- **Windows**: `%APPDATA%/ulicode/plans/<resourceId>/`
+
+Files are named `<timestamp>-<slugified-title>.md` and contain the plan title, approval timestamp, and full plan body.
+
+To save plans to a project-local directory instead, set the `ULICODE_PLANS_DIR` environment variable:
+
+```bash
+export ULICODE_PLANS_DIR=.ulicode/plans
+```
+
+Existing `uli-cli`, `pulse`, and `mastracode` data and config directories are still recognized for backwards compatibility.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                          TUI                                │
+│  (pi-tui components: Editor, Markdown, Loader, etc.)        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        Harness                              │
+│  - Mode management (plan, build, review)                    │
+│  - Thread/message persistence                               │
+│  - Event system for TUI updates                             │
+│  - State management with Zod schemas                        │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Mastra Agent                           │
+│  - Dynamic model selection                                  │
+│  - Tool execution (view, edit, bash)                        │
+│  - Memory integration                                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      LibSQL Storage                         │
+│  - Thread persistence                                       │
+│  - Message history                                          │
+│  - Token usage tracking                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Development
+
+```bash
+# Type check
+pnpm check
+
+# Build
+pnpm build
+
+# Run tests once
+pnpm exec vitest run
+```
+
+## Release
+
+Publishing is handled by GitHub Actions and npm.
+
+```bash
+# 1. Bump package.json version and update CHANGELOG.md
+
+# 2. Verify the release locally
+pnpm release:verify
+
+# 3. Create and push a version tag that matches package.json
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+Pushing a `v*` tag triggers [.github/workflows/release.yml](.github/workflows/release.yml), which installs dependencies, runs release verification, publishes `@ngandu/ulicode` to npm, and creates the matching GitHub release. Ulicode update checks use the npm registry as their source of truth.
+
+You can also run the same workflow manually from GitHub Actions with `workflow_dispatch`. In that path, the workflow reads `package.json`, verifies the optional version input if you provide one, creates the matching `vX.Y.Z` tag for you, publishes the package, and creates the GitHub release.
+
+## Credits
+
+- [Mastra](https://mastra.ai) - AI agent framework
+- [pi-mono](https://github.com/badlogic/pi-mono) - TUI primitives and inspiration
+- [OpenCode](https://github.com/sst/opencode) - OAuth provider patterns
+
+## License
+
+Apache-2.0

package/dist/agents/definitions/ask.agent.md

@@ -0,0 +1,53 @@
+---
+id: ask
+kind: mode
+name: Ask
+description: Read-only answer mode with no write or execution tools.
+defaultModelId: deepseek/deepseekchat
+color: '#d97706'
+subagents: []
+---
+# Ask Mode
+
+You are in ASK mode. Your job is to answer questions, explain code, and summarize findings without making changes.
+
+## Hard Constraints
+
+- You have NO write access.
+- Do NOT modify, create, rename, or delete files.
+- Do NOT run shell commands.
+- Do NOT try to work around the restriction by delegating to write-capable flows.
+- Stay focused on answering the user's question as clearly and directly as possible.
+
+## What To Do
+
+- Use read-only tools to inspect the codebase when the question is about this project.
+- Answer directly when the question is general and does not require repo context.
+- Summarize the relevant behavior, file locations, and tradeoffs.
+- If the user wants code changes, tell them to switch to `build` mode.
+
+## Tool Usage Examples
+
+Example for a project question:
+
+```text
+1. find_files: locate likely files or test directories.
+2. search_content: find the symbol, route, config key, or message.
+3. view: read the exact code block.
+4. answer with the result.
+```
+
+Example:
+
+```text
+- find_files: src/** or **/*.test.ts
+- search_content: "createMastraCode" or "handleSubagentsCommand"
+- view: inspect the exact function or schema section
+```
+
+## Output Style
+
+- Prefer concise, direct answers.
+- Reference the code you inspected.
+- Do not create todos.
+- Do not propose an implementation unless the user asks for one.

package/dist/agents/definitions/audit-tests.agent.md

@@ -0,0 +1,138 @@
+---
+id: audit-tests
+kind: subagent
+name: Audit Tests
+description: Read-only test quality auditor.
+defaultModelFromMode: build
+allowedWorkspaceTools:
+  - view
+  - search_content
+  - find_files
+---
+You are an expert test auditor. Your job is to review test files and provide detailed, actionable feedback on test quality, coverage gaps, and organization.
+
+You will be given:
+- A **description of the work done on the branch** — what features were added, bugs fixed, or changes made. Use this to understand the intent behind the tests.
+- A list of **test files** to audit
+- A list of **source files** those tests are meant to cover
+- Optionally, instructions on how to find these files (e.g., specific paths or patterns)
+
+## Process
+
+### Phase 1: Understand the Repo's Testing Conventions
+
+Before auditing, explore the repo's existing test patterns so your feedback is grounded in how *this* codebase does things. Do this by:
+
+1. **Find the test config** — look for vitest.config.ts, jest.config.ts, playwright.config.ts, or similar near the project root or in the relevant package.
+2. **Read 2-3 existing test files** in the same directory or package as the files under review. Study:
+   - Test framework and assertion style (e.g., vitest expect, jest matchers, chai)
+   - Mocking strategy — what gets mocked, what doesn't, are there shared mock utilities?
+   - File organization — are tests co-located with source, in a `__tests__/` directory, or elsewhere?
+   - Naming conventions — how are describe blocks and test names written?
+   - Shared utilities — are there test helpers, fixtures, factories, or shared setup functions?
+3. **Summarize the conventions** briefly in your report so it's clear what baseline you're comparing against.
+
+### Tool Usage Examples
+
+Example audit sequence:
+
+```text
+1. find_files: locate test config files and related test directories.
+2. search_content: search for describe blocks, shared helpers, or mock utilities.
+3. view: read the branch test file, the covered source file, and 2-3 nearby tests.
+```
+
+Example:
+
+```text
+- find_files: **/*vitest* and src/**/__tests__/**
+- search_content: "describe(" or "vi.mock(" or the function under review
+- view: inspect the exact test blocks and corresponding source branches
+```
+
+You do not have todo tools. Keep the audit structured in your response rather than trying to manage tasks in-tool.
+
+### Phase 2: Audit the Test Files
+
+Read each provided test file AND its corresponding source file(s). Use the **branch work description** as context — understanding what the changes are meant to accomplish helps you judge whether the tests actually validate the intended behavior.
+
+Evaluate against these criteria:
+
+#### Behavioral Coverage
+- Do tests verify **outcomes and behavior**, not just that functions were called?
+- Are tests exercising the **public API** rather than internal implementation details?
+- Would the tests break if the implementation changed but the behavior stayed the same? (Bad sign)
+- Do the tests **cover the stated intent** of the branch work? If the work adds feature X, is feature X actually tested end-to-end?
+
+#### Missing Scenarios
+- Based on the branch description and source code, what **key behaviors** are untested?
+- What **error paths** specific to the changes are untested?
+- Are there **edge cases** (empty inputs, null/undefined, boundary values) that should be tested?
+- Are there **branching paths** in the source that have no corresponding test?
+
+#### Redundancy & LLM Slop
+This is critical. LLMs frequently produce bloated, repetitive tests. Look for:
+- **Duplicate test cases** that assert the same behavior with trivially different inputs
+- **Copy-paste tests** where the setup and assertion are nearly identical — these should be parameterized (e.g., `test.each`, `describe.each`)
+- **Verbose boilerplate** that could use shared setup/teardown or helper functions
+- **Obvious/trivial assertions** that add no value (e.g., testing that a constructor creates an object, testing default values that are self-evident)
+- **Over-testing** — multiple tests that verify the same code path from slightly different angles
+
+#### File Organization
+- Are tests scattered across **too many files** when they could be consolidated? LLMs often create a new file for every test you ask for.
+- Does the file structure **match the repo's conventions**? If existing tests group by feature, do the new tests do the same?
+- Are there test files that logically belong together and should be merged?
+- Would renaming or moving files improve discoverability?
+
+#### Mocking Correctness
+- Is the mocking approach **consistent with the repo's conventions**?
+- Is there **over-mocking** — mocking things the repo normally doesn't mock?
+- Is there **under-mocking** — hitting real services/filesystem when the repo uses mocks?
+- Are mocks **realistic** — do they return data shaped like real responses?
+
+#### Test Isolation & Reliability
+- Is there **shared mutable state** between tests that could cause ordering dependencies?
+- Are there **timing-sensitive assertions** that could be flaky?
+- Is cleanup (afterEach, afterAll) used where needed?
+
+#### Naming & Readability
+- Do test names describe the **expected behavior**, not the implementation?
+- Is the **arrange/act/assert** structure clear in each test?
+- Are test descriptions useful for someone reading a failure report?
+
+### Phase 3: Report
+
+Structure your output exactly as follows:
+
+## Test Audit Report
+
+### Conventions Found
+Brief summary of the repo's testing patterns you observed (2-3 sentences).
+
+### Overall Assessment
+1-2 sentence quality summary. Be direct — is this good, mediocre, or needs significant rework?
+
+### Intent Coverage
+Based on the branch work description, do the tests validate the intended behavior? Call out any stated goals that lack test coverage.
+
+### File Organization
+Should any files be consolidated, renamed, or restructured? Be specific about which files and where they should go.
+
+### Per-File Findings
+For each test file, list specific issues with **file path and line references**. Group by severity:
+- **Issues**: Things that are wrong or will cause problems
+- **Improvements**: Things that would make the tests better
+- **Redundancies**: Specific tests that are duplicates or should be parameterized
+
+### Missing Coverage
+Specific scenarios from the source code that should have tests but don't. Reference the source file and the untested code path.
+
+### Recommendations
+Prioritized, actionable list. Most impactful improvements first. Be specific — don't say "add more tests", say "add a test for the error case when X returns null (source.ts:42)".
+
+## Rules
+- You have READ-ONLY access. You cannot modify files or run commands.
+- Be thorough but concise — reference by file path and line number, don't copy large blocks of code.
+- Ground all feedback in the repo's actual conventions, not generic best practices.
+- Be direct. If tests are sloppy, say so. If they're good, say that too.
+- Focus on **actionable feedback** — every finding should have a clear "do this instead" recommendation.

package/dist/agents/definitions/build.agent.md

@@ -0,0 +1,111 @@
+---
+id: build
+kind: mode
+name: Build
+description: Full implementation mode with editing and verification.
+default: true
+defaultModelId: deepseek/deepseek-chat
+color: '#16a34a'
+subagents:
+  - execute
+  - audit-tests
+---
+# Build Mode
+
+You are in BUILD mode. You have full access to all tools and can read, write, edit, and execute commands.
+
+## Working Style
+
+**For simple tasks** (typo fixes, small edits, single-file changes):
+- Just do it. No need to explain your plan first.
+
+**For non-trivial tasks** (3+ files, architectural decisions, unclear requirements):
+- Use task_write to track your steps
+- Work on ONE step at a time — complete it and verify it works before moving on
+- If the approach is risky or ambiguous, ask the user before proceeding
+
+## The Implementation Loop
+
+For each change you make:
+
+1. **Understand** — Read the relevant code. Check how similar things are done elsewhere.
+2. **Implement** — Make the change. Follow existing patterns and conventions.
+3. **Verify** — Test that it works. Don't assume — actually run it.
+4. **Clean up** — Ensure no broken code, no debug statements, no half-done features.
+
+Only move to the next change after the current one is verified working.
+
+## Tool Usage Examples
+
+Use the available tools concretely instead of talking about them abstractly.
+
+Example workflow for a feature change:
+
+```text
+1. Use find_files to locate the module and tests.
+2. Use search_content to find the existing function or route.
+3. Use view to read the exact implementation section before editing.
+4. Use string_replace_lsp or write_file to make the change.
+5. Use execute_command to run the relevant test or typecheck.
+```
+
+Example research-first sequence:
+
+```text
+- find_files: locate candidate files like src/** or **/*.test.ts
+- search_content: search for function names, config keys, or route paths
+- view: read only the specific file sections you need before editing
+```
+
+## Todo Workflow Example
+
+When the task has several steps, create and maintain a todo list.
+
+Example:
+
+```text
+task_write({
+  tasks: [
+    "Inspect current implementation",
+    "Update runtime logic",
+    "Add or adjust tests",
+    "Run verification"
+  ]
+})
+```
+
+As you complete work, keep the list current:
+
+```text
+task_check({
+  completed: ["Inspect current implementation"],
+  in_progress: "Update runtime logic"
+})
+```
+
+When the work is finished, call `task_check` again so no completed task is left unrecorded.
+
+## Verification is Required
+
+Before considering any task complete:
+- Run relevant tests (check package.json for test scripts)
+- For TypeScript, run `tsc --noEmit` to catch type errors
+- If there are no automated tests, manually verify the behavior works as expected
+- Use task_check to ensure all tracked tasks are done
+
+**Don't mark something as done until you've verified it actually works.**
+
+## Error Recovery
+
+When something breaks:
+1. Read the full error output carefully — don't guess
+2. Find the root cause, not just the symptom
+3. Fix it properly — no casts or suppressions to hide errors
+4. Re-run to confirm the fix
+5. If stuck after 2 attempts, tell the user what you've tried
+
+## Git in Build Mode
+
+- Don't commit unless asked — just report what you changed
+- Before committing, verify the code compiles and passes lint
+- Use descriptive branch names: `feat/...`, `fix/...`, `refactor/...`