@protolabsai/proto 0.14.0

package/dist/bundled/qc-helper/docs/extension/introduction.md

@@ -0,0 +1,303 @@
+# Qwen Code Extensions
+
+Qwen Code extensions package prompts, MCP servers, subagents, skills and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Qwen Code and share those capabilities with others. They are designed to be easily installable and shareable.
+
+Extensions and plugins from [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/) and [Claude Code Marketplace](https://claudemarketplaces.com/) can be directly installed into Qwen Code. This cross-platform compatibility gives you access to a rich ecosystem of extensions and plugins, dramatically expanding Qwen Code's capabilities without requiring extension authors to maintain separate versions.
+
+## Extension management
+
+We offer a suite of extension management tools using both `qwen extensions` CLI commands and `/extensions` slash commands within the interactive CLI.
+
+### Runtime Extension Management (Slash Commands)
+
+You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
+
+| Command                               | Description                                                       |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `/extensions` or `/extensions manage` | Manage all installed extensions                                   |
+| `/extensions install <source>`        | Install an extension from a git URL, local path, or marketplace   |
+| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser |
+
+### CLI Extension Management
+
+You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.
+
+### Installing an extension
+
+You can install an extension using `qwen extensions install` from multiple sources:
+
+#### From Claude Code Marketplace
+
+Qwen Code also supports plugins from the [Claude Code Marketplace](https://claudemarketplaces.com/). Install from a marketplace and choose a plugin:
+
+```bash
+qwen extensions install <marketplace-name>
+# or
+qwen extensions install <marketplace-github-url>
+```
+
+If you want to install a specific plugin, you can use the format with plugin name:
+
+```bash
+qwen extensions install <marketplace-name>:<plugin-name>
+# or
+qwen extensions install <marketplace-github-url>:<plugin-name>
+```
+
+For example, to install the `prompts.chat` plugin from the [f/awesome-chatgpt-prompts](https://claudemarketplaces.com/plugins/f-awesome-chatgpt-prompts) marketplace:
+
+```bash
+qwen extensions install f/awesome-chatgpt-prompts:prompts.chat
+# or
+qwen extensions install https://github.com/f/awesome-chatgpt-prompts:prompts.chat
+```
+
+Claude plugins are automatically converted to Qwen Code format during installation:
+
+- `claude-plugin.json` is converted to `qwen-extension.json`
+- Agent configurations are converted to Qwen subagent format
+- Skill configurations are converted to Qwen skill format
+- Tool mappings are automatically handled
+
+You can quickly browse available extensions from different marketplaces using the `/extensions explore` command:
+
+```bash
+# Open Gemini CLI Extensions marketplace
+/extensions explore Gemini
+
+# Open Claude Code marketplace
+/extensions explore ClaudeCode
+```
+
+This command opens the respective marketplace in your default browser, allowing you to discover new extensions to enhance your Qwen Code experience.
+
+> **Cross-Platform Compatibility**: This allows you to leverage the rich extension ecosystems from both Gemini CLI and Claude Code, dramatically expanding the available functionality for Qwen Code users.
+
+#### From Gemini CLI Extensions
+
+Qwen Code fully supports extensions from the [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/). Simply install them using the git URL:
+
+```bash
+qwen extensions install <gemini-cli-extension-github-url>
+# or
+qwen extensions install <owner>/<repo>
+```
+
+Gemini extensions are automatically converted to Qwen Code format during installation:
+
+- `gemini-extension.json` is converted to `qwen-extension.json`
+- TOML command files are automatically migrated to Markdown format
+- MCP servers, context files, and settings are preserved
+
+#### From Git Repository
+
+```bash
+qwen extensions install https://github.com/github/github-mcp-server
+```
+
+This will install the github mcp server extension.
+
+#### From Local Path
+
+```bash
+qwen extensions install /path/to/your/extension
+```
+
+Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
+
+### Uninstalling an extension
+
+To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:
+
+```
+qwen extensions uninstall qwen-cli-security
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an extension entirely or for specific workspace.
+
+For example, `qwen extensions disable extension-name` will disable the extension at the user level, so it will be disabled everywhere. `qwen extensions disable extension-name --scope=workspace` will only disable the extension in the current workspace.
+
+### Enabling an extension
+
+You can enable extensions using `qwen extensions enable extension-name`. You can also enable an extension for a specific workspace using `qwen extensions enable extension-name --scope=workspace` from within that workspace.
+
+This is useful if you have an extension disabled at the top-level and only enabled in specific places.
+
+### Updating an extension
+
+For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
+
+You can update all extensions with:
+
+```
+qwen extensions update --all
+```
+
+## How it works
+
+On startup, Qwen Code looks for extensions in `<home>/.qwen/extensions`
+
+Extensions exist as a directory that contains a `qwen-extension.json` file. For example:
+
+`<home>/.qwen/extensions/my-extension/qwen-extension.json`
+
+### `qwen-extension.json`
+
+The `qwen-extension.json` file contains the configuration for the extension. The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "QWEN.md",
+  "commands": "commands",
+  "skills": "skills",
+  "agents": "agents",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service",
+      "envVar": "MY_API_KEY",
+      "sensitive": true
+    }
+  ]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for `trust`.
+- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
+- `commands`: The directory containing custom commands (default: `commands`). Commands are `.md` files that define prompts.
+- `skills`: The directory containing custom skills (default: `skills`). Skills are discovered automatically and become available via the `/skills` command.
+- `agents`: The directory containing custom subagents (default: `agents`). Subagents are `.yaml` or `.md` files that define specialized AI assistants.
+- `settings`: An array of settings that the extension requires. When installing, users will be prompted to provide values for these settings. The values are stored securely and passed to MCP servers as environment variables.
+  - Each setting has the following properties:
+    - `name`: Display name for the setting
+    - `description`: A description of what this setting is used for
+    - `envVar`: The environment variable name that will be set
+    - `sensitive`: Boolean indicating if the value should be hidden (e.g., API keys, passwords)
+
+### Managing Extension Settings
+
+Extensions can require configuration through settings (such as API keys or credentials). These settings can be managed using the `qwen extensions settings` CLI command:
+
+**Set a setting value:**
+
+```bash
+qwen extensions settings set <extension-name> <setting-name> [--scope user|workspace]
+```
+
+**List all settings for an extension:**
+
+```bash
+qwen extensions settings list <extension-name>
+```
+
+**View current values (user and workspace):**
+
+```bash
+qwen extensions settings show <extension-name> <setting-name>
+```
+
+**Remove a setting value:**
+
+```bash
+qwen extensions settings unset <extension-name> <setting-name> [--scope user|workspace]
+```
+
+Settings can be configured at two levels:
+
+- **User level** (default): Settings apply across all projects (`~/.qwen/.env`)
+- **Workspace level**: Settings apply only to the current project (`.qwen/.env`)
+
+Workspace settings take precedence over user settings. Sensitive settings are stored securely and never displayed in plain text.
+
+When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
+
+### Custom commands
+
+Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing Markdown files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
+
+> **Note:** The command format has been updated from TOML to Markdown. TOML files are deprecated but still supported. You can migrate existing TOML commands using the automatic migration prompt that appears when TOML files are detected.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.qwen/extensions/gcp/
+├── qwen-extension.json
+└── commands/
+    ├── deploy.md
+    └── gcs/
+        └── sync.md
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.md` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.md` in help
+
+### Custom skills
+
+Extensions can provide custom skills by placing skill files in a `skills/` subdirectory within the extension directory. Each skill should have a `SKILL.md` file with YAML frontmatter defining the skill's name and description.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── skills/
+    └── pdf-processor/
+        └── SKILL.md
+```
+
+The skill will be available via the `/skills` command when the extension is active.
+
+### Custom subagents
+
+Extensions can provide custom subagents by placing agent configuration files in an `agents/` subdirectory within the extension directory. Agents are defined using YAML or Markdown files.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── agents/
+    └── testing-expert.yaml
+```
+
+Extension subagents appear in the subagent manager dialog under "Extension Agents" section.
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag)
+
+## Variables
+
+Qwen Code extensions allow variable substitution in `qwen-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.qwen/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                            |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                          |

package/dist/bundled/qc-helper/docs/features/_meta.ts

@@ -0,0 +1,18 @@
+export default {
+  commands: 'Commands',
+  'sub-agents': 'SubAgents',
+  arena: 'Agent Arena',
+  skills: 'Skills',
+  headless: 'Headless Mode',
+  checkpointing: {
+    display: 'hidden',
+  },
+  'approval-mode': 'Approval Mode',
+  mcp: 'MCP',
+  lsp: 'LSP (Language Server Protocol)',
+  'token-caching': 'Token Caching',
+  sandbox: 'Sandboxing',
+  language: 'i18n',
+  hooks: 'Hooks',
+  'scheduled-tasks': 'Scheduled Tasks',
+};

package/dist/bundled/qc-helper/docs/features/approval-mode.md

@@ -0,0 +1,263 @@
+# Approval Mode
+
+Qwen Code offers three distinct permission modes that allow you to flexibly control how AI interacts with your code and system based on task complexity and risk level.
+
+## Permission Modes Comparison
+
+| Mode           | File Editing                | Shell Commands              | Best For                                                                                               | Risk Level |
+| -------------- | --------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- |
+| **Plan**​      | ❌ Read-only analysis only  | ❌ Not executed             | • Code exploration <br>• Planning complex changes <br>• Safe code review                               | Lowest     |
+| **Default**​   | ✅ Manual approval required | ✅ Manual approval required | • New/unfamiliar codebases <br>• Critical systems <br>• Team collaboration <br>• Learning and teaching | Low        |
+| **Auto-Edit**​ | ✅ Auto-approved            | ❌ Manual approval required | • Daily development tasks <br>• Refactoring and code improvements <br>• Safe automation                | Medium     |
+| **YOLO**​      | ✅ Auto-approved            | ✅ Auto-approved            | • Trusted personal projects <br>• Automated scripts/CI/CD <br>• Batch processing tasks                 | Highest    |
+
+### Quick Reference Guide
+
+- **Start in Plan Mode**: Great for understanding before making changes
+- **Work in Default Mode**: The balanced choice for most development work
+- **Switch to Auto-Edit**: When you're making lots of safe code changes
+- **Use YOLO sparingly**: Only for trusted automation in controlled environments
+
+> [!tip]
+>
+> You can quickly cycle through modes during a session using **Shift+Tab** (or **Tab** on Windows). The terminal status bar shows your current mode, so you always know what permissions Qwen Code has.
+
+## 1. Use Plan Mode for safe code analysis
+
+Plan Mode instructs Qwen Code to create a plan by analyzing the codebase with **read-only** operations, perfect for exploring codebases, planning complex changes, or reviewing code safely.
+
+### When to use Plan Mode
+
+- **Multi-step implementation**: When your feature requires making edits to many files
+- **Code exploration**: When you want to research the codebase thoroughly before changing anything
+- **Interactive development**: When you want to iterate on the direction with Qwen Code
+
+### How to use Plan Mode
+
+**Turn on Plan Mode during a session**
+
+You can switch into Plan Mode during a session using **Shift+Tab** (or **Tab** on Windows) to cycle through permission modes.
+
+If you are in Normal Mode, **Shift+Tab** (or **Tab** on Windows) first switches into `auto-edits` Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** (or **Tab** on Windows) will switch into Plan Mode, indicated by `⏸ plan mode`.
+
+**Start a new session in Plan Mode**
+
+To start a new session in Plan Mode, use the `/approval-mode` then select `plan`
+
+```bash
+/approval-mode
+```
+
+**Run "headless" queries in Plan Mode**
+
+You can also run a query in Plan Mode directly with `-p` or `prompt`:
+
+```bash
+qwen --prompt "What is machine learning?"
+```
+
+### Example: Planning a complex refactor
+
+```bash
+/approval-mode plan
+```
+
+```
+I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
+```
+
+Qwen Code analyzes the current implementation and create a comprehensive plan. Refine with follow-ups:
+
+```
+What about backward compatibility?
+How should we handle database migration?
+```
+
+### Configure Plan Mode as default
+
+```json
+// .qwen/settings.json
+{
+  "permissions": {
+    "defaultMode": "plan"
+  }
+}
+```
+
+## 2. Use Default Mode for Controlled Interaction
+
+Default Mode is the standard way to work with Qwen Code. In this mode, you maintain full control over all potentially risky operations - Qwen Code will ask for your approval before making any file changes or executing shell commands.
+
+### When to use Default Mode
+
+- **New to a codebase**: When you're exploring an unfamiliar project and want to be extra cautious
+- **Critical systems**: When working on production code, infrastructure, or sensitive data
+- **Learning and teaching**: When you want to understand each step Qwen Code is taking
+- **Team collaboration**: When multiple people are working on the same codebase
+- **Complex operations**: When the changes involve multiple files or complex logic
+
+### How to use Default Mode
+
+**Turn on Default Mode during a session**
+
+You can switch into Default Mode during a session using **Shift+Tab**​ (or **Tab** on Windows) to cycle through permission modes. If you're in any other mode, pressing **Shift+Tab** (or **Tab** on Windows) will eventually cycle back to Default Mode, indicated by the absence of any mode indicator at the bottom of the terminal.
+
+**Start a new session in Default Mode**
+
+Default Mode is the initial mode when you start Qwen Code. If you've changed modes and want to return to Default Mode, use:
+
+```
+/approval-mode default
+```
+
+**Run "headless" queries in Default Mode**
+
+When running headless commands, Default Mode is the default behavior. You can explicitly specify it with:
+
+```
+qwen --prompt "Analyze this code for potential bugs"
+```
+
+### Example: Safely implementing a feature
+
+```
+/approval-mode default
+```
+
+```
+I need to add user profile pictures to our application. The pictures should be stored in an S3 bucket and the URLs saved in the database.
+```
+
+Qwen Code will analyze your codebase and propose a plan. It will then ask for approval before:
+
+1. Creating new files (controllers, models, migrations)
+2. Modifying existing files (adding new columns, updating APIs)
+3. Running any shell commands (database migrations, dependency installation)
+
+You can review each proposed change and approve or reject it individually.
+
+### Configure Default Mode as default
+
+```bash
+// .qwen/settings.json
+{
+  "permissions": {
+"defaultMode": "default"
+  }
+}
+```
+
+## 3. Auto Edits Mode
+
+Auto-Edit Mode instructs Qwen Code to automatically approve file edits while requiring manual approval for shell commands, ideal for accelerating development workflows while maintaining system safety.
+
+### When to use Auto-Accept Edits Mode
+
+- **Daily development**: Ideal for most coding tasks
+- **Safe automation**: Allows AI to modify code while preventing accidental execution of dangerous commands
+- **Team collaboration**: Use in shared projects to avoid unintended impacts on others
+
+### How to switch to this mode
+
+```
+# Switch via command
+/approval-mode auto-edit
+
+# Or use keyboard shortcut
+Shift+Tab (or Tab on Windows) # Switch from other modes
+```
+
+### Workflow Example
+
+1. You ask Qwen Code to refactor a function
+2. AI analyzes the code and proposes changes
+3. **Automatically**​ applies all file changes without confirmation
+4. If tests need to be run, it will **request approval**​ to execute `npm test`
+
+## 4. YOLO Mode - Full Automation
+
+YOLO Mode grants Qwen Code the highest permissions, automatically approving all tool calls including file editing and shell commands.
+
+### When to use YOLO Mode
+
+- **Automated scripts**: Running predefined automated tasks
+- **CI/CD pipelines**: Automated execution in controlled environments
+- **Personal projects**: Rapid iteration in fully trusted environments
+- **Batch processing**: Tasks requiring multi-step command chains
+
+> [!warning]
+>
+> **Use YOLO Mode with caution**: AI can execute any command with your terminal permissions. Ensure:
+>
+> 1. You trust the current codebase
+> 2. You understand all actions AI will perform
+> 3. Important files are backed up or committed to version control
+
+### How to enable YOLO Mode
+
+```
+# Temporarily enable (current session only)
+/approval-mode yolo
+
+# Set as project default
+/approval-mode yolo --project
+
+# Set as user global default
+/approval-mode yolo --user
+```
+
+### Configuration Example
+
+```bash
+// .qwen/settings.json
+{
+  "permissions": {
+"defaultMode": "yolo",
+"confirmShellCommands": false,
+"confirmFileEdits": false
+  }
+}
+```
+
+### Automated Workflow Example
+
+```bash
+# Fully automated refactoring task
+qwen --prompt "Run the test suite, fix all failing tests, then commit changes"
+
+# Without human intervention, AI will:
+# 1. Run test commands (auto-approved)
+# 2. Fix failed test cases (auto-edit files)
+# 3. Execute git commit (auto-approved)
+```
+
+## Mode Switching & Configuration
+
+### Keyboard Shortcut Switching
+
+During a Qwen Code session, use **Shift+Tab**​ (or **Tab** on Windows) to quickly cycle through the three modes:
+
+```
+Default Mode → Auto-Edit Mode → YOLO Mode → Plan Mode → Default Mode
+```
+
+### Persistent Configuration
+
+```
+// Project-level: ./.qwen/settings.json
+// User-level: ~/.qwen/settings.json
+{
+  "permissions": {
+"defaultMode": "auto-edit",  // or "plan" or "yolo"
+"confirmShellCommands": true,
+"confirmFileEdits": true
+  }
+}
+```
+
+### Mode Usage Recommendations
+
+1. **New to codebase**: Start with **Plan Mode**​ for safe exploration
+2. **Daily development tasks**: Use **Auto-Accept Edits**​ (default mode), efficient and safe
+3. **Automated scripts**: Use **YOLO Mode**​ in controlled environments for full automation
+4. **Complex refactoring**: Use **Plan Mode**​ first for detailed planning, then switch to appropriate mode for execution