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

package/dist/testing/discovery.js

@@ -0,0 +1,68 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalUrl, joinedUrl } from "#testing/url";
+export async function discoverTesting(environment, backend, cwd, options, tools = {}) {
+    const diagnostics = [];
+    let frontendUrl = canonicalUrl(options.frontendUrl ?? "");
+    let adminUrl = canonicalUrl(options.adminUrl ?? "");
+    if (options.frontendUrl && !frontendUrl)
+        diagnostics.push("Configured frontendUrl is invalid.");
+    if (options.adminUrl && !adminUrl)
+        diagnostics.push("Configured adminUrl is invalid.");
+    if (!frontendUrl && environment.type === "warden") {
+        const routing = await wardenRouting(join(cwd, environment.projectRoot));
+        if (routing)
+            frontendUrl = `https://${routing}/`;
+        else
+            diagnostics.push("Warden routing was not found in .env.");
+    }
+    if (!frontendUrl && environment.type !== "warden") {
+        const result = await backend.run(["bin/magento", "config:show", "web/secure/base_url"]);
+        frontendUrl = canonicalUrl(result.stdout.trim());
+        if (!frontendUrl) {
+            const fallback = await backend.run(["bin/magento", "config:show", "web/unsecure/base_url"]);
+            frontendUrl = canonicalUrl(fallback.stdout.trim());
+        }
+    }
+    if (!adminUrl) {
+        const result = await backend.run(["bin/magento", "info:adminuri"]);
+        const path = result.stdout.trim().split(/\s+/).pop();
+        adminUrl = joinedUrl(frontendUrl, path?.startsWith("/") ? path : `/${path ?? ""}`);
+    }
+    const browser = tools.browser
+        ? { available: true, executable: tools.browser }
+        : { available: false, reason: "Install Chromium or Chrome." };
+    const phpRepl = tools.magerun
+        ? { available: true, executable: tools.magerun }
+        : { available: false, reason: "n98-magerun2 is unavailable." };
+    if (!frontendUrl)
+        diagnostics.push("Frontend URL unavailable.");
+    if (!adminUrl)
+        diagnostics.push("Admin URL unavailable.");
+    diagnostics.push("URLs are discovered but unverified; no startup HTTP request was made.");
+    const http = tools.http ? { available: true, executable: tools.http } : { available: false, reason: "Install curl." };
+    return { frontendUrl, adminUrl, http, browser, phpRepl, diagnostics };
+}
+export async function wardenRouting(projectRoot) {
+    try {
+        const content = await readFile(join(projectRoot, ".env"), "utf8");
+        const picked = Object.fromEntries(content.split(/\r?\n/).flatMap((line) => {
+            const match = line.match(/^\s*(TRAEFIK_(?:DOMAIN|SUBDOMAIN))\s*=\s*([^#\r\n]+)\s*$/);
+            return match ? [[match[1], match[2].trim().replace(/^['"]|['"]$/g, "")]] : [];
+        }));
+        return picked.TRAEFIK_DOMAIN && picked.TRAEFIK_SUBDOMAIN ? `${picked.TRAEFIK_SUBDOMAIN}.${picked.TRAEFIK_DOMAIN}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function findExecutable(candidates) {
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch { /* PATH candidates are resolved by command execution. */ }
+    }
+    return undefined;
+}

package/dist/testing/host.d.ts

@@ -0,0 +1,29 @@
+export type HostProcessResult = {
+    output: string;
+    code: number;
+};
+export interface HostProcessRunner {
+    run(file: string, args: string[], options: {
+        cwd: string;
+        signal?: AbortSignal;
+        input?: string;
+    }): Promise<HostProcessResult>;
+}
+/** Process runner for host-owned test and navigation tools. Never wraps EnvironmentBackend. */
+export declare class NodeHostProcessRunner implements HostProcessRunner {
+    run(file: string, args: string[], options: {
+        cwd: string;
+        signal?: AbortSignal;
+        input?: string;
+    }): Promise<HostProcessResult>;
+}
+export declare function discoverHostExecutable(names: string[], runner?: HostProcessRunner): Promise<string | undefined>;
+export declare function browserArguments(input: {
+    profile: string;
+    artifact: string;
+    url: string;
+    action: "screenshot" | "dump-dom";
+    allowInsecureTls: boolean;
+}): string[];
+export declare function artifactExists(path: string): Promise<boolean>;
+export declare function bound(value: string): string;

package/dist/testing/host.js

@@ -0,0 +1,50 @@
+import { access } from "node:fs/promises";
+import { spawn } from "node:child_process";
+const MAX_OUTPUT = 32 * 1024;
+/** Process runner for host-owned test and navigation tools. Never wraps EnvironmentBackend. */
+export class NodeHostProcessRunner {
+    run(file, args, options) {
+        return new Promise((done) => {
+            const child = spawn(file, args, { cwd: options.cwd, signal: options.signal });
+            let output = "";
+            let settled = false;
+            const finish = (result) => { if (!settled) {
+                settled = true;
+                done(result);
+            } };
+            const add = (data) => { output = bound(output + data.toString()); };
+            child.stdout.on("data", add);
+            child.stderr.on("data", add);
+            child.on("error", (error) => finish({ output: error.message, code: 127 }));
+            child.on("close", (code) => finish({ output, code: code ?? 1 }));
+            if (options.input !== undefined)
+                child.stdin.end(options.input);
+        });
+    }
+}
+export async function discoverHostExecutable(names, runner = new NodeHostProcessRunner()) {
+    for (const name of names) {
+        const result = await runner.run("sh", ["-lc", `command -v ${name} 2>/dev/null`], { cwd: process.cwd() });
+        if (result.code === 0 && result.output.trim())
+            return result.output.trim();
+    }
+    return undefined;
+}
+export function browserArguments(input) {
+    return [
+        "--headless",
+        "--no-first-run",
+        `--user-data-dir=${input.profile}`,
+        "--disable-extensions",
+        "--virtual-time-budget=10000",
+        ...(input.allowInsecureTls ? ["--ignore-certificate-errors"] : []),
+        input.action === "screenshot" ? `--screenshot=${input.artifact}` : "--dump-dom",
+        input.url,
+    ];
+}
+export async function artifactExists(path) {
+    return access(path).then(() => true).catch(() => false);
+}
+export function bound(value) {
+    return value.length > MAX_OUTPUT ? `${value.slice(0, MAX_OUTPUT)}\n[output truncated]` : value;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export * from "#testing/model";
+export * from "#testing/url";
+export * from "#testing/discovery";
+export * from "#testing/magerun";
+export * from "#testing/host";

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+export * from "#testing/model";
+export * from "#testing/url";
+export * from "#testing/discovery";
+export * from "#testing/magerun";
+export * from "#testing/host";

package/dist/testing/magerun.d.ts

@@ -0,0 +1,8 @@
+import type { EnvironmentBackend } from "#environments/backend";
+import type { Environment } from "#environments/model";
+export declare function discoverMagerun(environment: Environment, backend: EnvironmentBackend, cwd: string): Promise<{
+    executable?: string;
+    diagnostic?: string;
+}>;
+/** Install the official PHAR outside the Magento project; verify the release API SHA-256 digest before publishing it. */
+export declare function installMagerun(home: string, _cwd: string, request?: typeof fetch): Promise<string>;

package/dist/testing/magerun.js

@@ -0,0 +1,73 @@
+import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { merchantHome } from "#config/paths";
+const RELEASE_URL = "https://api.github.com/repos/netz98/n98-magerun2/releases/latest";
+export async function discoverMagerun(environment, backend, cwd) {
+    if (environment.type === "warden")
+        return { 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 executable = result.stdout.trim();
+        if (executable)
+            return { 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." };
+    try {
+        return { executable: await installMagerun(merchantHome(), cwd) };
+    }
+    catch (error) {
+        return { 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) {
+    const directory = join(home, "tools", "n98-magerun2");
+    const destination = join(directory, "n98-magerun2.phar");
+    const digestPath = `${destination}.sha256`;
+    try {
+        await stat(destination);
+        const expected = (await readFile(digestPath, "utf8")).trim();
+        if (/^[a-f0-9]{64}$/.test(expected) && sha256(await readFile(destination)) === expected)
+            return destination;
+    }
+    catch { /* no verified cache */ }
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const release = await request(RELEASE_URL, { headers: { Accept: "application/vnd.github+json" } });
+    if (!release.ok)
+        throw new Error("official release metadata download failed");
+    const metadata = await release.json();
+    const asset = metadata.assets?.find(({ name }) => name === "n98-magerun2.phar");
+    const expected = asset?.digest?.match(/^sha256:([a-fA-F0-9]{64})$/)?.[1]?.toLowerCase();
+    if (!asset?.browser_download_url || !expected)
+        throw new Error("official release has no PHAR SHA-256 digest");
+    const phar = await request(asset.browser_download_url);
+    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)
+        throw new Error("PHAR SHA-256 verification failed");
+    const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+    await BunOrNode.write(temporary, bytes);
+    await chmod(temporary, 0o700);
+    try {
+        await rename(temporary, destination);
+    }
+    catch {
+        try {
+            await stat(destination);
+        }
+        catch {
+            throw new Error("atomic PHAR installation failed");
+        }
+    }
+    await writeFile(digestPath, expected, { mode: 0o600 });
+    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/testing/model.d.ts

@@ -0,0 +1,18 @@
+export type Capability = {
+    available: boolean;
+    executable?: string;
+    reason?: string;
+};
+export type TestingSnapshot = {
+    frontendUrl?: string;
+    adminUrl?: string;
+    http: Capability;
+    browser: Capability;
+    phpRepl: Capability;
+    diagnostics: string[];
+};
+export type TestingOptions = {
+    frontendUrl?: string;
+    adminUrl?: string;
+    allowInsecureTls: boolean;
+};

package/dist/testing/url.d.ts

@@ -0,0 +1,4 @@
+export declare function canonicalUrl(value: string): string | undefined;
+export declare function joinedUrl(base: string | undefined, path?: string): string | undefined;
+export declare function relativePath(value: string): boolean;
+export declare function sameOrigin(base: string | undefined, target: string): boolean;

package/dist/testing/url.js

@@ -0,0 +1,26 @@
+export function canonicalUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function joinedUrl(base, path = "/") {
+    if (!base || !relativePath(path))
+        return undefined;
+    const url = new URL(base);
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/\/{2,}/g, "/");
+    return url.toString();
+}
+export function relativePath(value) {
+    return !value.includes(":") && !value.startsWith("//") && value.startsWith("/");
+}
+export function sameOrigin(base, target) {
+    if (!base)
+        return false;
+    return new URL(base).origin === new URL(target).origin;
+}

package/dist/workflows/builtins.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDefinition } from "#workflows/definition";
+export declare const builtInWorkflows: WorkflowDefinition[];

package/dist/workflows/builtins.js

@@ -0,0 +1,38 @@
+export const builtInWorkflows = [
+    operation("cache-clean", "Clean only relevant Magento cache types", false, (types) => ["bin/magento", "cache:clean", ...types]),
+    operation("cache-flush", "Flush Magento caches", true, () => [
+        "bin/magento",
+        "cache:flush",
+    ]),
+    operation("compile", "Compile Magento dependency injection", true, () => [
+        "bin/magento",
+        "setup:di:compile",
+    ]),
+    operation("setup-upgrade", "Run Magento setup upgrade", true, () => [
+        "bin/magento",
+        "setup:upgrade",
+    ]),
+    operation("maintenance-enable", "Enable maintenance mode", true, () => [
+        "bin/magento",
+        "maintenance:enable",
+    ]),
+    operation("maintenance-disable", "Disable maintenance mode", true, () => [
+        "bin/magento",
+        "maintenance:disable",
+    ]),
+    operation("static-content-deploy", "Deploy static content", true, () => [
+        "bin/magento",
+        "setup:static-content:deploy",
+    ]),
+    operation("reindex", "Reindex Magento", true, () => [
+        "bin/magento",
+        "indexer:reindex",
+    ]),
+    operation("tests", "Run Magento tests", true, () => [
+        "bin/magento",
+        "dev:tests:run",
+    ]),
+];
+function operation(id, description, risky, command) {
+    return { id, description, risky, allowRemote: false, command };
+}

package/dist/workflows/change-tracker.d.ts

@@ -0,0 +1,9 @@
+import type { MagentoSnapshot } from "#magento/model";
+export declare class ChangeTracker {
+    #private;
+    begin(toolCallId: string, file: string): void;
+    finish(toolCallId: string, succeeded: boolean): void;
+    files(): string[];
+    safeCacheTypes(snapshot: MagentoSnapshot): string[];
+    clear(): void;
+}

package/dist/workflows/change-tracker.js

@@ -0,0 +1,38 @@
+const cacheByEdit = {
+    layout: ["layout", "block_html", "full_page"],
+    template: ["block_html", "full_page"],
+    xml: ["config", "layout", "block_html"],
+    di: ["config"],
+    graphql: ["config", "full_page"],
+};
+export class ChangeTracker {
+    #intent = new Map();
+    #files = new Set();
+    #cacheTypes = new Set();
+    begin(toolCallId, file) {
+        this.#intent.set(toolCallId, file);
+    }
+    finish(toolCallId, succeeded) {
+        const file = this.#intent.get(toolCallId);
+        this.#intent.delete(toolCallId);
+        if (!file || !succeeded)
+            return;
+        this.#files.add(file);
+        const lower = file.toLowerCase();
+        for (const [needle, types] of Object.entries(cacheByEdit))
+            if (lower.includes(needle) || lower.endsWith(`.${needle}`))
+                types.forEach((type) => this.#cacheTypes.add(type));
+        if (lower.endsWith(".xml"))
+            cacheByEdit.xml.forEach((type) => this.#cacheTypes.add(type));
+    }
+    files() {
+        return [...this.#files];
+    }
+    safeCacheTypes(snapshot) {
+        return [...this.#cacheTypes].filter((type) => snapshot.cacheTypes.includes(type));
+    }
+    clear() {
+        this.#files.clear();
+        this.#cacheTypes.clear();
+    }
+}

package/dist/workflows/definition.d.ts

@@ -0,0 +1,7 @@
+export type WorkflowDefinition = {
+    id: string;
+    description: string;
+    risky: boolean;
+    allowRemote: boolean;
+    command(cacheTypes: string[]): string[];
+};

package/dist/workflows/index.d.ts

@@ -0,0 +1,4 @@
+export { builtInWorkflows } from "#workflows/builtins";
+export { ChangeTracker } from "#workflows/change-tracker";
+export type { WorkflowDefinition } from "#workflows/definition";
+export { runWorkflow, syntaxCheck } from "#workflows/runner";

package/dist/workflows/index.js

@@ -0,0 +1,3 @@
+export { builtInWorkflows } from "#workflows/builtins";
+export { ChangeTracker } from "#workflows/change-tracker";
+export { runWorkflow, syntaxCheck } from "#workflows/runner";

package/dist/workflows/runner.d.ts

@@ -0,0 +1,7 @@
+import type { CommandExecutor } from "#environments/executor";
+import type { WorkflowDefinition } from "#workflows/definition";
+export declare function runWorkflow(executor: CommandExecutor, definition: WorkflowDefinition, cacheTypes?: string[]): Promise<{
+    command: import("#environments/executor").CommandSpec;
+    result: import("#environments/executor").CommandResult;
+}>;
+export declare function syntaxCheck(executor: CommandExecutor, files: string[]): Promise<string[]>;

package/dist/workflows/runner.js

@@ -0,0 +1,28 @@
+export async function runWorkflow(executor, definition, cacheTypes = []) {
+    const command = definition.command(cacheTypes);
+    return {
+        command: executor.command(command),
+        result: await executor.run(command),
+    };
+}
+export async function syntaxCheck(executor, files) {
+    const outcomes = [];
+    for (const file of files) {
+        const command = file.endsWith(".php")
+            ? ["php", "-l", executor.path(file)]
+            : file.endsWith(".xml")
+                ? ["xmllint", "--noout", executor.path(file)]
+                : file.endsWith(".json")
+                    ? [
+                        "node",
+                        "-e",
+                        `JSON.parse(require('fs').readFileSync(${JSON.stringify(executor.path(file))},'utf8'))`,
+                    ]
+                    : undefined;
+        if (!command)
+            continue;
+        const result = await executor.run(command);
+        outcomes.push(`${file}: ${result.exitCode === 0 ? "ok" : result.stderr || result.stdout}`);
+    }
+    return outcomes;
+}

package/package.json

@@ -1,21 +1,33 @@
 {
   "name": "@merchantduo/code",
-  "version": "0.1.0-beta.0",
+  "version": "0.2.0-beta.0",
   "private": false,
   "description": "Magento-native Pi-based Coding Agent",
   "type": "module",
+  "imports": {
+    "#app/*": "./dist/app/*.js",
+    "#cli/*": "./dist/cli/*.js",
+    "#config/*": "./dist/config/*.js",
+    "#environments/*": "./dist/environments/*.js",
+    "#features/*": "./dist/features/*.js",
+    "#integrations/*": "./dist/integrations/*.js",
+    "#magento/*": "./dist/magento/*.js",
+    "#provision/*": "./dist/provision/*.js",
+    "#shared/*": "./dist/shared/*.js",
+    "#skills/*": "./dist/skills/*.js",
+    "#testing/*": "./dist/testing/*.js",
+    "#workflows/*": "./dist/workflows/*.js"
+  },
   "bin": {
-    "merchantduo": "./dist/cli.js"
+    "merchantduo": "./dist/cli/main.js"
   },
   "files": [
     "dist",
-    "extensions",
     "skills",
     "vendor/mage2gen",
     "vendor/hyva-ai-tools",
     "THIRD_PARTY_LICENSES.md",
-    "README.md",
-    "LICENSE"
+    "README.md"
   ],
   "keywords": [
     "magento",
@@ -27,12 +39,22 @@
   },
   "pi": {
     "extensions": [
-      "./extensions"
+      "./dist/integrations/pi/context.js",
+      "./dist/integrations/pi/permissions.js",
+      "./dist/integrations/pi/workspace.js",
+      "./dist/integrations/pi/theme.js",
+      "./dist/integrations/pi/mage2gen.js",
+      "./dist/integrations/pi/workflows.js",
+      "./dist/integrations/pi/testing.js"
+    ],
+    "skills": [
+      "./skills",
+      "./vendor/hyva-ai-tools/skills"
     ]
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.1",
-    "@modelcontextprotocol/client": "2.0.0",
+    "typebox": "1.3.7",
     "yaml": "^2.8.1",
     "zod": "^3.24.4"
   },
@@ -42,8 +64,9 @@
     "typescript": "^5.8.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "node --test dist/**/*.test.js",
+    "clean": "node -e \"const fs=require('node:fs'); for(const path of ['dist','.test-dist']) fs.rmSync(path,{recursive:true,force:true})\"",
+    "build": "pnpm clean && tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/cli/main.js',0o755)\"",
+    "test": "pnpm build && tsc -p tsconfig.test.json && node --test \".test-dist/**/*.test.js\"",
     "check": "tsc --noEmit"
   }
 }

package/skills/magento-testing/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: magento-testing
+description: Use explicit MerchantDuo Magento testing and navigation tools only when they directly support the current request.
+---
+
+# Magento testing
+
+Use `magento_http_test` for a focused unauthenticated GET or HEAD request. Use `magento_browser_test` only for a requested screenshot or DOM capture. Use `magento_php_repl` only when the task needs a one-shot Magento PHP inspection. Use navigation commands only when the user asks to open the resolved page.
+
+Do not run background checks, broad crawls, cache actions, deployments, PHP snippets, browser actions, or HTTP requests merely because a session started, an edit succeeded, or the agent settled. URLs discovered at startup are unverified until an explicit test is requested. Never assume or manage an admin login.

package/dist/backend.d.ts

@@ -1,24 +0,0 @@
-import type { Environment } from "./config.js";
-export type CommandResult = {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    truncated: boolean;
-};
-export declare function contain(root: string, candidate: string): string;
-export declare class Backend {
-    readonly environment: Environment;
-    readonly localRoot: string;
-    constructor(environment: Environment, localRoot: string);
-    path(path: string): string;
-    command(argv: string[], target?: string): {
-        file: string;
-        args: string[];
-        cwd?: string;
-    };
-    run(argv: string[], options?: {
-        signal?: AbortSignal;
-        timeoutMs?: number;
-        target?: string;
-    }): Promise<CommandResult>;
-}