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

package/dist/environments/backend.js

@@ -22,6 +22,33 @@ export class EnvironmentBackend {
     }
     async run(argv, options = {}) {
         const spec = this.command(argv, options.target);
+        return this.#runSpec(spec, options);
+    }
+    lifecycleCommand(action) {
+        return this.#adapter.lifecycleCommand?.(action);
+    }
+    async status() {
+        if (this.environment.type === "ssh")
+            return "running";
+        if (this.environment.type === "local")
+            return "unknown";
+        const spec = this.lifecycleCommand("status");
+        if (!spec)
+            return "stopped";
+        const output = await this.#runSpec(spec);
+        return output.exitCode === 0 && wardenRunning(output.stdout) ? "running" : "stopped";
+    }
+    async start() {
+        return this.#lifecycle("start");
+    }
+    async stop() {
+        return this.#lifecycle("stop");
+    }
+    async #lifecycle(action) {
+        const spec = this.lifecycleCommand(action);
+        return spec ? this.#runSpec(spec) : undefined;
+    }
+    #runSpec(spec, options = {}) {
         return new Promise((resolveResult) => {
             const child = spawn(spec.file, spec.args, {
                 cwd: spec.cwd,
@@ -71,3 +98,7 @@ export class EnvironmentBackend {
         });
     }
 }
+/** `warden env ps --status running --services` prints one service per running container. */
+export function wardenRunning(stdout) {
+    return stdout.split("\n").some((line) => line.trim().length > 0);
+}

package/dist/environments/model.d.ts

@@ -3,6 +3,8 @@ type EnvironmentTesting = {
     adminUrl?: string;
     allowInsecureTls?: boolean;
 };
+/** Unknown is valid for a local stack until the agent has identified its actual lifecycle. */
+export type EnvironmentStatus = "running" | "stopped" | "unknown";
 export type LocalEnvironment = {
     type: "local";
     root: string;
@@ -20,9 +22,7 @@ export type SshEnvironment = {
     type: "ssh";
     host: string;
     root: string;
-    writable: boolean;
     testing?: EnvironmentTesting;
 };
 export type Environment = LocalEnvironment | WardenEnvironment | SshEnvironment;
-export declare function environmentWritable(environment: Environment): boolean;
 export {};

package/dist/environments/model.js

@@ -1,3 +1 @@
-export function environmentWritable(environment) {
-    return environment.type !== "ssh" || environment.writable;
-}
+export {};

package/dist/features/magerun2/index.d.ts

@@ -0,0 +1,2 @@
+export * from "#features/magerun2/model";
+export * from "#features/magerun2/service";

package/dist/features/magerun2/index.js

@@ -0,0 +1,2 @@
+export * from "#features/magerun2/model";
+export * from "#features/magerun2/service";

package/dist/features/magerun2/model.d.ts

@@ -0,0 +1,10 @@
+export type Magerun2Capability = {
+    available: boolean;
+    executable?: string;
+    diagnostic?: string;
+};
+export type Magerun2Result = {
+    output: string;
+    exitCode: number;
+    truncated: boolean;
+};

package/dist/features/magerun2/model.js

@@ -0,0 +1 @@
+export {};

package/dist/features/magerun2/service.d.ts

@@ -0,0 +1,12 @@
+import type { EnvironmentBackend } from "#environments/backend";
+import type { Environment } from "#environments/model";
+import { type HostProcessRunner } from "#testing/host";
+import type { Magerun2Capability, Magerun2Result } from "#features/magerun2/model";
+/** Resolve magerun once for the selected Magento environment without altering the project. */
+export declare function discoverMagerun2(environment: Environment, backend: EnvironmentBackend, cwd: string): Promise<Magerun2Capability>;
+/** Run a structured argument vector. Local commands are host processes; Warden and SSH use their selected backend. */
+export declare function runMagerun2(capability: Magerun2Capability, environment: Environment, backend: EnvironmentBackend, cwd: string, args: string[], stdin?: string, signal?: AbortSignal, host?: HostProcessRunner): Promise<Magerun2Result>;
+/** Stable display only: this is never passed to a shell. */
+export declare function quotedMagerunPreview(executable: string, args: string[]): string;
+/** Install the official PHAR outside the Magento project; verify its release SHA-256 before publishing it. */
+export declare function installMagerun2(home: string, _cwd: string, request?: typeof fetch): Promise<string>;

package/dist/{testing/magerun.js → features/magerun2/service.js}

@@ -2,30 +2,53 @@ import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promise
 import { join } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { merchantHome } from "#config/paths";
+import { NodeHostProcessRunner } from "#testing/host";
 const RELEASE_URL = "https://api.github.com/repos/netz98/n98-magerun2/releases/latest";
-export async function discoverMagerun(environment, backend, cwd) {
+const MAX_OUTPUT = 64 * 1024;
+/** Resolve magerun once for the selected Magento environment without altering the project. */
+export async function discoverMagerun2(environment, backend, cwd) {
     if (environment.type === "warden")
-        return { executable: "/usr/local/bin/mr" };
+        return { available: true, executable: "/usr/local/bin/mr" };
     const candidates = environment.type === "local"
         ? ["vendor/bin/n98-magerun2", "bin/n98-magerun2", "n98-magerun2", "magerun2"]
         : ["n98-magerun2", "magerun2"];
     for (const candidate of candidates) {
-        const result = await backend.run(["sh", "-lc", `command -v ${candidate} 2>/dev/null || test -x ${candidate} && printf '%s' ${candidate}`]);
+        const result = await backend.run(["sh", "-lc", `command -v -- ${candidate} 2>/dev/null || { test -x ${candidate} && printf '%s' ${candidate}; }`]);
         const executable = result.stdout.trim();
         if (executable)
-            return { executable };
+            return { available: true, executable };
     }
     if (environment.type === "ssh")
-        return { diagnostic: environment.writable ? "Install n98-magerun2 on the remote host to enable PHP REPL." : "PHP REPL is disabled for read-only SSH." };
+        return { available: false, diagnostic: "Install n98-magerun2 on the remote host." };
     try {
-        return { executable: await installMagerun(merchantHome(), cwd) };
+        return { available: true, executable: await installMagerun2(merchantHome(), cwd) };
     }
     catch (error) {
-        return { diagnostic: `Could not install n98-magerun2: ${error.message}` };
+        return { available: false, diagnostic: `Could not install n98-magerun2: ${error.message}` };
     }
 }
-/** Install the official PHAR outside the Magento project; verify the release API SHA-256 digest before publishing it. */
-export async function installMagerun(home, _cwd, request = fetch) {
+/** Run a structured argument vector. Local commands are host processes; Warden and SSH use their selected backend. */
+export async function runMagerun2(capability, environment, backend, cwd, args, stdin, signal, host = new NodeHostProcessRunner()) {
+    if (!capability.executable)
+        throw new Error(capability.diagnostic ?? "n98-magerun2 is unavailable.");
+    if (environment.type === "local") {
+        const command = backend.command([capability.executable, ...args]);
+        const result = await host.run(command.file, command.args, { cwd: command.cwd ?? cwd, signal, input: stdin });
+        return boundedResult(result.output, result.code, result.truncated);
+    }
+    const result = await backend.run([capability.executable, ...args], { input: stdin, signal });
+    return boundedResult(`${result.stdout}${result.stderr}`, result.exitCode, result.truncated);
+}
+/** Stable display only: this is never passed to a shell. */
+export function quotedMagerunPreview(executable, args) {
+    return [executable, ...args].map((value) => `'${value.replace(/'/g, "'\\''")}'`).join(" ");
+}
+function boundedResult(output, exitCode, alreadyTruncated = false) {
+    const truncated = alreadyTruncated || output.length > MAX_OUTPUT;
+    return { output: truncated ? `${output.slice(0, MAX_OUTPUT)}\n[output truncated]` : output, exitCode, truncated };
+}
+/** Install the official PHAR outside the Magento project; verify its release SHA-256 before publishing it. */
+export async function installMagerun2(home, _cwd, request = fetch) {
     const directory = join(home, "tools", "n98-magerun2");
     const destination = join(directory, "n98-magerun2.phar");
     const digestPath = `${destination}.sha256`;
@@ -49,11 +72,10 @@ export async function installMagerun(home, _cwd, request = fetch) {
     if (!phar.ok)
         throw new Error("official PHAR download failed");
     const bytes = new Uint8Array(await phar.arrayBuffer());
-    const actual = sha256(bytes);
-    if (!expected || actual !== expected)
+    if (sha256(bytes) !== expected)
         throw new Error("PHAR SHA-256 verification failed");
     const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
-    await BunOrNode.write(temporary, bytes);
+    await writeFile(temporary, bytes, { mode: 0o700, flag: "wx" });
     await chmod(temporary, 0o700);
     try {
         await rename(temporary, destination);
@@ -70,4 +92,3 @@ export async function installMagerun(home, _cwd, request = fetch) {
     return destination;
 }
 function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
-const BunOrNode = { async write(path, bytes) { const { writeFile } = await import("node:fs/promises"); await writeFile(path, bytes, { mode: 0o700, flag: "wx" }); } };

package/dist/integrations/pi/context.js

@@ -1,13 +1,20 @@
 import { refreshStatus } from "#app/status";
 import { merchantDuoSystemPrompt } from "#app/system-prompt";
-import { discoverTesting, discoverMagerun } from "#testing/index";
+import { discoverTesting } from "#testing/index";
+import { discoverMagerun2 } from "#features/magerun2/index";
 import { discoverHostExecutable } from "#testing/host";
 import { runtime, sessionEvents } from "#integrations/pi/session";
 export default function context(pi) {
     pi.on("session_start", async (_event, ctx) => {
         runtime.resetInjection();
         const state = await runtime.boot(ctx.cwd);
-        const magerun = await discoverMagerun(state.selected.environment, state.backend, ctx.cwd);
+        if (state.environmentStatus === "stopped") {
+            refreshStatus(ctx, state);
+            sessionEvents.emit("merchantduo.context", state);
+            pi.appendEntry("merchantduo.context", { environment: state.selected.name, environmentStatus: state.environmentStatus, permissionMode: state.permissionMode });
+            return;
+        }
+        const magerun2 = await discoverMagerun2(state.selected.environment, state.backend, ctx.cwd);
         // HTTP and Chromium deliberately run on the host against Warden's routed URL.
         // Do not use EnvironmentBackend here: its Warden adapter would probe php-fpm.
         // Prefer non-Snap Chrome: Snap Chromium cannot write MerchantDuo artifacts
@@ -16,12 +23,11 @@ export default function context(pi) {
             discoverHostExecutable(["curl"]),
             discoverHostExecutable(["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]),
         ]);
-        runtime.setTesting(await discoverTesting(state.selected.environment, state.backend, ctx.cwd, { ...state.config.testing, ...state.selected.environment.testing, allowInsecureTls: state.selected.environment.testing?.allowInsecureTls ?? state.config.testing.allowInsecureTls }, { http, browser, magerun: magerun.executable }));
-        if (magerun.diagnostic)
-            state.testing?.diagnostics.push(magerun.diagnostic);
+        runtime.setMagerun2(magerun2);
+        runtime.setTesting(await discoverTesting(state.selected.environment, state.backend, ctx.cwd, { ...state.config.testing, ...state.selected.environment.testing, allowInsecureTls: state.selected.environment.testing?.allowInsecureTls ?? state.config.testing.allowInsecureTls }, { http, browser }));
         refreshStatus(ctx, state);
         sessionEvents.emit("merchantduo.context", state);
-        pi.appendEntry("merchantduo.context", { environment: state.selected.name, testing: state.testing });
+        pi.appendEntry("merchantduo.context", { environment: state.selected.name, environmentStatus: state.environmentStatus, permissionMode: state.permissionMode, testing: state.testing, magerun2: state.magerun2 });
     });
     pi.on("session_compact", () => runtime.resetInjection());
     pi.on("session_shutdown", () => sessionEvents.clear());
@@ -41,6 +47,6 @@ export default function context(pi) {
     pi.on("before_agent_start", async (event, ctx) => {
         const state = await runtime.boot(ctx.cwd);
         const testing = state.testing;
-        return { systemPrompt: `${event.systemPrompt}\n${merchantDuoSystemPrompt()}\nTesting URLs are discovered but unverified. Frontend: ${testing?.frontendUrl ?? "unavailable"}; Admin: ${testing?.adminUrl ?? "unavailable"}. HTTP, browser, navigation, and test artifacts are host-only; never use environment bash to locate or repair their host paths. Use explicit test tools only when relevant.` };
+        return { systemPrompt: `${event.systemPrompt}\n${merchantDuoSystemPrompt()}\nEnvironment: ${state.selected.name} is ${state.environmentStatus}; permission mode=${state.permissionMode}. ${state.environmentStatus === "stopped" ? "Use environment_start only after the user directly asks to start it; do not use project tools until it is running." : "Testing URLs are discovered but unverified. Frontend: " + (testing?.frontendUrl ?? "unavailable") + "; Admin: " + (testing?.adminUrl ?? "unavailable") + ". HTTP, browser, navigation, and test artifacts are host-only; never use environment bash to locate or repair their host paths. Use explicit test tools only when relevant."}` };
     });
 }

package/dist/integrations/pi/environment.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Warden is managed directly; a local project's lifecycle is selected by the agent from live project evidence. */
+export default function environment(pi: ExtensionAPI): void;

package/dist/integrations/pi/environment.js

@@ -0,0 +1,64 @@
+import { Type } from "typebox";
+import { refreshStatus } from "#app/status";
+import { runtime, text } from "#integrations/pi/session";
+/** Warden is managed directly; a local project's lifecycle is selected by the agent from live project evidence. */
+export default function environment(pi) {
+    pi.registerTool({ name: "environment_status", label: "Environment status", description: "Report whether the selected MerchantDuo environment is running or stopped.", parameters: Type.Object({}), async execute(_id, _params, _signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_start", label: "Start environment", description: "Start Warden directly, or run the agent-selected local lifecycle command after inspection.", parameters: Type.Object({ command: Type.Optional(Type.String({ minLength: 1 })) }), async execute(_id, params, signal, _update, ctx) {
+            const state = await change("start", ctx.cwd, params.command, signal);
+            refreshStatus(ctx, state);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_stop", label: "Stop environment", description: "Stop Warden directly, or run the agent-selected local lifecycle command after inspection.", parameters: Type.Object({ command: Type.Optional(Type.String({ minLength: 1 })) }), async execute(_id, params, signal, _update, ctx) {
+            const state = await change("stop", ctx.cwd, params.command, signal);
+            refreshStatus(ctx, state);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_set_status", label: "Set environment status", description: "Record the local environment lifecycle status after inspecting or running its project-specific commands. Include concise command/output evidence.", parameters: Type.Object({ status: Type.Union([Type.Literal("running"), Type.Literal("stopped")]), evidence: Type.String({ minLength: 1 }) }), async execute(_id, params, _signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            if (state.selected.environment.type !== "local")
+                throw new Error("Only local environment status is agent-reported.");
+            refreshStatus(ctx, runtime.setEnvironmentStatus(params.status));
+            return text(`Local environment marked ${params.status}: ${params.evidence}`);
+        } });
+    registerCommand(pi, "duo-env-start", "start");
+    registerCommand(pi, "duo-env-stop", "stop");
+}
+function registerCommand(pi, name, action) {
+    pi.registerCommand(name, { description: `${action === "start" ? "Start" : "Stop"} the selected environment. Warden is direct; local is agent-directed.`, handler: async (_args, ctx) => {
+            const state = await runtime.boot(ctx.cwd);
+            if (state.selected.environment.type === "local") {
+                pi.sendUserMessage(localLifecyclePrompt(action));
+                ctx.ui.notify(`Asked the agent to ${action} the local environment from project evidence.`, "info");
+                return;
+            }
+            const changed = await change(action, ctx.cwd);
+            refreshStatus(ctx, changed);
+            ctx.ui.notify(environmentMessage(changed), "info");
+        } });
+}
+async function change(action, cwd, command, signal) {
+    const state = await runtime.boot(cwd);
+    if (state.selected.environment.type === "ssh")
+        throw new Error("SSH is always reported running; MerchantDuo never controls remote services.");
+    if (state.selected.environment.type === "local") {
+        if (!command)
+            throw new Error(`Inspect the local project first, then call environment_${action} with its exact lifecycle command.`);
+        const result = await state.backend.run(["sh", "-lc", command], { signal });
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || `Could not ${action} local environment`);
+        return runtime.setEnvironmentStatus(action === "start" ? "running" : "stopped");
+    }
+    return action === "start" ? runtime.startEnvironment(cwd) : runtime.stopEnvironment(cwd);
+}
+function localLifecyclePrompt(action) {
+    return `The user directly requested that you ${action} the selected local environment. This local stack is not assumed to use any one runtime. Inspect the project documentation, package scripts, Compose files, service configuration, and existing process state first. Determine the smallest correct ${action} command, explain the evidence and intended effect, then execute it through environment_${action} with the exact command. Do not use a generic command, do not stop unrelated host services, and if the project lifecycle cannot be determined safely, ask the user. After a successful command, the tool records ${action === "start" ? "running" : "stopped"}.`;
+}
+function environmentMessage(state) {
+    const environment = state.selected.environment;
+    const managed = environment.type === "warden" ? "Warden-managed" : environment.type === "local" ? "agent-directed" : "remote unmanaged";
+    return `${state.selected.name} (${environment.type}): ${state.environmentStatus} [${managed}]`;
+}

package/dist/integrations/pi/magerun2.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Generic magerun2 is intentionally separate from the typed PHP console. */
+export default function magerun2(pi: ExtensionAPI): void;
+export declare function magerun2Refusal(args: string[]): string | undefined;

package/dist/integrations/pi/magerun2.js

@@ -0,0 +1,35 @@
+import { Type } from "typebox";
+import { quotedMagerunPreview, runMagerun2 } from "#features/magerun2/index";
+import { runtime, text } from "#integrations/pi/session";
+/** Generic magerun2 is intentionally separate from the typed PHP console. */
+export default function magerun2(pi) {
+    pi.registerTool({
+        name: "magerun2",
+        label: "n98-magerun2",
+        description: "Preview or explicitly run one structured n98-magerun2 subcommand in the selected environment. Use magento_php_repl for dev:console.",
+        parameters: Type.Object({
+            args: Type.Array(Type.String(), { minItems: 1 }),
+            stdin: Type.Optional(Type.String()),
+            execute: Type.Optional(Type.Boolean()),
+        }),
+        async execute(_id, params, signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            const refusal = magerun2Refusal(params.args);
+            if (refusal)
+                return text(refusal);
+            const capability = state.magerun2;
+            if (!capability?.executable)
+                return text(capability?.diagnostic ?? "n98-magerun2 is unavailable.");
+            const preview = quotedMagerunPreview(capability.executable, params.args);
+            if (!params.execute)
+                return text(`Preview: ${preview}\nSet execute=true only after the user directly requests execution.`);
+            const result = await runMagerun2(capability, state.selected.environment, state.backend, ctx.cwd, params.args, params.stdin, signal);
+            return text(`Exit status: ${result.exitCode}${result.truncated ? " (output truncated)" : ""}\n${result.output}`);
+        },
+    });
+}
+export function magerun2Refusal(args) {
+    if (args.includes("dev:console"))
+        return "Refused: dev:console belongs to magento_php_repl, which accepts a typed snippet and optional area.";
+    return undefined;
+}

package/dist/integrations/pi/optional-services.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+/** Change these constants when MerchantDuo's hosted services change; never expose URL configuration. */
+export declare const KNOWLEDGE_MCP_BASE_URL = "https://merchantduo.invalid/mcp";
+export declare const MERCHANTDUO_LLM_BASE_URL = "https://merchantduo.invalid/v1";
+export declare const MERCHANTDUO_LLM_PROVIDER = "merchantduo";
+export declare const MERCHANTDUO_LLM_MODEL = "merchantduo-mock";
+export declare function mcpToken(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function llmProviderConfig(env?: NodeJS.ProcessEnv): ProviderConfig | undefined;
+export default function optionalServices(pi: ExtensionAPI): void;

package/dist/integrations/pi/optional-services.js

@@ -0,0 +1,79 @@
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { Type } from "typebox";
+import { text } from "#integrations/pi/session";
+/** Change these constants when MerchantDuo's hosted services change; never expose URL configuration. */
+export const KNOWLEDGE_MCP_BASE_URL = "https://merchantduo.invalid/mcp";
+export const MERCHANTDUO_LLM_BASE_URL = "https://merchantduo.invalid/v1";
+export const MERCHANTDUO_LLM_PROVIDER = "merchantduo";
+export const MERCHANTDUO_LLM_MODEL = "merchantduo-mock";
+export function mcpToken(env = process.env) {
+    return env.MERCHANTDUO_MCP_TOKEN || undefined;
+}
+export function llmProviderConfig(env = process.env) {
+    if (!env.MERCHANTDUO_LLM_TOKEN)
+        return undefined;
+    return {
+        name: "MerchantDuo",
+        baseUrl: MERCHANTDUO_LLM_BASE_URL,
+        apiKey: "$MERCHANTDUO_LLM_TOKEN",
+        api: "openai-completions",
+        models: [{
+                id: MERCHANTDUO_LLM_MODEL,
+                name: "MerchantDuo",
+                input: ["text"],
+                reasoning: false,
+                contextWindow: 32_768,
+                maxTokens: 4_096,
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            }],
+    };
+}
+async function withKnowledgeClient(token, run) {
+    const transport = new StreamableHTTPClientTransport(new URL(KNOWLEDGE_MCP_BASE_URL), {
+        authProvider: { token: async () => token },
+    });
+    const client = new Client({ name: "merchantduo", version: "0.2.0" });
+    try {
+        await client.connect(transport);
+        return await run(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+export default function optionalServices(pi) {
+    const provider = llmProviderConfig();
+    if (provider)
+        pi.registerProvider(MERCHANTDUO_LLM_PROVIDER, provider);
+    const token = mcpToken();
+    if (!token)
+        return;
+    pi.registerTool({
+        name: "merchantduo_knowledge",
+        label: "MerchantDuo knowledge",
+        description: "Use the built-in read-only MerchantDuo knowledge MCP. Omit tool to list its tools, then pass a listed tool name and a JSON object of arguments.",
+        parameters: Type.Object({ tool: Type.Optional(Type.String()), arguments: Type.Optional(Type.String()) }),
+        async execute(_id, params) {
+            try {
+                const result = await withKnowledgeClient(token, async (client) => {
+                    if (!params.tool)
+                        return await client.listTools();
+                    const tools = await client.listTools();
+                    const selected = tools.tools.find((tool) => tool.name === params.tool);
+                    if (!selected)
+                        throw new Error(`unknown MCP tool: ${params.tool}`);
+                    if (!selected.annotations?.readOnlyHint)
+                        throw new Error(`refused non-read-only MCP tool: ${params.tool}`);
+                    const arguments_ = params.arguments ? JSON.parse(params.arguments) : {};
+                    if (!arguments_ || Array.isArray(arguments_) || typeof arguments_ !== "object")
+                        throw new Error("arguments must be a JSON object");
+                    return await client.callTool({ name: params.tool, arguments: arguments_ });
+                });
+                return text(JSON.stringify(result));
+            }
+            catch (error) {
+                return text(`MerchantDuo knowledge MCP unavailable: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/integrations/pi/permissions.d.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type PermissionMode } from "#app/permission-mode";
 import type { Environment } from "#environments/model";
 export declare function requiresExecuteConfirmation(toolName: string, input: Record<string, unknown>): boolean;
-export declare function requiresSshConfirmation(environment: Environment, toolName: string): boolean;
-/** The sole MerchantDuo confirmation gate. Explicit test/navigation tools are intentionally excluded. */
+/** Return block/confirmation behavior; callers retain all hard capability constraints. */
+export declare function permissionDecision(mode: PermissionMode, environment: Environment, toolName: string, input: Record<string, unknown>): "allow" | "block" | "confirm";
+/** The sole MerchantDuo confirmation gate. YOLO removes dialogs, never hard constraints. */
 export default function permissions(pi: ExtensionAPI): void;

package/dist/integrations/pi/permissions.js

@@ -1,35 +1,62 @@
+import { permissionModes } from "#app/permission-mode";
+import { refreshStatus } from "#app/status";
 import { runtime } from "#integrations/pi/session";
+const workspaceMutations = new Set(["write", "edit"]);
+const stoppedAllowed = new Set(["environment_status", "environment_start", "environment_stop", "environment_set_status"]);
 export function requiresExecuteConfirmation(toolName, input) {
-    return (toolName === "mage2gen_generate_module" || toolName === "magento_workflow") && input.execute === true;
+    return ["environment_start", "environment_stop"].includes(toolName) || ((toolName === "mage2gen_generate_module" || toolName === "magento_workflow" || toolName === "magerun2") && input.execute === true);
 }
-export function requiresSshConfirmation(environment, toolName) {
-    return environment.type === "ssh" && environment.writable && ["write", "edit", "bash"].includes(toolName);
+/** Return block/confirmation behavior; callers retain all hard capability constraints. */
+export function permissionDecision(mode, environment, toolName, input) {
+    if (mode === "yolo")
+        return "allow";
+    if (mode === "read-only" && workspaceMutations.has(toolName))
+        return "block";
+    if (mode === "read-only" && (toolName === "bash" || toolName === "magento_php_repl" || requiresExecuteConfirmation(toolName, input)))
+        return "confirm";
+    if (requiresExecuteConfirmation(toolName, input))
+        return "confirm";
+    if (mode === "normal" && environment.type === "ssh" && (workspaceMutations.has(toolName) || toolName === "bash"))
+        return "confirm";
+    return "allow";
 }
-/** The sole MerchantDuo confirmation gate. Explicit test/navigation tools are intentionally excluded. */
+async function confirm(ctx, title, message) {
+    return ctx.hasUI && await ctx.ui.confirm(title, message);
+}
+/** The sole MerchantDuo confirmation gate. YOLO removes dialogs, never hard constraints. */
 export default function permissions(pi) {
+    pi.registerCommand("duo-switch-permissions", { description: "Set this session's permission mode: read-only, normal, or yolo.", handler: async (args, ctx) => {
+            const mode = args.trim();
+            if (!permissionModes.includes(mode)) {
+                ctx.ui.notify("Choose one of: read-only, normal, yolo", "error");
+                return;
+            }
+            await runtime.boot(ctx.cwd);
+            const state = runtime.setPermissionMode(mode);
+            refreshStatus(ctx, state);
+            ctx.ui.notify(`Session permission mode set to ${mode}. It will reset when this session ends.`, "info");
+        } });
     pi.on("tool_call", async (event, ctx) => {
         const state = await runtime.boot(ctx.cwd);
-        const input = event.input;
-        if (requiresExecuteConfirmation(event.toolName, input)) {
-            const ok = ctx.hasUI && await ctx.ui.confirm("Confirm Magento action", `Execute ${event.toolName}?`);
-            return ok ? undefined : { block: true, reason: "Cancelled: confirmation required." };
-        }
-        if (state.selected.environment.type === "ssh" && ["write", "edit", "bash"].includes(event.toolName)) {
-            if (!state.selected.environment.writable)
-                return { block: true, reason: "MerchantDuo: this SSH environment is read-only." };
-            const ok = !requiresSshConfirmation(state.selected.environment, event.toolName) || (ctx.hasUI && await ctx.ui.confirm("SSH workspace action", `Run ${event.toolName} on ${state.selected.environment.host}?`));
-            return ok ? undefined : { block: true, reason: "Cancelled: SSH confirmation required." };
-        }
+        if (state.environmentStatus === "stopped" && !stoppedAllowed.has(event.toolName))
+            return { block: true, reason: "MerchantDuo: selected environment is stopped. Start it first." };
+        const decision = permissionDecision(state.permissionMode, state.selected.environment, event.toolName, event.input);
+        if (decision === "allow")
+            return;
+        if (decision === "block")
+            return { block: true, reason: "MerchantDuo: read-only mode blocks direct workspace writes and edits." };
+        const ok = await confirm(ctx, "Confirm Magento action", `Run ${event.toolName} in ${state.permissionMode} mode?`);
+        return ok ? undefined : { block: true, reason: "Cancelled: confirmation required." };
     });
     pi.on("user_bash", async (event, ctx) => {
         const state = await runtime.boot(ctx.cwd);
-        if (state.selected.environment.type !== "ssh")
-            return;
-        if (!state.selected.environment.writable)
-            return { result: { output: "MerchantDuo: this SSH environment is read-only.", exitCode: 1, cancelled: true, truncated: false } };
-        const ok = ctx.hasUI && await ctx.ui.confirm("SSH command", `Run command on ${state.selected.environment.host}?`);
-        if (!ok)
+        if (state.environmentStatus === "stopped")
+            return { result: { output: "MerchantDuo: selected environment is stopped. Start it first.", exitCode: 1, cancelled: true, truncated: false } };
+        const decision = state.permissionMode === "yolo" ? "allow" : state.permissionMode === "read-only" || state.selected.environment.type === "ssh" ? "confirm" : "allow";
+        if (decision === "confirm" && !(await confirm(ctx, "Confirm shell command", `Run command in ${state.permissionMode} mode?`)))
             return { result: { output: "Cancelled: confirmation required.", exitCode: 1, cancelled: true, truncated: false } };
+        if (decision === "allow" && state.selected.environment.type !== "ssh" && state.permissionMode !== "read-only")
+            return;
         const result = await state.backend.run(["sh", "-lc", event.command]);
         return { result: { output: `${result.stdout}${result.stderr}`, exitCode: result.exitCode, cancelled: false, truncated: result.truncated } };
     });

package/dist/integrations/pi/testing.js

@@ -56,23 +56,22 @@ export default function testing(pi) {
         } });
     pi.registerTool({ name: "magento_php_repl", label: "Magento PHP console", description: "Explicit one-shot magerun2 PHP snippet execution.", parameters: Type.Object({ snippet: Type.String({ minLength: 1 }), area: Type.Optional(Type.Union([Type.Literal("adminhtml"), Type.Literal("frontend"), Type.Literal("crontab"), Type.Literal("webapi_rest"), Type.Literal("graphql")])) }), async execute(_id, params, signal, _update, ctx) {
             const state = await runtime.boot(ctx.cwd);
-            if (state.selected.environment.type === "ssh" && !state.selected.environment.writable)
-                return text("PHP REPL is unavailable for read-only SSH.");
-            const executable = state.testing?.phpRepl.executable;
+            const executable = state.magerun2?.executable;
             if (!executable)
-                return text(state.testing?.phpRepl.reason ?? "PHP REPL unavailable.");
-            const args = [executable, "dev:console"];
+                return text(state.magerun2?.diagnostic ?? "PHP REPL unavailable.");
+            const args = ["dev:console"];
             if (params.area)
                 args.push(`--area=${params.area}`);
             if (state.selected.environment.type === "local") {
-                const result = await host.run("sh", ["-lc", `${quote(executable)} dev:console${params.area ? ` --area=${params.area}` : ""}`], { cwd: ctx.cwd, signal, input: params.snippet });
+                const command = state.backend.command([executable, ...args]);
+                const result = await host.run(command.file, command.args, { cwd: command.cwd ?? ctx.cwd, signal, input: params.snippet });
                 return text(bound(result.output));
             }
-            const result = await state.backend.run(args, { input: params.snippet, signal });
+            const result = await state.backend.run([executable, ...args], { input: params.snippet, signal });
             return text(bound(`${result.stdout}${result.stderr}`));
         } });
-    registerNavigate(pi, "navigate-frontend", "frontend");
-    registerNavigate(pi, "navigate-adminhtml", "adminhtml");
+    registerNavigate(pi, "duo-navigate-frontend", "frontend");
+    registerNavigate(pi, "duo-navigate-adminhtml", "adminhtml");
 }
 function registerNavigate(pi, name, target) { pi.registerCommand(name, { description: `Open the discovered Magento ${target} URL in the default browser.`, handler: async (args, ctx) => { const state = await runtime.boot(ctx.cwd); const base = target === "frontend" ? state.testing?.frontendUrl : state.testing?.adminUrl; const url = targetUrl(base, args.trim() || "/"); if (!url) {
         ctx.ui.notify("URL unavailable or path is not same-origin.", "error");
@@ -84,5 +83,4 @@ function registerNavigate(pi, name, target) { pi.registerCommand(name, { descrip
 function targetUrl(base, path) { if (!relativePath(path))
     return undefined; const url = joinedUrl(base, path); return url && sameOrigin(base, url) ? url : undefined; }
 function projectId(cwd) { return cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").slice(-80) || "project"; }
-function quote(value) { return `'${value.replace(/'/g, "'\\''")}'`; }
 const BunOrNode = { async write(path, value) { const { writeFile } = await import("node:fs/promises"); await writeFile(path, value, "utf8"); } };

package/dist/integrations/pi/theme.d.ts

@@ -1,2 +1,4 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SessionState } from "#app/runtime";
+export declare function themeChoices(state: SessionState): string[];
 export default function theme(pi: ExtensionAPI): void;

package/dist/integrations/pi/theme.js

@@ -1,6 +1,25 @@
 import { refreshStatus } from "#app/status";
 import { runtime } from "#integrations/pi/session";
-export default function theme(pi) { pi.registerCommand("theme", { description: "Select all, any, or a detected Magento theme.", handler: async (args, ctx) => { const state = await runtime.boot(ctx.cwd); const value = args.trim(); const choices = ["all", "any", ...state.magento.themes.map((theme) => theme.code)]; if (!choices.includes(value)) {
-        ctx.ui.notify(`Choose one of: ${choices.join(", ")}`, "error");
-        return;
-    } const changed = await runtime.changeTheme(ctx.cwd, value); refreshStatus(ctx, changed); ctx.ui.notify(`Theme scope set to ${value}.`, "info"); } }); }
+export function themeChoices(state) {
+    return ["all", "any", ...state.magento.themes.map((theme) => theme.code)];
+}
+export default function theme(pi) {
+    pi.registerCommand("duo-switch-theme", {
+        description: "Choose a detected Magento theme, all, or any.",
+        handler: async (args, ctx) => {
+            const state = await runtime.boot(ctx.cwd);
+            const choices = themeChoices(state);
+            const typed = args.trim();
+            const value = typed || (ctx.hasUI ? await ctx.ui.select("Select Magento theme scope", choices) : undefined);
+            if (!value)
+                return;
+            if (!choices.includes(value)) {
+                ctx.ui.notify(`Choose one of: ${choices.join(", ")}`, "error");
+                return;
+            }
+            const changed = await runtime.changeTheme(ctx.cwd, value);
+            refreshStatus(ctx, changed);
+            ctx.ui.notify(`Theme scope set to ${value}.`, "info");
+        },
+    });
+}