@anh3d0nic/qwen-code-termux-ice 1.0.0

package/docs/developers/contributing.md

@@ -0,0 +1,303 @@
+# How to Contribute
+
+We would love to accept your patches and contributions to this project.
+
+## Contribution Process
+
+### Code Reviews
+
+All submissions, including submissions by project members, require review. We
+use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
+for this purpose.
+
+### Pull Request Guidelines
+
+To help us review and merge your PRs quickly, please follow these guidelines. PRs that do not meet these standards may be closed.
+
+#### 1. Link to an Existing Issue
+
+All PRs should be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written.
+
+- **For bug fixes:** The PR should be linked to the bug report issue.
+- **For features:** The PR should be linked to the feature request or proposal issue that has been approved by a maintainer.
+
+If an issue for your change doesn't exist, please **open one first** and wait for feedback before you start coding.
+
+#### 2. Keep It Small and Focused
+
+We favor small, atomic PRs that address a single issue or add a single, self-contained feature.
+
+- **Do:** Create a PR that fixes one specific bug or adds one specific feature.
+- **Don't:** Bundle multiple unrelated changes (e.g., a bug fix, a new feature, and a refactor) into a single PR.
+
+Large changes should be broken down into a series of smaller, logical PRs that can be reviewed and merged independently.
+
+#### 3. Use Draft PRs for Work in Progress
+
+If you'd like to get early feedback on your work, please use GitHub's **Draft Pull Request** feature. This signals to the maintainers that the PR is not yet ready for a formal review but is open for discussion and initial feedback.
+
+#### 4. Ensure All Checks Pass
+
+Before submitting your PR, ensure that all automated checks are passing by running `npm run preflight`. This command runs all tests, linting, and other style checks.
+
+#### 5. Update Documentation
+
+If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the `/docs` directory.
+
+#### 6. Write Clear Commit Messages and a Good PR Description
+
+Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for your commit messages.
+
+- **Good PR Title:** `feat(cli): Add --json flag to 'config get' command`
+- **Bad PR Title:** `Made some changes`
+
+In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., `Fixes #123`).
+
+## Development Setup and Workflow
+
+This section guides contributors on how to build, modify, and understand the development setup of this project.
+
+### Setting Up the Development Environment
+
+**Prerequisites:**
+
+1.  **Node.js**:
+    - **Development:** Please use Node.js `~20.19.0`. This specific version is required due to an upstream development dependency issue. You can use a tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
+    - **Production:** For running the CLI in a production environment, any version of Node.js `>=20` is acceptable.
+2.  **Git**
+
+### Build Process
+
+To clone the repository:
+
+```bash
+git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL
+cd qwen-code
+```
+
+To install dependencies defined in `package.json` as well as root dependencies:
+
+```bash
+npm install
+```
+
+To build the entire project (all packages):
+
+```bash
+npm run build
+```
+
+This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.js` and `package.json` scripts for more details on what happens during the build.
+
+### Enabling Sandboxing
+
+[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `QWEN_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details.
+
+To build both the `qwen-code` CLI utility and the sandbox container, run `build:all` from the root directory:
+
+```bash
+npm run build:all
+```
+
+To skip building the sandbox container, you can use `npm run build` instead.
+
+### Running
+
+To start the Qwen Code application from the source code (after building), run the following command from the root directory:
+
+```bash
+npm start
+```
+
+If you'd like to run the source build outside of the qwen-code folder, you can utilize `npm link path/to/qwen-code/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) to run with `qwen-code`
+
+### Running Tests
+
+This project contains two types of tests: unit tests and integration tests.
+
+#### Unit Tests
+
+To execute the unit test suite for the project:
+
+```bash
+npm run test
+```
+
+This will run tests located in the `packages/core` and `packages/cli` directories. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run `npm run preflight`.
+
+#### Integration Tests
+
+The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default `npm run test` command.
+
+To run the integration tests, use the following command:
+
+```bash
+npm run test:e2e
+```
+
+For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/integration-tests.md).
+
+### Linting and Preflight Checks
+
+To ensure code quality and formatting consistency, run the preflight check:
+
+```bash
+npm run preflight
+```
+
+This command will run ESLint, Prettier, all tests, and other checks as defined in the project's `package.json`.
+
+_ProTip_
+
+after cloning create a git precommit hook file to ensure your commits are always clean.
+
+```bash
+echo "
+# Run npm build and check for errors
+if ! npm run preflight; then
+  echo "npm build failed. Commit aborted."
+  exit 1
+fi
+" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+```
+
+#### Formatting
+
+To separately format the code in this project by running the following command from the root directory:
+
+```bash
+npm run format
+```
+
+This command uses Prettier to format the code according to the project's style guidelines.
+
+#### Linting
+
+To separately lint the code in this project, run the following command from the root directory:
+
+```bash
+npm run lint
+```
+
+### Coding Conventions
+
+- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
+- **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.
+
+### Project Structure
+
+- `packages/`: Contains the individual sub-packages of the project.
+  - `cli/`: The command-line interface.
+  - `core/`: The core backend logic for Qwen Code.
+- `docs/`: Contains all project documentation.
+- `scripts/`: Utility scripts for building, testing, and development tasks.
+
+For more detailed architecture, see `docs/architecture.md`.
+
+## Documentation Development
+
+This section describes how to develop and preview the documentation locally.
+
+### Prerequisites
+
+1. Ensure you have Node.js (version 18+) installed
+2. Have npm or yarn available
+
+### Setup Documentation Site Locally
+
+To work on the documentation and preview changes locally:
+
+1. Navigate to the `docs-site` directory:
+
+   ```bash
+   cd docs-site
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Link the documentation content from the main `docs` directory:
+
+   ```bash
+   npm run link
+   ```
+
+   This creates a symbolic link from `../docs` to `content` in the docs-site project, allowing the documentation content to be served by the Next.js site.
+
+4. Start the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site with live updates as you make changes.
+
+Any changes made to the documentation files in the main `docs` directory will be reflected immediately in the documentation site.
+
+## Debugging
+
+### VS Code:
+
+0.  Run the CLI to interactively debug in VS Code with `F5`
+1.  Start the CLI in debug mode from the root directory:
+    ```bash
+    npm run debug
+    ```
+    This command runs `node --inspect-brk dist/index.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger.
+2.  In VS Code, use the "Attach" launch configuration (found in `.vscode/launch.json`).
+
+Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.
+
+To hit a breakpoint inside the sandbox container run:
+
+```bash
+DEBUG=1 qwen-code
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect qwen-code due to automatic exclusion. Use `.qwen-code/.env` files for qwen-code specific debug settings.
+
+### React DevTools
+
+To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.
+
+1.  **Start the Qwen Code application in development mode:**
+
+    ```bash
+    DEV=true npm start
+    ```
+
+2.  **Install and run React DevTools version 4.28.5 (or the latest compatible 4.x version):**
+
+    You can either install it globally:
+
+    ```bash
+    npm install -g react-devtools@4.28.5
+    react-devtools
+    ```
+
+    Or run it directly using npx:
+
+    ```bash
+    npx react-devtools@4.28.5
+    ```
+
+    Your running CLI application should then connect to React DevTools.
+
+## Sandboxing
+
+> TBD
+
+## Manual Publish
+
+We publish an artifact for each commit to our internal registry. But if you need to manually cut a local build, then run the following commands:
+
+```
+npm run clean
+npm install
+npm run auth
+npm run prerelease:dev
+npm publish --workspaces
+```

package/docs/developers/development/_meta.ts

@@ -0,0 +1,9 @@
+export default {
+  npm: 'NPM',
+  telemetry: 'Telemetry',
+  'integration-tests': 'Integration Tests',
+  'issue-and-pr-automation': 'Issue and PR Automation',
+  deployment: {
+    display: 'hidden',
+  },
+};

package/docs/developers/development/deployment.md

@@ -0,0 +1,117 @@
+# Qwen Code Execution and Deployment
+
+This document describes how to run Qwen Code and explains the deployment architecture that Qwen Code uses.
+
+## Running Qwen Code
+
+There are several ways to run Qwen Code. The option you choose depends on how you intend to use it.
+
+---
+
+### 1. Standard installation (Recommended for typical users)
+
+This is the recommended way for end-users to install Qwen Code. It involves downloading the Qwen Code package from the NPM registry.
+
+- **Global install:**
+
+  ```bash
+  npm install -g @qwen-code/qwen-code
+  ```
+
+  Then, run the CLI from anywhere:
+
+  ```bash
+  qwen
+  ```
+
+- **NPX execution:**
+
+  ```bash
+  # Execute the latest version from NPM without a global install
+  npx @qwen-code/qwen-code
+  ```
+
+---
+
+### 2. Running in a sandbox (Docker/Podman)
+
+For security and isolation, Qwen Code can be run inside a container. This is the default way that the CLI executes tools that might have side effects.
+
+- **Directly from the Registry:**
+  You can run the published sandbox image directly. This is useful for environments where you only have Docker and want to run the CLI.
+  ```bash
+  # Run the published sandbox image
+  docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11
+  ```
+- **Using the `--sandbox` flag:**
+  If you have Qwen Code installed locally (using the standard installation described above), you can instruct it to run inside the sandbox container.
+  ```bash
+  qwen --sandbox -y -p "your prompt here"
+  ```
+
+---
+
+### 3. Running from source (Recommended for Qwen Code contributors)
+
+Contributors to the project will want to run the CLI directly from the source code.
+
+- **Development Mode:**
+  This method provides hot-reloading and is useful for active development.
+  ```bash
+  # From the root of the repository
+  npm run start
+  ```
+- **Production-like mode (Linked package):**
+  This method simulates a global installation by linking your local package. It's useful for testing a local build in a production workflow.
+
+  ```bash
+  # Link the local cli package to your global node_modules
+  npm link packages/cli
+
+  # Now you can run your local version using the `qwen` command
+  qwen
+  ```
+
+---
+
+### 4. Running the latest Qwen Code commit from GitHub
+
+You can run the most recently committed version of Qwen Code directly from the GitHub repository. This is useful for testing features still in development.
+
+```bash
+# Execute the CLI directly from the main branch on GitHub
+npx https://github.com/QwenLM/qwen-code
+```
+
+## Deployment architecture
+
+The execution methods described above are made possible by the following architectural components and processes:
+
+**NPM packages**
+
+Qwen Code project is a monorepo that publishes core packages to the NPM registry:
+
+- `@qwen-code/qwen-code-core`: The backend, handling logic and tool execution.
+- `@qwen-code/qwen-code`: The user-facing frontend.
+
+These packages are used when performing the standard installation and when running Qwen Code from the source.
+
+**Build and packaging processes**
+
+There are two distinct build processes used, depending on the distribution channel:
+
+- **NPM publication:** For publishing to the NPM registry, the TypeScript source code in `@qwen-code/qwen-code-core` and `@qwen-code/qwen-code` is transpiled into standard JavaScript using the TypeScript Compiler (`tsc`). The resulting `dist/` directory is what gets published in the NPM package. This is a standard approach for TypeScript libraries.
+
+- **GitHub `npx` execution:** When running the latest version of Qwen Code directly from GitHub, a different process is triggered by the `prepare` script in `package.json`. This script uses `esbuild` to bundle the entire application and its dependencies into a single, self-contained JavaScript file. This bundle is created on-the-fly on the user's machine and is not checked into the repository.
+
+**Docker sandbox image**
+
+The Docker-based execution method is supported by the `qwen-code-sandbox` container image. This image is published to a container registry and contains a pre-installed, global version of Qwen Code.
+
+## Release process
+
+The release process is automated through GitHub Actions. The release workflow performs the following actions:
+
+1.  Build the NPM packages using `tsc`.
+2.  Publish the NPM packages to the artifact registry.
+3.  Create GitHub releases with bundled assets.

package/docs/developers/development/integration-tests.md

@@ -0,0 +1,137 @@
+# Integration Tests
+
+This document provides information about the integration testing framework used in this project.
+
+## Overview
+
+The integration tests are designed to validate the end-to-end functionality of Qwen Code. They execute the built binary in a controlled environment and verify that it behaves as expected when interacting with the file system.
+
+These tests are located in the `integration-tests` directory and are run using a custom test runner.
+
+## Running the tests
+
+The integration tests are not run as part of the default `npm run test` command. They must be run explicitly using the `npm run test:integration:all` script.
+
+The integration tests can also be run using the following shortcut:
+
+```bash
+npm run test:e2e
+```
+
+## Running a specific set of tests
+
+To run a subset of test files, you can use `npm run <integration test command> <file_name1> ....` where &lt;integration test command&gt; is either `test:e2e` or `test:integration*` and `<file_name>` is any of the `.test.js` files in the `integration-tests/` directory. For example, the following command runs `list_directory.test.js` and `write_file.test.js`:
+
+```bash
+npm run test:e2e list_directory write_file
+```
+
+### Running a single test by name
+
+To run a single test by its name, use the `--test-name-pattern` flag:
+
+```bash
+npm run test:e2e -- --test-name-pattern "reads a file"
+```
+
+### Running all tests
+
+To run the entire suite of integration tests, use the following command:
+
+```bash
+npm run test:integration:all
+```
+
+### Sandbox matrix
+
+The `all` command will run tests for `no sandboxing`, `docker` and `podman`.
+Each individual type can be run using the following commands:
+
+```bash
+npm run test:integration:sandbox:none
+```
+
+```bash
+npm run test:integration:sandbox:docker
+```
+
+```bash
+npm run test:integration:sandbox:podman
+```
+
+## Diagnostics
+
+The integration test runner provides several options for diagnostics to help track down test failures.
+
+### Keeping test output
+
+You can preserve the temporary files created during a test run for inspection. This is useful for debugging issues with file system operations.
+
+To keep the test output set the `KEEP_OUTPUT` environment variable to `true`.
+
+```bash
+KEEP_OUTPUT=true npm run test:integration:sandbox:none
+```
+
+When output is kept, the test runner will print the path to the unique directory for the test run.
+
+### Verbose output
+
+For more detailed debugging, set the `VERBOSE` environment variable to `true`.
+
+```bash
+VERBOSE=true npm run test:integration:sandbox:none
+```
+
+When using `VERBOSE=true` and `KEEP_OUTPUT=true` in the same command, the output is streamed to the console and also saved to a log file within the test's temporary directory.
+
+The verbose output is formatted to clearly identify the source of the logs:
+
+```
+--- TEST: <log dir>:<test-name> ---
+... output from the qwen command ...
+--- END TEST: <log dir>:<test-name> ---
+```
+
+## Linting and formatting
+
+To ensure code quality and consistency, the integration test files are linted as part of the main build process. You can also manually run the linter and auto-fixer.
+
+### Running the linter
+
+To check for linting errors, run the following command:
+
+```bash
+npm run lint
+```
+
+You can include the `:fix` flag in the command to automatically fix any fixable linting errors:
+
+```bash
+npm run lint:fix
+```
+
+## Directory structure
+
+The integration tests create a unique directory for each test run inside the `.integration-tests` directory. Within this directory, a subdirectory is created for each test file, and within that, a subdirectory is created for each individual test case.
+
+This structure makes it easy to locate the artifacts for a specific test run, file, or case.
+
+```
+.integration-tests/
+└── <run-id>/
+    └── <test-file-name>.test.js/
+        └── <test-case-name>/
+            ├── output.log
+            └── ...other test artifacts...
+```
+
+## Continuous integration
+
+To ensure the integration tests are always run, a GitHub Actions workflow is defined in `.github/workflows/e2e.yml`. This workflow automatically runs the integrations tests for pull requests against the `main` branch, or when a pull request is added to a merge queue.
+
+The workflow runs the tests in different sandboxing environments to ensure Qwen Code is tested across each:
+
+- `sandbox:none`: Runs the tests without any sandboxing.
+- `sandbox:docker`: Runs the tests in a Docker container.
+- `sandbox:podman`: Runs the tests in a Podman container.

package/docs/developers/development/issue-and-pr-automation.md

@@ -0,0 +1,84 @@
+# Automation and Triage Processes
+
+This document provides a detailed overview of the automated processes we use to manage and triage issues and pull requests. Our goal is to provide prompt feedback and ensure that contributions are reviewed and integrated efficiently. Understanding this automation will help you as a contributor know what to expect and how to best interact with our repository bots.
+
+## Guiding Principle: Issues and Pull Requests
+
+First and foremost, almost every Pull Request (PR) should be linked to a corresponding Issue. The issue describes the "what" and the "why" (the bug or feature), while the PR is the "how" (the implementation). This separation helps us track work, prioritize features, and maintain clear historical context. Our automation is built around this principle.
+
+---
+
+## Detailed Automation Workflows
+
+Here is a breakdown of the specific automation workflows that run in our repository.
+
+### 1. When you open an Issue: `Automated Issue Triage`
+
+This is the first bot you will interact with when you create an issue. Its job is to perform an initial analysis and apply the correct labels.
+
+- **Workflow File**: `.github/workflows/qwen-automated-issue-triage.yml`
+- **When it runs**: Immediately after an issue is created or reopened.
+- **What it does**:
+  - It uses a Qwen model to analyze the issue's title and body against a detailed set of guidelines.
+  - **Applies one `area/*` label**: Categorizes the issue into a functional area of the project (e.g., `area/ux`, `area/models`, `area/platform`).
+  - **Applies one `kind/*` label**: Identifies the type of issue (e.g., `kind/bug`, `kind/enhancement`, `kind/question`).
+  - **Applies one `priority/*` label**: Assigns a priority from P0 (critical) to P3 (low) based on the described impact.
+  - **May apply `status/need-information`**: If the issue lacks critical details (like logs or reproduction steps), it will be flagged for more information.
+  - **May apply `status/need-retesting`**: If the issue references a CLI version that is more than six versions old, it will be flagged for retesting on a current version.
+- **What you should do**:
+  - Fill out the issue template as completely as possible. The more detail you provide, the more accurate the triage will be.
+  - If the `status/need-information` label is added, please provide the requested details in a comment.
+
+### 2. When you open a Pull Request: `Continuous Integration (CI)`
+
+This workflow ensures that all changes meet our quality standards before they can be merged.
+
+- **Workflow File**: `.github/workflows/ci.yml`
+- **When it runs**: On every push to a pull request.
+- **What it does**:
+  - **Lint**: Checks that your code adheres to our project's formatting and style rules.
+  - **Test**: Runs our full suite of automated tests across macOS, Windows, and Linux, and on multiple Node.js versions. This is the most time-consuming part of the CI process.
+  - **Post Coverage Comment**: After all tests have successfully passed, a bot will post a comment on your PR. This comment provides a summary of how well your changes are covered by tests.
+- **What you should do**:
+  - Ensure all CI checks pass. A green checkmark ✅ will appear next to your commit when everything is successful.
+  - If a check fails (a red "X" ❌), click the "Details" link next to the failed check to view the logs, identify the problem, and push a fix.
+
+### 3. Ongoing Triage for Pull Requests: `PR Auditing and Label Sync`
+
+This workflow runs periodically to ensure all open PRs are correctly linked to issues and have consistent labels.
+
+- **Workflow File**: `.github/workflows/qwen-scheduled-pr-triage.yml`
+- **When it runs**: Every 15 minutes on all open pull requests.
+- **What it does**:
+  - **Checks for a linked issue**: The bot scans your PR description for a keyword that links it to an issue (e.g., `Fixes #123`, `Closes #456`).
+  - **Adds `status/need-issue`**: If no linked issue is found, the bot will add the `status/need-issue` label to your PR. This is a clear signal that an issue needs to be created and linked.
+  - **Synchronizes labels**: If an issue _is_ linked, the bot ensures the PR's labels perfectly match the issue's labels. It will add any missing labels and remove any that don't belong, and it will remove the `status/need-issue` label if it was present.
+- **What you should do**:
+  - **Always link your PR to an issue.** This is the most important step. Add a line like `Resolves #<issue-number>` to your PR description.
+  - This will ensure your PR is correctly categorized and moves through the review process smoothly.
+
+### 4. Ongoing Triage for Issues: `Scheduled Issue Triage`
+
+This is a fallback workflow to ensure that no issue gets missed by the triage process.
+
+- **Workflow File**: `.github/workflows/qwen-scheduled-issue-triage.yml`
+- **When it runs**: Every hour on all open issues.
+- **What it does**:
+  - It actively seeks out issues that either have no labels at all or still have the `status/need-triage` label.
+  - It then triggers the same powerful QwenCode-based analysis as the initial triage bot to apply the correct labels.
+- **What you should do**:
+  - You typically don't need to do anything. This workflow is a safety net to ensure every issue is eventually categorized, even if the initial triage fails.
+
+### 5. Release Automation
+
+This workflow handles the process of packaging and publishing new versions of Qwen Code.
+
+- **Workflow File**: `.github/workflows/release.yml`
+- **When it runs**: On a daily schedule for "nightly" releases, and manually for official patch/minor releases.
+- **What it does**:
+  - Automatically builds the project, bumps the version numbers, and publishes the packages to npm.
+  - Creates a corresponding release on GitHub with generated release notes.
+- **What you should do**:
+  - As a contributor, you don't need to do anything for this process. You can be confident that once your PR is merged into the `main` branch, your changes will be included in the very next nightly release.
+
+We hope this detailed overview is helpful. If you have any questions about our automation or processes, please don't hesitate to ask!