# MerchantDuo

MerchantDuo is a Pi coding agent for Magento 2.4 teams. It starts from the store's selected environment, Magento version, deployment mode, and theme context instead of treating a Magento project as a generic repository.

```
npx @merchantduo/code 
```

## Overview

- Works with local checkouts, Warden, and SSH environments.
- Detects Magento edition, version, PHP version, deployment mode, cache types, and registered theme inheritance.
- Ships Magento 2.4, Luma, Hyva, Mage2Gen, testing, and persistent-goal skills.
- Provides guided local/Warden store provisioning.
- Keeps remote writes and Magento operations behind explicit execution boundaries.

At session start, MerchantDuo produces a Magento snapshot from the selected environment. Frontend and admin URLs are discovered but remain unverified until an explicit test. The compact status line shows the Magento version, environment lifecycle, session permission mode, an explicit theme scope when one is selected, and the frontend URL when available.

## Commands and tools

Extension slash commands are namespaced with `duo-` to avoid collisions with other Pi extensions.

- [Command reference](docs/commands.md) covers session theme and permission switching, lifecycle, navigation, and bundled persistent-goal commands.
- [Tool reference](docs/tools.md) covers workspace, environment, Magento workflow, magerun2, testing, PHP-console, and optional knowledge tools, including parameters and confirmation boundaries.

## Environments

Define the environments your team uses in `.merchantduo.yaml`, then select one at launch with `--env`.

```yaml
defaultEnvironment: local
activeTheme: all
testing:
  frontendUrl: https://shop.example.test/
  adminUrl: https://shop.example.test/admin/
  allowInsecureTls: true
environments:
  local:
    type: local
    root: .
  warden:
    type: warden
    projectRoot: .
    root: /var/www/html
    filesService: php-fpm
    targets:
      default: php-fpm
      debug: php-debug
  stage:
    type: ssh
    host: shop-stage
    root: /var/www/html
```

Local uses the checkout directly. Warden routes project and Magento execution through its configured service. Local and Warden sessions start in `normal`; SSH starts in `read-only`. Run `/duo-switch-permissions` to choose a mode interactively, or provide `<read-only|normal|yolo>` directly to change only the current session; `merchantduo --yolo` starts in `yolo`. Configure SSH user, port, and key through an OpenSSH host alias:

```sshconfig
Host shop-stage
  HostName stage.example.com
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519
```

Use that alias as `host: shop-stage`. Every `merchantduo init` asks “Choose what fits you most” and saves the selected role under the current user's `~/.merchantduo/operator-profile.yaml`: store admin, backend developer, frontend developer, or full-stack developer. It then offers local first and Warden when its project `.env` is detected; it prints an SSH example instead of writing an unused remote environment. The role is optional to load and gives the agent context for explanations and recommendations only; it does not change tools or permissions. Project configuration contains no user identity and is safe to share in a repository.

## Provisioning

Provision a local or Warden developer store from an empty directory or an existing Magento checkout:

```sh
merchantduo provision
merchantduo provision --env warden
```

This opens plain Pi in the host shell, even when the project defaults to Warden. It shares MerchantDuo’s configured Pi authentication, models, and user settings, but does not load the MerchantDuo package or initialize Magento context. The agent first inspects the real project, Warden/local runtime, Composer platform requirements, Magento state, and source/database evidence. It does not run a fixed Composer, database, Magento, lifecycle, or web-server sequence. Before a material mutation, it explains the evidence and intended effect and waits for confirmation. In particular, lock-file PHP incompatibility is diagnosed rather than bypassed with `composer update`. Unlike normal MerchantDuo sessions, provisioning may inspect and configure Magento deployment configuration such as `app/etc/env.php` and `app/etc/config.php` when needed; it must not reveal credentials or tokens in chat, commands, logs, or generated files.

## Install and start

MerchantDuo requires Node.js 22.19 or later, Bash, and Python 3. HTTP/browser testing additionally needs curl and Chrome or Chromium. The bundled `fetch_content` internet-research tool runs over host HTTP and has no browser or Python-runner prerequisite. Warden and SSH environments need Warden and OpenSSH respectively.

```sh
pnpm install --frozen-lockfile
merchantduo init
merchantduo doctor --env local
merchantduo --env local
```

Review the generated `.merchantduo.yaml` before the first session. MerchantDuo requires a one-time configuration trust decision; set `MERCHANTDUO_TRUST_CONFIG=1` only after review.

Normal interactive sessions display a compact MerchantDuo version and shortcut header, not Pi's skills or extensions inventories. MerchantDuo checks the npm `@merchantduo/code` release after startup; when a newer version exists, run:

```sh
merchantduo update
```

Use `merchantduo update --check` to inspect availability without changing anything. The updater only changes a global npm or pnpm installation. A source checkout or project dependency remains managed by its own checkout/dependency workflow.

## Safety and optional services

Normal MerchantDuo sessions do not load `app/etc/env.php`, credentials, or tokens into agent context. The separate provisioning session may configure Magento deployment files, but never reveals their secret values. MerchantDuo does not run background tests, cache commands, deployment actions, browser operations, or PHP code. Explicit operations use the confirmation rules described in the [tool reference](docs/tools.md).

Set `MERCHANTDUO_MCP_TOKEN` to enable the built-in read-only knowledge tool. Set `MERCHANTDUO_LLM_TOKEN` to enable the built-in MerchantDuo provider. Neither endpoint is project configuration.

## Development

```sh
pnpm install --frozen-lockfile
pnpm check
pnpm test
npm pack --dry-run
```

For the extension layout, provisioning boundary, and session lifecycle, see [the architecture notes](docs/architecture.md).