@papert-code/papert-code 0.2.5 → 0.3.1

package/LICENSE

@@ -188,7 +188,7 @@
       identification within third-party archives.
 
   Copyright 2025 Google LLC
-  Copyright 2025 Papert
+  Copyright 2025 Qwen
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,302 +1,197 @@
 # Papert Code
 
-Papert Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) ([details](./README.gemini.md)), It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.
+Papert Code is a terminal-native AI coding companion that automates everyday developer workflows. It reads, edits, and generates code across large repositories, automates shell tasks with safety rails, and exposes the same capabilities through a TypeScript SDK and a VS Code companion extension.
 
-## Key Features
+- Terminal-first agent with `papert`, built for high-signal, multi-turn coding sessions.
+- Codebase-aware tools: reads and edits files, runs ripgrep queries, executes shell commands, and respects `.gitignore` + `.papertignore`.
+- Safety and control: structured plans, explicit approval modes (`plan`, `default`, `auto-edit`, `yolo`), and sandbox support (Seatbelt/macOS, Docker, Podman).
+- Extensible platform: user commands, subagents, Model Context Protocol (MCP) servers, and a TypeScript SDK for embedding Papert Code into your own apps.
+- Works with any OpenAI-compatible API; pick your own model, base URL, and keys.
 
-- **Code Understanding & Editing** - Query and edit large codebases beyond traditional context window limits
-- **Workflow Automation** - Automate operational tasks like handling pull requests and complex rebases
-- **Enhanced Parser** - Adapted parser specifically optimized for Papert-Coder models
-- **Vision Model Support** - Automatically detect images in your input and seamlessly switch to vision-capable models for multimodal analysis
+## Repository layout
 
-## Programmatic API (Alpha)
-
-Embed the full Papert Code CLI toolchain directly inside another Node.js or
-TypeScript process—no subprocess management required. Install the CLI as a
-dependency and import the new API entry point:
-
-```bash
-npm install
-```
-
-```ts
-import { createPapertAgent } from '@papert-code/papert-code/api';
-
-const agent = await createPapertAgent({
-  cliArgs: {
-    model: 'gemini-3-pro',
-    approvalMode: 'auto_edit',
-  },
-});
-
-await agent.runPrompt('Summarize outstanding TODOs');
-```
-
-The agent shares settings, MCP configuration, and auth flows with the CLI (for
-example `~/.papert/settings.json`, `OPENAI_API_KEY`, or Papert OAuth tokens). Use
-`createProgrammaticCliArgs` to mimic CLI flags in code, and see
-[`docs/cli/programmatic-agent.md`](./docs/cli/programmatic-agent.md) plus the
-[`examples/programmatic-agent`](./examples/programmatic-agent) sample for a
-complete walkthrough.
-
-## Release (npm)
-
-- Bump versions across workspace (root, core, cli, vscode companion as needed) to the target (e.g. 0.2.5).
-- Install deps and run checks: `pnpm install && pnpm lint && pnpm test --filter core && pnpm build`.
-- Publish core and CLI from repo root: `pnpm publish --filter @papert-code/papert-code-core --access public` then `pnpm publish --filter @papert-code/papert-code --access public`.
-- Verify: `npm view @papert-code/papert-code version` (and core) shows the new version; optionally smoke-test `pnpm dlx @papert-code/papert-code@<version> --help`.
+- `packages/cli` — the Papert Code CLI (interactive TUI, tools, settings, sandbox integration).
+- `packages/core` — core tool implementations, MCP plumbing, and shared services.
+- `packages/sdk-typescript` — programmatic access to Papert Code (streaming queries + full CLI runner).
+- `packages/test-utils` — helpers for integration/terminal tests.
+- `packages/vscode-ide-companion` — VS Code extension that mirrors the CLI features inside the editor.
+- `docs/` — user and contributor documentation.
 
 ## Installation
 
 ### Prerequisites
 
-Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed.
+- Node.js **>= 20**
+
+### Install from npm
 
 ```bash
-curl -qL https://www.npmjs.com/install.sh | sh
+npm install -g @papert-code/papert-code
+papert --version
 ```
 
 ### Install from source
 
 ```bash
-git clone https://github.com/PapertLM/papert-code.git
+git clone https://github.com/azharlabs/papert-code.git
 cd papert-code
 npm install
 npm install -g .
 ```
 
-## Quick Start
+## Configure a model provider
 
-```bash
-# Start Papert Code
-papert
+Papert Code speaks the OpenAI-compatible API. Set your provider values via environment variables or `.env`/`.papert/.env` files:
 
-# Example commands
-> Explain this codebase structure
-> Help me refactor this function
-> Generate unit tests for this module
+```bash
+export OPENAI_API_KEY="your_api_key"
+export OPENAI_BASE_URL="https://api.your-provider.com/v1"   # optional if using api.openai.com
+export OPENAI_MODEL="your-model-id"                        # e.g. gpt-4o-mini
 ```
 
-### Session Management
+You can also pass flags per session:
 
-Control your token usage with configurable session limits to optimize costs and performance.
+```bash
+papert --model gpt-4o-mini --base-url https://api.openai.com/v1
+```
 
-#### Configure Session Token Limit
+## Quick start
 
-Create or edit `.papert/settings.json` in your home directory:
+```bash
+papert
 
-```json
-{
-  "sessionTokenLimit": 32000
-}
+# Example prompts
+> Give me a map of the main services in this repo.
+> Refactor the auth middleware for clearer error handling.
+> Generate integration tests for the payment flow.
 ```
 
-#### Session Commands
+### Everyday commands
 
-- **`/compress`** - Compress conversation history to continue within token limits
-- **`/clear`** - Clear all conversation history and start fresh
-- **`/stats`** - Check current token usage and limits
+- `/help` — list commands
+- `/clear` — wipe the conversation
+- `/compress` — shrink history to stay within context limits
+- `/stats` — show token and tool usage
+- `/exit` — quit the session
 
-> 📝 **Note**: Session token limit applies to a single conversation, not cumulative API calls.
+Keyboard shortcuts: `Ctrl+C` cancels the current turn, `Ctrl+D` exits on an empty line, arrow keys navigate history.
 
-### Vision Model Configuration
+## Core capabilities
 
-Papert Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. **This feature is enabled by default** - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.
+- **Repository awareness**: traverses large codebases, respects `.gitignore` and `.papertignore`, and uses ripgrep for fast search.
+- **Structured editing**: reads and writes files with minimal diffs; keeps edits scoped and reversible.
+- **Shell automation**: runs commands with approval; supports long-running tasks and streaming output.
+- **Planning and approvals**: choose how cautious the agent should be:
+  - `plan`: always propose a plan before acting
+  - `default`: ask for confirmation on impactful operations
+  - `auto-edit`: auto-approve safe edits, prompt for risky ones
+  - `yolo`: auto-approve everything (use sparingly)
+- **Sandboxing**: optional seatbelt (macOS) or container sandboxes (Docker/Podman) to isolate filesystem and network access.
+- **Extensibility**:
+  - `.papert/commands/` for custom slash-commands
+  - `.papert/agents/` for specialized subagents
+  - MCP servers for external toolchains and data sources
 
-#### Skip the Switch Dialog (Optional)
+## Project settings and ignore files
 
-If you don't want to see the interactive dialog each time, configure the default behavior in your `.papert/settings.json`:
+Papert Code looks for `.papert/settings.json` in your project or `~/.papert/settings.json` for user defaults. Example:
 
 ```json
 {
-  "experimental": {
-    "vlmSwitchMode": "once"
+  "model": "gpt-4o-mini",
+  "approvalMode": "default",
+  "tool": {
+    "core": ["read_file", "write_file", "run_terminal_cmd"],
+    "exclude": ["ShellTool(rm )"]
+  },
+  "sandbox": {
+    "enabled": false
   }
 }
 ```
 
-**Available modes:**
-
-- **`"once"`** - Switch to vision model for this query only, then revert
-- **`"session"`** - Switch to vision model for the entire session
-- **`"persist"`** - Continue with current model (no switching)
-- **Not set** - Show interactive dialog each time (default)
+Use `.papertignore` to exclude directories or files from context collection (same semantics as `.gitignore`). Environment variables can live in `.papert/.env` (project-scoped) or `~/.papert/.env` (user-scoped).
 
-#### Command Line Override
+## TypeScript SDK
 
-You can also set the behavior via command line:
+Install the SDK:
 
 ```bash
-# Switch once per query
-papert --vlm-switch-mode once
-
-# Switch for entire session
-papert --vlm-switch-mode session
-
-# Never switch automatically
-papert --vlm-switch-mode persist
+npm install @papert-code/sdk-typescript
 ```
 
-#### Disable Vision Models (Optional)
+### Streaming queries
 
-To completely disable vision model support, add to your `.papert/settings.json`:
+```typescript
+import { query } from '@papert-code/sdk-typescript';
 
-```json
-{
-  "experimental": {
-    "visionModelPreview": false
+for await (const message of query({
+  prompt: 'List the services in this repo and summarize their responsibilities.',
+  options: { cwd: '/path/to/project', model: 'gpt-4o-mini' },
+})) {
+  if (message.type === 'assistant') {
+    console.log(message.message.content);
+  }
+  if (message.type === 'result') {
+    console.log('Finished');
   }
 }
 ```
 
-> 💡 **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected.
-
-```bash
-# Just run this command and follow the browser authentication
-papert
-```
-
-**What happens:**
-
-1. **Instant Setup**: CLI opens your browser automatically
-2. **One-Click Login**: Authenticate with your papert.ai account
-3. **Automatic Management**: Credentials cached locally for future use
-4. **No Configuration**: Zero setup required - just start coding!
-
-#### OpenAI-Compatible API
-
-Use API keys for OpenAI or other compatible providers:
-
-**Configuration Methods:**
-
-1. **Environment Variables**
-
-   ```bash
-   export OPENAI_API_KEY="your_api_key_here"
-   export OPENAI_BASE_URL="your_api_endpoint"
-   export OPENAI_MODEL="your_model_choice"
-   ```
-
-2. **Project `.env` File**
-   Create a `.env` file in your project root:
-   ```env
-   OPENAI_API_KEY=your_api_key_here
-   OPENAI_BASE_URL=your_api_endpoint
-   OPENAI_MODEL=your_model_choice
-   ```
-
-## Usage Examples
-
-### 🔍 Explore Codebases
-
-```bash
-cd your-project/
-papert
-
-# Architecture analysis
-> Describe the main pieces of this system's architecture
-> What are the key dependencies and how do they interact?
-> Find all API endpoints and their authentication methods
-```
-
-### 💻 Code Development
+### Drive the full CLI
 
-```bash
-# Refactoring
-> Refactor this function to improve readability and performance
-> Convert this class to use dependency injection
-> Split this large module into smaller, focused components
-
-# Code generation
-> Create a REST API endpoint for user management
-> Generate unit tests for the authentication module
-> Add error handling to all database operations
-```
-
-### 🔄 Automate Workflows
-
-```bash
-# Git automation
-> Analyze git commits from the last 7 days, grouped by feature
-> Create a changelog from recent commits
-> Find all TODO comments and create GitHub issues
-
-# File operations
-> Convert all images in this directory to PNG format
-> Rename all test files to follow the *.test.ts pattern
-> Find and remove all console.log statements
-```
-
-### 🐛 Debugging & Analysis
-
-```bash
-# Performance analysis
-> Identify performance bottlenecks in this React component
-> Find all N+1 query problems in the codebase
+```typescript
+import { createPapertAgent } from '@papert-code/sdk-typescript';
 
-# Security audit
-> Check for potential SQL injection vulnerabilities
-> Find all hardcoded credentials or API keys
-```
-
-## Popular Tasks
+const agent = await createPapertAgent({
+  cliArgs: {
+    model: 'gpt-4o-mini',
+    approvalMode: 'auto-edit', // plan | default | auto-edit | yolo
+    apiKey: process.env.OPENAI_API_KEY,
+    baseUrl: 'https://api.openai.com/v1'
+  },
+});
 
-### 📚 Understand New Codebases
+const { stdout, exitCode } = await agent.runPrompt(
+  'Summarize outstanding TODOs by directory',
+  { extraArgs: ['--output-format', 'json'] },
+);
 
-```text
-> What are the core business logic components?
-> What security mechanisms are in place?
-> How does the data flow through the system?
-> What are the main design patterns used?
-> Generate a dependency graph for this module
+console.log(stdout, exitCode);
 ```
 
-### 🔨 Code Refactoring & Optimization
+SDK features:
 
-```text
-> What parts of this module can be optimized?
-> Help me refactor this class to follow SOLID principles
-> Add proper error handling and logging
-> Convert callbacks to async/await pattern
-> Implement caching for expensive operations
-```
+- Multi-turn streaming API with tool awareness.
+- Permission hooks (`canUseTool`), custom tool allow/deny lists, and MCP server wiring.
+- Abort support via `AbortController`, per-call environment overrides, and subagent configuration.
+- Works with the installed `papert` binary or a specified CLI path.
 
-### 📝 Documentation & Testing
+Examples live under `packages/sdk-typescript/examples` (ESM, no ts-node required).
 
-```text
-> Generate comprehensive JSDoc comments for all public APIs
-> Write unit tests with edge cases for this component
-> Create API documentation in OpenAPI format
-> Add inline comments explaining complex algorithms
-> Generate a README for this module
-```
+## VS Code companion
 
-### 🚀 Development Acceleration
+`packages/vscode-ide-companion` mirrors the CLI experience inside VS Code: native diffing, context awareness, and the same approval modes. Build it with `npm run build:vscode` or install from the marketplace once published.
 
-```text
-> Set up a new Express server with authentication
-> Create a React component with TypeScript and tests
-> Implement a rate limiter middleware
-> Add database migrations for new schema
-> Configure CI/CD pipeline for this project
-```
+## Development
 
-## Commands & Shortcuts
+Common scripts:
 
-### Session Commands
+- `npm run build` — build the CLI bundle
+- `npm test` — run workspace tests in parallel
+- `npm run lint` / `npm run lint:ci` — lint source and tests
+- `npm run typecheck` — TypeScript checks
+- `npm run build:all` — CLI + sandbox + VS Code companion
+- `npm run clean` — remove build artifacts and generated files
 
-- `/help` - Display available commands
-- `/clear` - Clear conversation history
-- `/compress` - Compress history to save tokens
-- `/stats` - Show current session information
-- `/exit` or `/quit` - Exit Papert Code
+See `CONTRIBUTING.md` for full contributor guidance and sandbox notes.
 
-### Keyboard Shortcuts
+## Troubleshooting
 
-- `Ctrl+C` - Cancel current operation
-- `Ctrl+D` - Exit (on empty line)
-- `Up/Down` - Navigate command history
+- Check `docs/support/troubleshooting.md` for common fixes.
+- Verify your provider configuration (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`).
+- Use `/stats` to see context usage and `/compress` to shrink history if you hit limits.
 
-## Acknowledgments
+## License
 
-This project is based on [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of the Gemini CLI team.
+Apache 2.0, see `LICENSE`.