@merchantduo/code 0.1.0-beta.0 → 0.2.0-beta.1

package/README.md

@@ -1,91 +1,78 @@
 # MerchantDuo
 
-MerchantDuo is a Magento-native coding companion for [Pi](https://github.com/earendil-works/pi). It gives an agent the right Magento context and safely routes its work to a local project, a Warden service, or an SSH environment—without forking Pi or storing credentials.
+MerchantDuo is a Pi coding agent for Magento teams that works from the store's real environment, Magento version, deployment mode, and theme context.
 
-Built for Magento Open Source and Adobe Commerce 2.4.x projects. This is an early public beta.
+## Main features
 
-## Features
+- Magento-aware coding sessions
+- Local, Warden, and SSH environments
+- Developer-store provisioning
+- Magento 2.4, Luma, Hyva, Mage2Gen, and testing skills
+- Magento workflows and focused test tools
+- Version, edition, deployment-mode, and theme detection
+- Remote-write and operational safety controls
 
-- Detects Magento edition, version, PHP version, deploy mode, cache types, and enabled modules.
-- Keeps a terminal session pinned to one environment: local, Warden, or SSH.
-- Uses project-scoped configuration with strict validation, environment-variable secrets, and one-time trust per config revision.
-- Runs Warden commands through the selected service, including `php-debug` when requested.
-- Makes SSH environments cautious by default: remote profiles are read-only unless explicitly made writable, and remote commands require confirmation.
-- Tracks Magento-related edits and exposes safe, explicit cache, maintenance, compilation, setup, and static-content workflows through Pi.
-- Adds a configurable, read-only Magento knowledge MCP connection when available.
-- Detects Magento-registered themes and lets a session scope work to all themes, any relevant theme, or one selected theme with `/theme`.
-- Ships Magento 2.4, Luma, Mage2Gen, and official Hyva skill sources; selected Magento/theme guidance is injected only when applicable.
-- Ships with a placeholder OpenAI-compatible provider configuration that you can replace before production use.
+## Details
 
-## Requirements
+MerchantDuo gives Magento developers a coding-agent workspace that starts with the project context they need. It runs on Pi, inspects the selected Magento environment, keeps theme scope visible, and exposes Magento-specific tools for the work that usually slows an agency team down.
 
-- Node.js 22.19 or newer
-- Bash
-- A Magento project for Magento-aware features
-- Optional: [Warden](https://docs.warden.dev/) or SSH for those environment types
+It is built for Magento 2.4 development, not as a generic chat wrapper with a few shell commands attached. A session knows whether it is working locally, in Warden, or through SSH. It can identify the Magento edition, version, PHP version, deployment mode, enabled module count, cache types, and real registered themes before it suggests framework-specific work.
 
-## Install
+MerchantDuo is currently beta software for development teams.
 
-Run it without a global install:
+## What agencies get
 
-```sh
-npx merchantduo init
-```
-
-Or install the beta globally:
-
-```sh
-npm install --global merchantduo
-merchantduo init
-```
-
-`merchantduo init` creates `.merchantduo.yaml` in the current project.
+- A Pi coding-agent package with Magento context from the start of each session.
+- Local, Warden, and SSH environments selected per project or command.
+- A guided `provision` command for preparing a local or Warden developer store.
+- Native Magento 2.4, Luma, Hyva, Mage2Gen, and testing skills.
+- Magento-aware file, search, edit, module-generation, workflow, HTTP, browser, and PHP-console tools.
+- Theme discovery based on registered themes in `vendor` and `app/design`, including parent chains and Luma or Hyva classification.
+- Deployment-mode guidance that changes for developer, default, and production installations.
+- Guardrails around remote writes, Magento operations, credentials, and browser access.
 
-## Quick start
+The result is less time re-explaining a store to an agent and fewer generic recommendations that do not fit Magento.
 
-1. Initialise configuration from your Magento project root.
+## Magento context before the first change
 
-   ```sh
-   merchantduo init
-   ```
+At session startup, MerchantDuo creates a Magento snapshot for the selected environment. It reads `composer.lock` and `bin/magento --version` when available, then reports disagreements instead of silently choosing one. The snapshot includes:
 
-2. Optionally set a token for the built-in read-only Magento knowledge MCP.
+- Magento Open Source or Adobe Commerce edition and version
+- PHP version and deployment mode
+- Enabled module count and cache types
+- Registered themes, inheritance chains, and Luma or Hyva classification
+- Available frontend and admin URLs, marked unverified until explicitly tested
+- Whether the selected environment is writable
 
-   ```sh
-   export MERCHANTDUO_MCP_TOKEN="..."
-   ```
+Theme discovery only scans real Magento theme roots: package roots under `vendor` and themes under `app/design`. It does not search arbitrary vendor fixtures. Use `/theme` to select `all`, `any`, or a detected theme code. `all` keeps every detected theme in scope, while `any` tells the agent to identify the relevant theme before it edits theme-specific code.
 
-3. Review the generated configuration, then approve it once. MerchantDuo records trust by absolute path and content digest, so a changed file needs to be reviewed again.
+## Curated Magento knowledge
 
-   ```sh
-   MERCHANTDUO_TRUST_CONFIG=1 merchantduo doctor
-   ```
+MerchantDuo ships focused Pi skills instead of relying on broad, generic instructions:
 
-4. Start Pi in your chosen environment.
+- `magento-24x` guides Magento 2.4 work toward service contracts, dependency injection, declarative schema and data patches, layout XML, and the right deployment-mode workflow.
+- `luma` covers Magento fallback, layout XML, RequireJS, UI components, Knockout, LESS, and static assets.
+- `hyva` directs work toward Hyva templates, Alpine, Tailwind, and Hyva UI components. The package also vendors the relevant Hyva skills.
+- `mage2gen` makes vendored Mage2Gen the standard starting point for new modules.
+- `magento-testing` keeps testing explicit, targeted, and unauthenticated.
 
-   ```sh
-   merchantduo --env default "Explain this Magento module"
-   merchantduo --env warden "Find the layout handle for checkout"
-   ```
+The current package provides this curated knowledge locally through Pi skills. `merchantduo doctor` reports knowledge-service status and currently shows that no external knowledge connection is configured. That prevents the agent from presenting an unavailable MCP source as project knowledge.
 
-## Configuration
+## Environments that match agency work
 
-MerchantDuo merges optional global defaults from `~/.merchantduo/config.yaml` with the project file `.merchantduo.yaml`. Project environments replace global environments with the same name. Unknown keys and missing interpolated variables are rejected.
+Define the environments your team actually uses in `.merchantduo.yaml`, then select one at launch with `--env`.
 
 ```yaml
-version: 1
-defaultEnvironment: default
+defaultEnvironment: local
 activeTheme: all
-
-automation:
-  syntaxChecks: auto
-  cacheClean: auto
-
+testing:
+  frontendUrl: https://shop.example.test/
+  adminUrl: https://shop.example.test/admin/
+  allowInsecureTls: true
 environments:
-  default:
+  local:
     type: local
     root: .
-
   warden:
     type: warden
     projectRoot: .
@@ -94,7 +81,6 @@ environments:
     targets:
       default: php-fpm
       debug: php-debug
-
   stage:
     type: ssh
     host: shop-stage
@@ -102,62 +88,109 @@ environments:
     writable: false
 ```
 
-Environment selection is fixed for a running session and follows this order:
+Local work uses the Magento checkout directly. Warden work routes file and Magento commands through the selected service. SSH starts read-only unless you set `writable: true`, and writable remote file or shell work requires confirmation.
 
-1. `--env <name>`
-2. `MERCHANTDUO_ENV`
-3. `defaultEnvironment`
-4. An implicit local environment rooted at the current directory
+For SSH user names, ports, and identities, use an OpenSSH alias rather than extra YAML keys:
 
-`activeTheme` is project-scoped. Its default, `all`, means changes should cover every detected registered theme. `any` tells the agent to infer the relevant theme from the request and code. A concrete Magento theme code limits theme-specific work to that theme and its inheritance chain. The `/theme` command displays a selector when called without arguments, or accepts `/theme all`, `/theme any`, or a detected theme code. Invalid values do not change the file.
+```sshconfig
+Host shop-stage
+  HostName stage.example.com
+  User deploy
+  Port 2222
+  IdentityFile ~/.ssh/id_ed25519
+```
 
-## Commands
+Use the alias as `host: shop-stage` in `.merchantduo.yaml`.
 
-```sh
-# Launch Pi with MerchantDuo
-merchantduo [--env <name>] [--config <path>] [Pi options or prompt]
+`merchantduo init` offers the local checkout first. When the project `.env` contains Warden routing markers, it also offers a Warden environment. It writes only the environments you accept and then prints the remote SSH example instead of adding a fake remote entry. Local development certificates are accepted by default; set `testing.allowInsecureTls: false` when the selected URLs have publicly trusted certificates.
 
-# Create .merchantduo.yaml
-merchantduo init
+## Provision a developer store
 
-# Check Magento and environment connectivity
-merchantduo doctor [--env <name>]
+Run provisioning from an empty directory or an existing Magento project:
+
+```sh
+merchantduo provision
+merchantduo provision --env warden --source https://git.example.test/store.git --database ./backup.sql.gz --yes
 ```
 
-`merchantduo doctor` includes detected registered themes, their inheritance chains/classes, and the active theme scope. Discovery reads registrations only from installed vendor package roots and `app/design` theme roots, excluding framework test fixtures. Pi’s footer shows the package/Magento version, environment and write policy, and `Theme: <selection> (/theme to switch)`. SSH is always confirmation-gated; a non-writable SSH profile is additionally read-only.
+Provisioning supports local and Warden environments. It inspects available services, Magento source, database dumps, and existing web-server routing. The interactive flow asks only for choices it cannot resolve, prints an ordered plan, and asks once before it changes anything.
 
-## Skills and Mage2Gen
+With `--yes`, every decision must already be explicit or unambiguous. The command fails rather than guessing a source, database, web server, or environment.
 
-All shipped skills remain available for explicit use. On session start and after context compaction, MerchantDuo automatically supplies the best Magento instruction for the detected version (currently the `2.4` prefix) plus Luma or Hyva guidance only when a concrete selected theme has that class. `all` and `any` deliberately suppress automatic theme guidance. Theme changes are coalesced and take effect on the next prompt.
+Sources can be an existing checkout, Git URL, local archive, or HTTPS archive. Databases can be the current database, a local SQL or compressed SQL dump, or an HTTPS URL. Downloaded archives are staged below `MERCHANTDUO_HOME/provisions`, checked for path traversal, and removed after extraction.
 
-Every session also receives MerchantDuo's baseline implementation rules: inspect relevant code and inheritance before edits, use Magento-native extension points, follow the selected theme scope, and validate proportionally. A direct user request to run an operational Magento action invokes the workflow immediately; its single MerchantDuo confirmation dialog is authoritative, so the agent does not ask for an additional conversational confirmation. New module requests must use the vendored Mage2Gen scaffolding first, unless it cannot represent the request and the agent states why.
+Input precedence is command flags, then a discovered Magento checkout or the only SQL dump in the project root, then the interactive interview.
 
-The official Hyva skill repository is vendored at `vendor/hyva-ai-tools/skills`. Mage2Gen's `magento-2.4` source is vendored at `vendor/mage2gen`; use the `mage2gen_generate_module` tool rather than locating the source from the target project. It runs the package-absolute Mage2Gen Python library against the local/Warden project workspace, writes only to `app/code`, and supports an optional frontend route/controller starter. Python 3 is required; Mage2Gen's setup has no runtime dependencies beyond Python/setuptools. The tool refuses existing destinations and presents one write confirmation. SSH generation is intentionally unsupported because the local package source is not installed on the remote host.
+For Warden, MerchantDuo runs Warden lifecycle and database commands on the host, then runs Composer and Magento commands in the configured PHP service. Local provisioning requires PHP, Composer, the MySQL client, and an active nginx or Apache service. If no matching virtual host exists, the approved plan can add a minimal `pub` vhost and an `/etc/hosts` entry for the selected local domain. It does not replace an existing matching vhost.
 
-Useful environment variables:
+If `MERCHANTDUO_LLM_TOKEN` is set, provisioning can ask a narrow OpenAI-compatible advisor to choose from its already generated action plan. Its built-in endpoint and model are mock wiring, not a hosted AI service. Invalid advisor output falls back to the deterministic plan. MerchantDuo never sends the token, database credentials, or `app/etc/env.php` contents to the advisor.
 
-| Variable                | Purpose                                                       |
-| ----------------------- | ------------------------------------------------------------- |
-| `MERCHANTDUO_HOME`      | Overrides the default state directory, `~/.merchantduo`.      |
-| `MERCHANTDUO_CONFIG`    | Selects a configuration file.                                 |
-| `MERCHANTDUO_ENV`       | Selects the session environment.                              |
-| `MERCHANTDUO_API_KEY`   | Enables the configured MerchantDuo provider.                  |
-| `MERCHANTDUO_MCP_TOKEN` | Optionally supplies the token for the built-in knowledge MCP. |
+## Tools that respect Magento boundaries
 
-## Safety model and post-change workflows
+MerchantDuo uses direct Pi extensions for context, permissions, workspace work, themes, Mage2Gen, workflows, and testing. The package manifest is the source of truth for both extensions and skills.
+
+| Capability | What it does |
+| --- | --- |
+| Workspace tools | Read, search, write, and edit inside the selected environment. |
+| `mage2gen_generate_module` | Previews or generates a module under the selected local or Warden project's `app/code`. It refuses existing destinations and does not run over SSH. |
+| `magento_workflow` | Previews Magento operations such as cache cleaning, setup upgrade, DI compilation, static-content deployment, reindexing, and tests. Use `execute: true` to request the single in-tool confirmation. |
+| `magento_http_test` | Runs an explicit unauthenticated GET or HEAD request against a discovered Magento URL. |
+| `magento_browser_test` | Captures a screenshot or DOM dump with an isolated Chromium profile. Artifacts are stored under `MERCHANTDUO_HOME/artifacts/<project-id>/`. |
+| `magento_php_repl` | Runs one PHP snippet through a one-shot `n98-magerun2` console. |
+| `/navigate-frontend` and `/navigate-adminhtml` | Open a discovered same-origin frontend or admin URL without handling login credentials. |
 
-MerchantDuo does not read `app/etc/env.php` or inject credentials into agent context. Keep secrets in environment variables. It never automatically runs cache flushes, maintenance changes, static-content deployment, compilation, setup upgrades, indexing, tests, or remote mutations. Use the `magento_workflow` tool for command previews and explicit confirmation; it is the only route for Magento operational commands. Its actions include `cache-clean`, `cache-flush`, `maintenance-enable`, `maintenance-disable`, `setup-upgrade`, `compile`, `static-content-deploy`, `reindex`, and `tests`.
+No lifecycle hook runs tests, cache actions, deployments, or browser commands because a session started or a file changed. Those operations remain explicit. Testing and navigation are direct user-request boundaries, so they do not ask for the MerchantDuo confirmation.
 
-MerchantDuo reads `bin/magento deploy:mode:show` into the snapshot and uses that detected mode when recommending post-change work. It first inspects the changed module/files and chooses the smallest Magento-native workflow: ordinary PHP or template edits generally require only a relevant targeted cache clean, if any. Module registration, schema, declarative configuration, or dependency changes use this guidance:
+## Magento workflows without blind deployment commands
 
-| Mode | Recommended workflow |
+MerchantDuo tracks changed files and recommends the smallest relevant operation. It does not assume every edit needs a full Magento deployment.
+
+| Detected mode | Typical module-change sequence |
 | --- | --- |
-| Developer | `setup:upgrade`, then targeted cache clean. Do not normally compile DI or deploy static content. |
-| Default | `setup:upgrade`, then targeted cache clean. Compile or static deploy only when the task specifically requires it. |
-| Production | maintenance enable → `setup:upgrade` → DI compile → static-content deploy → targeted cache clean → maintenance disable. |
+| Developer | `setup:upgrade`, then clean relevant cache types. |
+| Default | `setup:upgrade`, then clean relevant cache types. Compile DI or deploy static content only when the change requires it. |
+| Production | Enable maintenance mode, run `setup:upgrade`, compile DI, deploy static content, clean relevant cache types, then disable maintenance mode. |
+
+If the deployment mode cannot be determined, MerchantDuo reports that fact instead of inventing a sequence.
+
+## Install and start
+
+MerchantDuo requires Node.js 22.19 or later, Bash, Python 3, curl, and Chromium or Chrome. Warden environments require Warden. SSH environments require OpenSSH. A remote PHP console needs `n98-magerun2` on that environment.
+
+Linux navigation also needs `xdg-open`. Browser discovery accepts `chromium-browser`, `chromium`, `google-chrome`, and `google-chrome-stable`.
+
+Install the package through your team's npm registry, then create the project configuration:
+
+```sh
+merchantduo init
+merchantduo doctor --env local
+merchantduo --env local
+```
+
+`merchantduo init` creates `.merchantduo.yaml`. Review it before the first agent session. MerchantDuo requires an explicit one-time trust decision for a project configuration. Set `MERCHANTDUO_TRUST_CONFIG=1` only after reviewing that file.
+
+Testing URLs can be configured at the top level or per environment. Configured URLs take precedence over discovery. Local discovery reads Magento base URLs and the admin URI. Warden reads `TRAEFIK_DOMAIN` and `TRAEFIK_SUBDOMAIN` from the project `.env`. MerchantDuo does not contact discovered URLs until an explicit testing request.
+
+For SSH, MerchantDuo uses configured URLs or reads Magento remotely when URLs are absent. HTTP tests, browser tests, navigation, temporary browser profiles, and test artifacts always run on and belong to the host, including for Warden. MerchantDuo finds and invokes the host `curl` and Chrome/Chromium, never their container copies. Local TLS exceptions apply consistently to both curl and the browser. The PHP REPL remains Magento-side because it executes application code and therefore needs Warden's PHP service, project files, configuration, and database. When local `n98-magerun2` is unavailable, MerchantDuo looks in `vendor/bin`, `bin`, and `PATH`, then can use a verified official PHAR cache under `MERCHANTDUO_HOME/tools/n98-magerun2` without modifying the Magento project. Failure to obtain that cache does not stop the session.
+
+## Safety model
 
-If mode detection fails or returns an unknown value, MerchantDuo reports that rather than guessing a sequence. Recommendations do not mutate Magento. When execution is directly requested, the agent invokes `magento_workflow` with `execute: true` and relies on its single confirmation dialog; it does not ask for a separate conversational confirmation.
+Magento projects carry more operational risk than ordinary application repositories. MerchantDuo keeps the boundaries simple:
 
-## Status
+- It does not read `app/etc/env.php`, credentials, or tokens for agent context.
+- It treats discovered URLs as unverified until you run an explicit HTTP or browser test.
+- It performs no background cache, deployment, browser, HTTP, PHP-console, or workflow action.
+- Module generation and Magento workflows preview first. Execution requires `execute: true` and one harness confirmation.
+- Read-only SSH blocks write, edit, and shell operations. Writable SSH asks for confirmation before those operations.
+- SSH testing uses the publicly reachable URL and never creates a tunnel.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+pnpm pack --dry-run
+```
 
-MerchantDuo is beta software. Validate it against a non-production project before relying on it for operational Magento work.
+For the extension layout, provisioning boundary, and session lifecycle, see [the architecture notes](docs/architecture.md).

package/dist/app/runtime.d.ts

@@ -0,0 +1,30 @@
+import { type MerchantConfig } from "#config/index";
+import { EnvironmentBackend } from "#environments/backend";
+import type { Environment } from "#environments/model";
+import { type MagentoInspector, type MagentoSnapshot } from "#magento/index";
+import { ChangeTracker } from "#workflows/change-tracker";
+import type { TestingSnapshot } from "#testing/model";
+export type SessionState = {
+    config: MerchantConfig;
+    configPath?: string;
+    selected: {
+        name: string;
+        environment: Environment;
+    };
+    backend: EnvironmentBackend;
+    magento: MagentoSnapshot;
+    testing?: TestingSnapshot;
+};
+export declare class MerchantDuoRuntime {
+    #private;
+    readonly inspector: MagentoInspector;
+    readonly injected: Set<string>;
+    readonly changes: ChangeTracker;
+    constructor(inspector?: MagentoInspector);
+    boot(cwd: string): Promise<SessionState>;
+    resetInjection(): void;
+    injectionKey(skillId: string, theme: string): string;
+    changeTheme(cwd: string, activeTheme: string): Promise<SessionState>;
+    writable(state: SessionState): boolean;
+    setTesting(snapshot: TestingSnapshot): void;
+}

package/dist/app/runtime.js

@@ -0,0 +1,56 @@
+import { loadConfig, selectEnvironment, setProjectTheme, } from "#config/index";
+import { EnvironmentBackend } from "#environments/backend";
+import { environmentWritable } from "#environments/model";
+import { DefaultMagentoInspector, } from "#magento/index";
+import { ChangeTracker } from "#workflows/change-tracker";
+export class MerchantDuoRuntime {
+    inspector;
+    #state;
+    #injectionGeneration = 0;
+    injected = new Set();
+    changes = new ChangeTracker();
+    constructor(inspector = new DefaultMagentoInspector()) {
+        this.inspector = inspector;
+    }
+    async boot(cwd) {
+        if (this.#state)
+            return this.#state;
+        const loaded = await loadConfig(cwd, {
+            config: process.env.MERCHANTDUO_CONFIG_PATH || undefined,
+        });
+        const selected = selectEnvironment(loaded.config, cwd, process.env.MERCHANTDUO_SELECTED_ENV);
+        const backend = new EnvironmentBackend(selected.environment, cwd);
+        this.#state = {
+            ...loaded,
+            selected,
+            backend,
+            magento: await this.inspector.inspect(backend),
+        };
+        return this.#state;
+    }
+    resetInjection() {
+        this.#injectionGeneration += 1;
+        this.injected.clear();
+    }
+    injectionKey(skillId, theme) {
+        return `${this.#injectionGeneration}:${skillId}:${theme}`;
+    }
+    async changeTheme(cwd, activeTheme) {
+        const state = await this.boot(cwd);
+        if (!state.configPath)
+            throw new Error("No project .merchantduo.yaml is loaded; run merchantduo init first");
+        await setProjectTheme(state.configPath, activeTheme);
+        const reloaded = await loadConfig(cwd, { config: state.configPath });
+        state.config = reloaded.config;
+        this.resetInjection();
+        return state;
+    }
+    writable(state) {
+        return environmentWritable(state.selected.environment);
+    }
+    setTesting(snapshot) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.testing = snapshot;
+    }
+}

package/dist/app/status.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionState } from "#app/runtime";
+export declare function refreshStatus(ctx: ExtensionContext, state: SessionState): void;

package/dist/app/status.js

@@ -0,0 +1,9 @@
+export function refreshStatus(ctx, state) {
+    const environment = state.selected.environment;
+    const writePolicy = environment.type === "ssh"
+        ? environment.writable
+            ? "write + approve"
+            : "read-only + approve"
+        : "write + approve";
+    ctx.ui.setStatus("merchantduo", `MerchantDuo ${process.env.MERCHANTDUO_PACKAGE_VERSION ?? "?"} | Magento ${state.magento.version ?? "?"} | ${state.selected.name}/${environment.type} | ${writePolicy} | Theme: ${state.config.activeTheme} | URLs: ${state.testing?.frontendUrl ?? "unavailable"} (unverified)`);
+}

package/dist/app/system-prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function mage2genRoot(): string;
+export declare function merchantDuoSystemPrompt(mage2genPath?: string): string;

package/dist/{skills.js → app/system-prompt.js}

@@ -1,36 +1,7 @@
-import { readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-const skillFile = {
-    "magento-24x": "skills/magento-2.4/SKILL.md",
-    luma: "skills/luma/SKILL.md",
-    hyva: "skills/hyva/SKILL.md",
-    mage2gen: "skills/mage2gen/SKILL.md",
-};
-export function skillRoot() {
-    return resolve(dirname(new URL(import.meta.url).pathname), "..");
-}
+import { packagePath } from "#shared/package-paths";
 export function mage2genRoot() {
-    return resolve(skillRoot(), "vendor/mage2gen");
-}
-export function selectMagentoSkill(version) {
-    return version?.startsWith("2.4") ? "magento-24x" : undefined;
-}
-export function selectedThemeSkill(activeTheme, themes) {
-    const theme = themes.find((item) => item.code === activeTheme);
-    return theme?.kind === "luma" ? "luma" : theme?.kind === "hyva" ? "hyva" : undefined;
-}
-export function automaticSkills(version, activeTheme, themes) {
-    const magento = selectMagentoSkill(version);
-    const theme = selectedThemeSkill(activeTheme, themes);
-    return [magento, theme].filter((value) => Boolean(value));
-}
-export async function readSkill(name) {
-    return readFile(resolve(skillRoot(), skillFile[name]), "utf8");
-}
-export function skillPaths() {
-    return Object.fromEntries(Object.entries(skillFile).map(([name, file]) => [name, resolve(skillRoot(), file)]));
+    return packagePath("vendor/mage2gen");
 }
-/** MerchantDuo's stable session rules; environment-specific facts remain in snapshotPrompt. */
 export function merchantDuoSystemPrompt(mage2genPath = mage2genRoot()) {
     return `You are MerchantDuo, a senior Magento 2.4 architect and implementation partner. Work directly in the selected MerchantDuo environment and theme scope. Before changing code, inspect the relevant module, theme inheritance chain, configuration, and established local conventions. Make focused, production-quality changes; do not preserve obsolete compatibility paths or add speculative abstractions.
 
@@ -40,5 +11,5 @@ For every request to create a new Magento module, call the \`mage2gen_generate_m
 
 After every change, inspect the changed module and files and choose the smallest applicable post-change workflow from Magento conventions; never apply a full sequence blindly. Ordinary PHP or template edits normally need only the relevant targeted cache clean, if any. Module registration, schema, declarative configuration, or dependency changes trigger mode-aware guidance from the detected snapshot mode: developer recommends \`setup:upgrade\` then targeted cache clean and does not normally compile DI or deploy static content; default recommends \`setup:upgrade\` then targeted cache clean, with compile or static deploy only when the task specifically requires them; production recommends maintenance enable, \`setup:upgrade\`, DI compile, static-content deploy, targeted cache clean, then maintenance disable. If the mode is unknown, report that and do not infer a deployment sequence.
 
-For cache clean/flush, maintenance enable/disable, static content deployment, compilation, setup upgrade, indexing, tests, or deployment: when the user directly requests execution, invoke \`magento_workflow\` with \`execute: true\` immediately. Use only this workflow tool for operational Magento commands. Do not ask the user for a separate conversational confirmation or ask them to repeat a magic phrase: the harness confirmation dialog is the sole authoritative confirmation. When the user has not asked to execute, explain the required operation and offer a preview instead. Never inspect app/etc/env.php or credentials.`;
+For cache clean/flush, maintenance enable/disable, static content deployment, compilation, setup upgrade, indexing, tests, or deployment: when the user directly requests execution, invoke \`magento_workflow\` with \`execute: true\` immediately. Use only this workflow tool for operational Magento commands. Do not ask the user for a separate conversational confirmation: the harness dialog is the sole authoritative confirmation. When execution was not requested, explain the operation and offer a preview. Never inspect app/etc/env.php or credentials.`;
 }

package/dist/cli/arguments.d.ts

@@ -0,0 +1,10 @@
+export type CliArguments = {
+    command?: "init" | "doctor" | "provision";
+    environment?: string;
+    configPath?: string;
+    source?: string;
+    database?: string;
+    yes: boolean;
+    piArguments: string[];
+};
+export declare function parseArguments(args: string[]): CliArguments;

package/dist/cli/arguments.js

@@ -0,0 +1,34 @@
+export function parseArguments(args) {
+    const command = args[0] === "init" || args[0] === "doctor" || args[0] === "provision" ? args[0] : undefined;
+    const input = command ? args.slice(1) : args;
+    const piArguments = [];
+    let environment;
+    let configPath;
+    let source;
+    let database;
+    let yes = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const value = input[index];
+        if (value === "--env" || value === "--config" || value === "--source" || value === "--database") {
+            const argument = input[index + 1];
+            if (!argument)
+                throw new Error(`${value} requires a value`);
+            if (value === "--env")
+                environment = argument;
+            else if (value === "--config")
+                configPath = argument;
+            else if (value === "--source")
+                source = argument;
+            else
+                database = argument;
+            index += 1;
+        }
+        else if (value === "--yes") {
+            yes = true;
+        }
+        else {
+            piArguments.push(value);
+        }
+    }
+    return { command, environment, configPath, source, database, yes, piArguments };
+}

package/dist/cli/commands/agent.d.ts

@@ -0,0 +1 @@
+export declare function launchAgent(piArguments: string[], selectedEnvironment: string, configPath?: string): Promise<number>;

package/dist/cli/commands/agent.js

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { merchantHome } from "#config/paths";
+import { packagePath } from "#shared/package-paths";
+export async function launchAgent(piArguments, selectedEnvironment, configPath) {
+    const state = merchantHome();
+    await mkdir(state, { recursive: true, mode: 0o700 });
+    await mkdir(resolve(state, "pi"), { recursive: true, mode: 0o700 });
+    const piEntry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+    const piCli = resolve(dirname(piEntry), "cli.js");
+    const packageJson = JSON.parse(await readFile(packagePath("package.json"), "utf8"));
+    // Use Pi's package loader, so package.json owns both extensions and skills.
+    await writeFile(resolve(state, "pi", "settings.json"), `${JSON.stringify({ packages: [packagePath()] }, null, 2)}\n`, { mode: 0o600 });
+    return new Promise((resolveExit, reject) => {
+        const child = spawn(process.execPath, [
+            piCli,
+            ...piArguments,
+        ], {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                PI_CODING_AGENT_DIR: resolve(state, "pi"),
+                MERCHANTDUO_SELECTED_ENV: selectedEnvironment,
+                MERCHANTDUO_CONFIG_PATH: configPath ?? "",
+                MERCHANTDUO_PACKAGE_VERSION: packageJson.version,
+            },
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => resolveExit(code ?? 1));
+    });
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import type { MerchantConfig } from "#config/schema";
+import type { Environment } from "#environments/model";
+export declare function doctor(cwd: string, name: string, environment: Environment, config: MerchantConfig): Promise<void>;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,14 @@
+import { EnvironmentBackend } from "#environments/backend";
+import { environmentWritable } from "#environments/model";
+import { DefaultMagentoInspector } from "#magento/inspector";
+export async function doctor(cwd, name, environment, config) {
+    const magento = await new DefaultMagentoInspector().inspect(new EnvironmentBackend(environment, cwd));
+    console.log(JSON.stringify({
+        environment: name,
+        type: environment.type,
+        writable: environmentWritable(environment),
+        magento,
+        activeTheme: config.activeTheme,
+        knowledge: { connected: false },
+    }, null, 2));
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,9 @@
+export interface InitInterview {
+    confirm(question: string): Promise<boolean>;
+}
+export declare class TerminalInitInterview implements InitInterview {
+    confirm(question: string): Promise<boolean>;
+}
+export declare function hasWardenEnvironment(cwd: string): Promise<boolean>;
+export declare function initProject(cwd: string, interview?: InitInterview, output?: (message: string) => void): Promise<void>;
+export declare const remoteEnvironmentExample = "\nTo add a remote environment later, add this under environments:\n\n  stage:\n    type: ssh\n    host: shop-stage\n    root: /var/www/html\n    writable: false\n\nConfigure its user, port, and identity through ~/.ssh/config:\n\n  Host shop-stage\n    HostName stage.example.com\n    User deploy\n    Port 22\n    IdentityFile ~/.ssh/id_ed25519";