@merchantduo/code 0.2.0-beta.2 → 0.2.0-beta.4

package/README.md

@@ -1,66 +1,27 @@
 # MerchantDuo
 
-MerchantDuo is a Pi coding agent for Magento teams that works from the store's real environment, Magento version, deployment mode, and theme context.
+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.
 
-## Main features
+## Overview
 
-- 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
+- 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, and testing skills.
+- Provides guided local/Warden store provisioning.
+- Keeps remote writes and Magento operations behind explicit execution boundaries.
 
-## Details
+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 MerchantDuo and Magento versions, environment lifecycle, session permission mode, an explicit theme scope when one is selected, and the frontend URL when available.
 
-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.
+## Commands and tools
 
-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.
+Extension slash commands are namespaced with `duo-` to avoid collisions with other Pi extensions.
 
-MerchantDuo is currently beta software for development teams.
+- [Command reference](docs/commands.md) covers session theme and permission switching, lifecycle, and navigation commands.
+- [Tool reference](docs/tools.md) covers workspace, environment, Magento workflow, magerun2, testing, PHP-console, and optional knowledge tools, including parameters and confirmation boundaries.
 
-## What agencies get
+## Environments
 
-- 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.
-
-The result is less time re-explaining a store to an agent and fewer generic recommendations that do not fit Magento.
-
-## Magento context before the first change
-
-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:
-
-- 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
-
-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.
-
-## Curated Magento knowledge
-
-MerchantDuo ships focused Pi skills instead of relying on broad, generic instructions:
-
-- `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.
-
-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.
-
-## Environments that match agency work
-
-Define the environments your team actually uses in `.merchantduo.yaml`, then select one at launch with `--env`.
+Define the environments your team uses in `.merchantduo.yaml`, then select one at launch with `--env`.
 
 ```yaml
 defaultEnvironment: local
@@ -85,12 +46,9 @@ environments:
     type: ssh
     host: shop-stage
     root: /var/www/html
-    writable: false
 ```
 
-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.
-
-For SSH user names, ports, and identities, use an OpenSSH alias rather than extra YAML keys:
+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`. Use `/duo-switch-permissions <read-only|normal|yolo>` to change only the current session, or `merchantduo --yolo` to start in `yolo`. Configure SSH user, port, and key through an OpenSSH host alias:
 
 ```sshconfig
 Host shop-stage
@@ -100,89 +58,37 @@ Host shop-stage
   IdentityFile ~/.ssh/id_ed25519
 ```
 
-Use the alias as `host: shop-stage` in `.merchantduo.yaml`.
+Use that alias as `host: shop-stage`. `merchantduo init` offers local first and Warden when its project `.env` is detected; it prints an SSH example instead of writing an unused remote environment.
 
-`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.
+## Provisioning
 
-## Provision a developer store
-
-Run provisioning from an empty directory or an existing Magento project:
+Provision a local or Warden developer store from an empty directory or an existing Magento checkout:
 
 ```sh
 merchantduo provision
 merchantduo provision --env warden --source https://git.example.test/store.git --database ./backup.sql.gz --yes
 ```
 
-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.
-
-With `--yes`, every decision must already be explicit or unambiguous. The command fails rather than guessing a source, database, web server, or environment.
-
-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.
-
-Input precedence is command flags, then a discovered Magento checkout or the only SQL dump in the project root, then the interactive interview.
-
-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.
-
-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.
-
-## Tools that respect Magento boundaries
-
-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. |
-
-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.
-
-## Magento workflows without blind deployment commands
-
-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 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.
+The interactive flow discovers available source, database, and service evidence, shows an ordered plan, and asks once before mutations. `--yes` requires all decisions to be explicit or unambiguous.
 
 ## 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:
+MerchantDuo requires Node.js 22.19 or later, Bash, and Python 3. HTTP/browser testing additionally needs curl and Chrome or Chromium; Warden and SSH environments need Warden and OpenSSH respectively.
 
 ```sh
+pnpm install --frozen-lockfile
 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.
+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.
 
-## Safety model
+## Safety and optional services
 
-Magento projects carry more operational risk than ordinary application repositories. MerchantDuo keeps the boundaries simple:
+MerchantDuo does not load `app/etc/env.php`, credentials, or tokens into agent context. It 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).
 
-- 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.
+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
 
@@ -190,7 +96,7 @@ Magento projects carry more operational risk than ordinary application repositor
 pnpm install --frozen-lockfile
 pnpm check
 pnpm test
-pnpm pack --dry-run
+npm pack --dry-run
 ```
 
 For the extension layout, provisioning boundary, and session lifecycle, see [the architecture notes](docs/architecture.md).

package/dist/app/permission-mode.d.ts

@@ -0,0 +1,5 @@
+import type { Environment } from "#environments/model";
+export declare const permissionModes: readonly ["read-only", "normal", "yolo"];
+export type PermissionMode = (typeof permissionModes)[number];
+/** Resolve one non-persistent session policy. Invalid launch input is rejected, never relaxed. */
+export declare function resolvePermissionMode(environment: Environment, override?: string): PermissionMode;

package/dist/app/permission-mode.js

@@ -0,0 +1,10 @@
+export const permissionModes = ["read-only", "normal", "yolo"];
+/** Resolve one non-persistent session policy. Invalid launch input is rejected, never relaxed. */
+export function resolvePermissionMode(environment, override) {
+    if (override !== undefined) {
+        if (!permissionModes.includes(override))
+            throw new Error(`Invalid MERCHANTDUO_PERMISSION_MODE: ${override}. Expected read-only, normal, or yolo.`);
+        return override;
+    }
+    return environment.type === "ssh" ? "read-only" : "normal";
+}

package/dist/app/runtime.d.ts

@@ -1,9 +1,12 @@
 import { type MerchantConfig } from "#config/index";
 import { EnvironmentBackend } from "#environments/backend";
 import type { Environment } from "#environments/model";
+import { type PermissionMode } from "#app/permission-mode";
+import type { EnvironmentStatus } from "#environments/model";
 import { type MagentoInspector, type MagentoSnapshot } from "#magento/index";
 import { ChangeTracker } from "#workflows/change-tracker";
 import type { TestingSnapshot } from "#testing/model";
+import type { Magerun2Capability } from "#features/magerun2/index";
 export type SessionState = {
     config: MerchantConfig;
     configPath?: string;
@@ -12,8 +15,11 @@ export type SessionState = {
         environment: Environment;
     };
     backend: EnvironmentBackend;
+    environmentStatus: EnvironmentStatus;
+    permissionMode: PermissionMode;
     magento: MagentoSnapshot;
     testing?: TestingSnapshot;
+    magerun2?: Magerun2Capability;
 };
 export declare class MerchantDuoRuntime {
     #private;
@@ -25,6 +31,10 @@ export declare class MerchantDuoRuntime {
     resetInjection(): void;
     injectionKey(skillId: string, theme: string): string;
     changeTheme(cwd: string, activeTheme: string): Promise<SessionState>;
-    writable(state: SessionState): boolean;
+    setPermissionMode(mode: PermissionMode): SessionState;
     setTesting(snapshot: TestingSnapshot): void;
+    setMagerun2(capability: Magerun2Capability): void;
+    setEnvironmentStatus(status: EnvironmentStatus): SessionState;
+    startEnvironment(cwd: string): Promise<SessionState>;
+    stopEnvironment(cwd: string): Promise<SessionState>;
 }

package/dist/app/runtime.js

@@ -1,6 +1,6 @@
 import { loadConfig, selectEnvironment, setProjectTheme, } from "#config/index";
 import { EnvironmentBackend } from "#environments/backend";
-import { environmentWritable } from "#environments/model";
+import { resolvePermissionMode } from "#app/permission-mode";
 import { DefaultMagentoInspector, } from "#magento/index";
 import { ChangeTracker } from "#workflows/change-tracker";
 export class MerchantDuoRuntime {
@@ -20,11 +20,14 @@ export class MerchantDuoRuntime {
         });
         const selected = selectEnvironment(loaded.config, cwd, process.env.MERCHANTDUO_SELECTED_ENV);
         const backend = new EnvironmentBackend(selected.environment, cwd);
+        const environmentStatus = await backend.status();
         this.#state = {
             ...loaded,
             selected,
             backend,
-            magento: await this.inspector.inspect(backend),
+            environmentStatus,
+            permissionMode: resolvePermissionMode(selected.environment, process.env.MERCHANTDUO_PERMISSION_MODE),
+            magento: environmentStatus === "running" ? await this.inspector.inspect(backend) : stoppedMagentoSnapshot(),
         };
         return this.#state;
     }
@@ -45,12 +48,57 @@ export class MerchantDuoRuntime {
         this.resetInjection();
         return state;
     }
-    writable(state) {
-        return environmentWritable(state.selected.environment);
+    setPermissionMode(mode) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.permissionMode = mode;
+        return this.#state;
     }
     setTesting(snapshot) {
         if (!this.#state)
             throw new Error("Session has not started");
         this.#state.testing = snapshot;
     }
+    setMagerun2(capability) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.magerun2 = capability;
+    }
+    setEnvironmentStatus(status) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.environmentStatus = status;
+        if (status === "stopped") {
+            this.#state.magento = stoppedMagentoSnapshot();
+            this.#state.testing = undefined;
+            this.#state.magerun2 = undefined;
+        }
+        return this.#state;
+    }
+    async startEnvironment(cwd) {
+        const state = await this.boot(cwd);
+        const result = await state.backend.start();
+        if (result && result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || "Could not start environment");
+        state.environmentStatus = await state.backend.status();
+        if (state.environmentStatus === "running")
+            state.magento = await this.inspector.inspect(state.backend);
+        return state;
+    }
+    async stopEnvironment(cwd) {
+        const state = await this.boot(cwd);
+        const result = await state.backend.stop();
+        if (result && result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || "Could not stop environment");
+        state.environmentStatus = await state.backend.status();
+        if (state.environmentStatus === "stopped") {
+            state.magento = stoppedMagentoSnapshot();
+            state.testing = undefined;
+            state.magerun2 = undefined;
+        }
+        return state;
+    }
+}
+function stoppedMagentoSnapshot() {
+    return { cacheTypes: [], warnings: ["Environment is stopped"], evidence: [], themes: [] };
 }

package/dist/app/status.js

@@ -1,9 +1,11 @@
 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)`);
+    const parts = [
+        `MerchantDuo ${process.env.MERCHANTDUO_PACKAGE_VERSION ?? "?"}`,
+        `M${state.magento.version ?? "?"}`,
+        `${state.selected.name} (${state.environmentStatus})`,
+        state.permissionMode === "read-only" ? "r-o" : state.permissionMode,
+        ...(state.config.activeTheme === "all" ? [] : [state.config.activeTheme]),
+        ...(state.testing?.frontendUrl ? [state.testing.frontendUrl] : []),
+    ];
+    ctx.ui.setStatus("merchantduo", parts.join(" · "));
 }

package/dist/app/system-prompt.js

@@ -11,5 +11,11 @@ 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: 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.`;
+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.
+
+Session permission mode is shown in the startup context and can be changed only with \`/duo-switch-permissions read-only|normal|yolo\`. Read-only blocks direct write/edit but an approved shell or explicit operation may still mutate. Normal retains ordinary local/Warden direct workspace behavior and SSH confirmations. Yolo removes MerchantDuo dialogs only; it never removes the explicit \`execute: true\` boundary, stopped-environment block, SSH lifecycle restriction, Mage2Gen SSH restriction, remote workflow restriction, PHP-console boundary, or credential and URL protections.
+
+For a supported cache, deploy, indexing, or test operation, prefer \`magento_workflow\`. For a different n98-magerun2 subcommand, use \`magerun2\` with an exact \`args: string[]\` vector, never a shell command or interpolation. When the user did not directly request execution, return its preview without \`execute: true\`; an executed generic magerun2 call requires \`execute: true\` and uses the same sole harness confirmation. Never send \`dev:console\` through \`magerun2\`: use the typed \`magento_php_repl\` tool instead.
+
+Environment lifecycle is explicit. Warden has known direct controls. SSH is always reported running and must never be started, stopped, or restarted. A local environment is agent-directed: when the user requests a start or stop, inspect the actual project lifecycle first, then call \`environment_start\` or \`environment_stop\` with the exact smallest command. Never guess a generic Docker, Compose, npm, or service command, and never affect unrelated host services. Use \`environment_set_status\` after a status inspection that does not itself start or stop the stack. Never inspect app/etc/env.php or credentials.`;
 }

package/dist/cli/arguments.d.ts

@@ -5,6 +5,7 @@ export type CliArguments = {
     source?: string;
     database?: string;
     yes: boolean;
+    yolo: boolean;
     piArguments: string[];
 };
 export declare function parseArguments(args: string[]): CliArguments;

package/dist/cli/arguments.js

@@ -7,6 +7,7 @@ export function parseArguments(args) {
     let source;
     let database;
     let yes = false;
+    let yolo = false;
     for (let index = 0; index < input.length; index += 1) {
         const value = input[index];
         if (value === "--env" || value === "--config" || value === "--source" || value === "--database") {
@@ -26,9 +27,14 @@ export function parseArguments(args) {
         else if (value === "--yes") {
             yes = true;
         }
+        else if (value === "--yolo") {
+            yolo = true;
+        }
         else {
             piArguments.push(value);
         }
     }
-    return { command, environment, configPath, source, database, yes, piArguments };
+    if (command && yolo)
+        throw new Error("--yolo is only available when starting an agent session");
+    return { command, environment, configPath, source, database, yes, yolo, piArguments };
 }

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

@@ -1 +1,3 @@
-export declare function launchAgent(piArguments: string[], selectedEnvironment: string, configPath?: string): Promise<number>;
+import type { PermissionMode } from "#app/permission-mode";
+export declare function launchAgent(piArguments: string[], selectedEnvironment: string, configPath?: string, permissionMode?: PermissionMode): Promise<number>;
+export declare function agentEnvironment(base: NodeJS.ProcessEnv, piDirectory: string, selectedEnvironment: string, configPath: string | undefined, version: string, permissionMode?: PermissionMode): NodeJS.ProcessEnv;

package/dist/cli/commands/agent.js

@@ -4,7 +4,7 @@ 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) {
+export async function launchAgent(piArguments, selectedEnvironment, configPath, permissionMode) {
     const state = merchantHome();
     await mkdir(state, { recursive: true, mode: 0o700 });
     await mkdir(resolve(state, "pi"), { recursive: true, mode: 0o700 });
@@ -19,15 +19,12 @@ export async function launchAgent(piArguments, selectedEnvironment, configPath)
             ...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,
-            },
+            env: agentEnvironment(process.env, resolve(state, "pi"), selectedEnvironment, configPath, packageJson.version, permissionMode),
         });
         child.on("error", reject);
         child.on("exit", (code) => resolveExit(code ?? 1));
     });
 }
+export function agentEnvironment(base, piDirectory, selectedEnvironment, configPath, version, permissionMode) {
+    return { ...base, PI_CODING_AGENT_DIR: piDirectory, MERCHANTDUO_SELECTED_ENV: selectedEnvironment, MERCHANTDUO_CONFIG_PATH: configPath ?? "", MERCHANTDUO_PACKAGE_VERSION: version, ...(permissionMode ? { MERCHANTDUO_PERMISSION_MODE: permissionMode } : {}) };
+}

package/dist/cli/commands/doctor.js

@@ -1,12 +1,12 @@
 import { EnvironmentBackend } from "#environments/backend";
-import { environmentWritable } from "#environments/model";
+import { resolvePermissionMode } from "#app/permission-mode";
 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),
+        defaultPermissionMode: resolvePermissionMode(environment),
         magento,
         activeTheme: config.activeTheme,
         knowledge: { connected: false },

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

@@ -6,4 +6,4 @@ export declare class TerminalInitInterview implements InitInterview {
 }
 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";
+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\nSSH sessions start read-only. Use /duo-switch-permissions normal or yolo only for the current session. Configure 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";

package/dist/cli/commands/init.js

@@ -65,4 +65,4 @@ export async function initProject(cwd, interview = new TerminalInitInterview(),
     output(`Created ${path}`);
     output(remoteEnvironmentExample);
 }
-export 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`;
+export 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\nSSH sessions start read-only. Use /duo-switch-permissions normal or yolo only for the current session. Configure 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`;

package/dist/cli/main.js

@@ -23,7 +23,7 @@ async function main() {
     }
     if (args.command === "doctor")
         return doctor(cwd, selected.name, selected.environment, loaded.config);
-    process.exitCode = await launchAgent(args.piArguments, selected.name, loaded.configPath);
+    process.exitCode = await launchAgent(args.piArguments, selected.name, loaded.configPath, args.yolo ? "yolo" : undefined);
 }
 main().catch((error) => {
     console.error(`merchantduo: ${error.message}`);

package/dist/config/schema.d.ts

@@ -93,7 +93,6 @@ export declare const ConfigSchema: z.ZodObject<{
         type: z.ZodLiteral<"ssh">;
         host: z.ZodString;
         root: z.ZodString;
-        writable: z.ZodDefault<z.ZodBoolean>;
         testing: z.ZodOptional<z.ZodObject<{
             frontendUrl: z.ZodOptional<z.ZodString>;
             adminUrl: z.ZodOptional<z.ZodString>;
@@ -111,7 +110,6 @@ export declare const ConfigSchema: z.ZodObject<{
         type: "ssh";
         root: string;
         host: string;
-        writable: boolean;
         testing?: {
             allowInsecureTls: boolean;
             frontendUrl?: string | undefined;
@@ -126,7 +124,6 @@ export declare const ConfigSchema: z.ZodObject<{
             adminUrl?: string | undefined;
             allowInsecureTls?: boolean | undefined;
         } | undefined;
-        writable?: boolean | undefined;
     }>]>>>;
 }, "strict", z.ZodTypeAny, {
     testing: {
@@ -158,7 +155,6 @@ export declare const ConfigSchema: z.ZodObject<{
         type: "ssh";
         root: string;
         host: string;
-        writable: boolean;
         testing?: {
             allowInsecureTls: boolean;
             frontendUrl?: string | undefined;
@@ -202,7 +198,6 @@ export declare const ConfigSchema: z.ZodObject<{
             adminUrl?: string | undefined;
             allowInsecureTls?: boolean | undefined;
         } | undefined;
-        writable?: boolean | undefined;
     }> | undefined;
 }>;
 export type MerchantConfig = Omit<z.infer<typeof ConfigSchema>, "environments"> & {

package/dist/config/schema.js

@@ -22,7 +22,6 @@ const ssh = z
     type: z.literal("ssh"),
     host: z.string().min(1),
     root: z.string(),
-    writable: z.boolean().default(false),
     testing: testing.optional(),
 })
     .strict();

package/dist/environments/adapter.d.ts

@@ -2,4 +2,5 @@ import type { CommandSpec } from "#environments/executor";
 export interface EnvironmentAdapter {
     path(path: string): string;
     command(argv: string[], target?: string): CommandSpec;
+    lifecycleCommand?(action: "status" | "start" | "stop"): CommandSpec;
 }

package/dist/environments/adapters/warden.d.ts

@@ -10,4 +10,9 @@ export declare class WardenAdapter implements EnvironmentAdapter {
         args: string[];
         cwd: string;
     };
+    lifecycleCommand(action: "status" | "start" | "stop"): {
+        file: string;
+        args: string[];
+        cwd: string;
+    };
 }

package/dist/environments/adapters/warden.js

@@ -21,4 +21,11 @@ export class WardenAdapter {
             cwd: resolve(this.cwd, this.environment.projectRoot),
         };
     }
+    lifecycleCommand(action) {
+        // Lifecycle commands run on the host in the Warden project, never in php-fpm.
+        const actionArgs = action === "status"
+            ? ["env", "ps", "--status", "running", "--services"]
+            : ["env", action];
+        return { file: "warden", args: actionArgs, cwd: resolve(this.cwd, this.environment.projectRoot) };
+    }
 }

package/dist/environments/backend.d.ts

@@ -1,4 +1,5 @@
 import type { Environment } from "#environments/model";
+import type { EnvironmentStatus } from "#environments/model";
 import type { CommandExecutor, CommandResult, CommandSpec, RunOptions } from "#environments/executor";
 export { contain } from "#environments/path-policy";
 /** Concrete local/Warden/SSH command adapter selected once for a session. */
@@ -10,4 +11,10 @@ export declare class EnvironmentBackend implements CommandExecutor {
     path(path: string): string;
     command(argv: string[], target?: string): CommandSpec;
     run(argv: string[], options?: RunOptions): Promise<CommandResult>;
+    lifecycleCommand(action: "status" | "start" | "stop"): CommandSpec | undefined;
+    status(): Promise<EnvironmentStatus>;
+    start(): Promise<CommandResult | undefined>;
+    stop(): Promise<CommandResult | undefined>;
 }
+/** `warden env ps --status running --services` prints one service per running container. */
+export declare function wardenRunning(stdout: string): boolean;