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

package/dist/magento/inspector.js

@@ -0,0 +1,56 @@
+import { parseDeployMode } from "#magento/deploy-mode";
+import { parseRegisteredThemes, resolveThemes } from "#magento/themes";
+/** Ordered, fail-soft Magento inspection. New probes can be extracted without changing consumers. */
+export class DefaultMagentoInspector {
+    async inspect(executor) {
+        const warnings = [];
+        const evidence = [];
+        const composer = await executor.run([
+            "sh",
+            "-lc",
+            "test -f composer.lock && node -e \"const x=require('./composer.lock'); console.log(JSON.stringify(x.packages||[]))\" || true",
+        ]);
+        const match = composer.stdout.match(/magento\/(product-community-edition|product-enterprise-edition).*?"version":"([^"]+)/s);
+        const edition = match?.[1] === "product-enterprise-edition"
+            ? "Adobe Commerce"
+            : match
+                ? "Open Source"
+                : undefined;
+        const composerVersion = match?.[2];
+        if (composerVersion)
+            evidence.push("composer.lock");
+        const cli = await executor.run(["bin/magento", "--version"]);
+        const cliVersion = cli.stdout.match(/(?:Magento|Adobe Commerce)[^0-9]*(\d+\.\d+\.\d+(?:-[^\s]+)?)/)?.[1];
+        if (cliVersion)
+            evidence.push("bin/magento --version");
+        if (composerVersion &&
+            cliVersion &&
+            !cliVersion.startsWith(composerVersion))
+            warnings.push(`Composer (${composerVersion}) and CLI (${cliVersion}) disagree`);
+        const [php, mode, cache, modules, registeredThemes] = await Promise.all([
+            executor.run(["php", "-r", "echo PHP_VERSION;"]),
+            executor.run(["bin/magento", "deploy:mode:show"]),
+            executor.run(["bin/magento", "cache:status", "--no-ansi"]),
+            executor.run(["bin/magento", "module:status", "--enabled", "--no-ansi"]),
+            executor.run(["sh", "-lc", themeDiscoveryScript]),
+        ]);
+        return {
+            version: composerVersion ?? cliVersion,
+            edition,
+            phpVersion: php.stdout.trim() || undefined,
+            mode: parseDeployMode(mode.stdout, mode.exitCode),
+            cacheTypes: cache.stdout
+                .split("\n")
+                .map((line) => line.match(/^([^:]+):/)?.[1])
+                .filter((value) => Boolean(value)),
+            modulesEnabled: modules.stdout.split("\n").filter(Boolean).length || undefined,
+            warnings,
+            evidence,
+            themes: resolveThemes(parseRegisteredThemes(registeredThemes.stdout)),
+        };
+    }
+}
+const themeDiscoveryScript = `{
+  find vendor -mindepth 3 -maxdepth 3 -type f -name registration.php 2>/dev/null
+  find app/design -mindepth 4 -maxdepth 4 -type f -name registration.php 2>/dev/null
+} | while read f; do d=$(dirname "$f"); x="$d/theme.xml"; [ -f "$x" ] || continue; code=$(sed -n "s/.*ComponentRegistrar::THEME[[:space:]]*,[[:space:]]*['\\\"]\\([^'\\\"]*\\).*/\\1/p" "$f" | head -1); [ -n "$code" ] || continue; title=$(sed -n 's:.*<title>\\(.*\\)</title>.*:\\1:p' "$x" | head -1); parent=$(sed -n 's:.*<parent>\\(.*\\)</parent>.*:\\1:p' "$x" | head -1); node -e 'console.log(JSON.stringify({code:process.argv[1],path:process.argv[2],title:process.argv[3]||undefined,parent:process.argv[4]||undefined})+"\\u001e")' "$code" "$d" "$title" "$parent"; done`;

package/dist/magento/model.d.ts

@@ -0,0 +1,25 @@
+export type MagentoDeployMode = "default" | "developer" | "production";
+export type MagentoTheme = {
+    code: string;
+    title?: string;
+    path: string;
+    parentChain: string[];
+    kind: "luma" | "hyva" | "other";
+};
+export type RawTheme = {
+    code: string;
+    path: string;
+    title?: string;
+    parent?: string;
+};
+export type MagentoSnapshot = {
+    version?: string;
+    edition?: "Open Source" | "Adobe Commerce";
+    phpVersion?: string;
+    mode?: MagentoDeployMode;
+    cacheTypes: string[];
+    modulesEnabled?: number;
+    warnings: string[];
+    evidence: string[];
+    themes: MagentoTheme[];
+};

package/dist/magento/prompt.d.ts

@@ -0,0 +1,2 @@
+import type { MagentoSnapshot } from "#magento/model";
+export declare function snapshotPrompt(envName: string, writable: boolean, status: string, snapshot: MagentoSnapshot): string;

package/dist/magento/prompt.js

@@ -0,0 +1,3 @@
+export function snapshotPrompt(envName, writable, status, snapshot) {
+    return `[MerchantDuo: environment=${envName}; write policy=${writable ? "writable" : "read-only"}; Magento=${snapshot.edition ?? "unknown"} ${snapshot.version ?? "unknown"}; PHP=${snapshot.phpVersion ?? "unknown"}; mode=${snapshot.mode ?? "unknown"}; knowledge=${status}; pending actions are controlled by magento_workflow. Do not inspect app/etc/env.php or credentials.${snapshot.warnings.length ? ` Warnings: ${snapshot.warnings.join("; ")}` : ""}]`;
+}

package/dist/magento/themes.d.ts

@@ -0,0 +1,3 @@
+import type { MagentoTheme, RawTheme } from "#magento/model";
+export declare function resolveThemes(themes: RawTheme[]): MagentoTheme[];
+export declare function parseRegisteredThemes(output: string): RawTheme[];

package/dist/magento/themes.js

@@ -0,0 +1,46 @@
+export function resolveThemes(themes) {
+    const byCode = new Map(themes.map((theme) => [theme.code, theme]));
+    const lineage = (theme) => {
+        const chain = [];
+        const seen = new Set([theme.code]);
+        let parent = theme.parent;
+        while (parent && !seen.has(parent)) {
+            chain.push(parent);
+            seen.add(parent);
+            parent = byCode.get(parent)?.parent;
+        }
+        return chain;
+    };
+    return themes.map((theme) => {
+        const parentChain = lineage(theme);
+        const ancestry = [theme.code, ...parentChain];
+        return {
+            code: theme.code,
+            title: theme.title,
+            path: theme.path,
+            parentChain,
+            kind: ancestry.includes("Magento/luma")
+                ? "luma"
+                : ancestry.includes("Hyva/default") || ancestry.includes("Hyva/reset")
+                    ? "hyva"
+                    : "other",
+        };
+    });
+}
+export function parseRegisteredThemes(output) {
+    return output
+        .split("\u001e")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .flatMap((entry) => {
+        try {
+            const value = JSON.parse(entry);
+            return typeof value.code === "string" && typeof value.path === "string"
+                ? [value]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}

package/dist/provision/advisor.d.ts

@@ -0,0 +1,12 @@
+import { type ProvisionPlan, type ProvisionSnapshot } from "#provision/model";
+export declare const PROVISION_ADVISOR_BASE_URL = "https://merchantduo.invalid/v1";
+export declare const PROVISION_ADVISOR_MODEL = "merchantduo-mock";
+export declare class ProvisionAdvisor {
+    private readonly token;
+    private readonly fetcher;
+    constructor(token?: string | undefined, fetcher?: typeof fetch);
+    advise(snapshot: ProvisionSnapshot, plan: ProvisionPlan): Promise<{
+        plan: ProvisionPlan;
+        diagnostic?: string;
+    }>;
+}

package/dist/provision/advisor.js

@@ -0,0 +1,28 @@
+import { redactProvisionSnapshot } from "#provision/model";
+export const PROVISION_ADVISOR_BASE_URL = "https://merchantduo.invalid/v1";
+export const PROVISION_ADVISOR_MODEL = "merchantduo-mock";
+export class ProvisionAdvisor {
+    token;
+    fetcher;
+    constructor(token = process.env.MERCHANTDUO_LLM_TOKEN, fetcher = fetch) {
+        this.token = token;
+        this.fetcher = fetcher;
+    }
+    async advise(snapshot, plan) {
+        if (!this.token)
+            return { plan };
+        try {
+            const response = await this.fetcher(`${PROVISION_ADVISOR_BASE_URL}/chat/completions`, { method: "POST", headers: { authorization: `Bearer ${this.token}`, "content-type": "application/json" }, body: JSON.stringify({ model: PROVISION_ADVISOR_MODEL, response_format: { type: "json_object" }, messages: [{ role: "user", content: JSON.stringify({ snapshot: redactProvisionSnapshot(snapshot), allowedActions: plan.actions }) }] }) });
+            if (!response.ok)
+                throw new Error(`advisor returned HTTP ${response.status}`);
+            const body = await response.json();
+            const selected = JSON.parse(body.choices?.[0]?.message?.content ?? "{}");
+            if (!Array.isArray(selected.actions) || !selected.actions.every((action) => plan.actions.some((allowed) => JSON.stringify(allowed) === JSON.stringify(action))))
+                throw new Error("advisor selected an action outside the approved plan");
+            return { plan: { ...plan, actions: selected.actions } };
+        }
+        catch (error) {
+            return { plan, diagnostic: `Provision advisor unavailable: ${error.message}; using deterministic plan.` };
+        }
+    }
+}

package/dist/provision/discovery.d.ts

@@ -0,0 +1,12 @@
+import type { ProvisionSnapshot } from "#provision/model";
+export type ProvisionProbe = {
+    run(argv: string[], cwd?: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+};
+export declare class SystemProvisionProbe implements ProvisionProbe {
+    run(argv: string[], cwd?: string): Promise<import("#environments/executor").CommandResult>;
+}
+export declare function discoverProvision(root: string, probe?: ProvisionProbe): Promise<ProvisionSnapshot>;

package/dist/provision/discovery.js

@@ -0,0 +1,61 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, join, resolve } from "node:path";
+const exists = async (path) => access(path, constants.F_OK).then(() => true).catch(() => false);
+export class SystemProvisionProbe {
+    async run(argv, cwd) {
+        const { EnvironmentBackend } = await import("#environments/backend");
+        const backend = new EnvironmentBackend({ type: "local", root: cwd ?? process.cwd() }, cwd ?? process.cwd());
+        return backend.run(argv);
+    }
+}
+async function command(probe, name, cwd) {
+    return (await probe.run(["sh", "-lc", `command -v ${name} >/dev/null`], cwd)).exitCode === 0;
+}
+async function serviceActive(probe, name, cwd) {
+    return (await probe.run(["sh", "-lc", `systemctl is-active --quiet ${name} 2>/dev/null || pgrep -x ${name} >/dev/null 2>&1`], cwd)).exitCode === 0;
+}
+function parseVhosts(text, root) {
+    const normalized = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const rootMatch = text.match(new RegExp(`(?:root|DocumentRoot)\\s+["']?(${normalized}(?:/pub)?)["']?`, "i"));
+    if (!rootMatch)
+        return undefined;
+    const domain = text.match(/(?:server_name|ServerName)\s+([^\s;]+)/i)?.[1];
+    return domain ? { server: /server_name/i.test(text) ? "nginx" : "apache", domain, documentRoot: rootMatch[1] } : undefined;
+}
+export async function discoverProvision(root, probe = new SystemProvisionProbe()) {
+    const resolved = resolve(root);
+    const entries = await readdir(resolved).catch(() => []);
+    const composer = await exists(join(resolved, "composer.json"));
+    const binMagento = await exists(join(resolved, "bin/magento"));
+    const composerText = composer ? await readFile(join(resolved, "composer.json"), "utf8").catch(() => "") : "";
+    const detected = binMagento || /magento\/(product|project|composer)/.test(composerText);
+    const dumps = entries.filter((name) => /\.sql(?:\.gz)?$/i.test(name)).map((name) => join(resolved, name));
+    const [php, composerCommand, mysql, warden, nginx, apache, nginxActive, apacheActive, wardenRunning] = await Promise.all([
+        command(probe, "php", resolved), command(probe, "composer", resolved), command(probe, "mysql", resolved), command(probe, "warden", resolved),
+        command(probe, "nginx", resolved), command(probe, "apache2", resolved).then((v) => v || command(probe, "httpd", resolved)),
+        serviceActive(probe, "nginx", resolved), serviceActive(probe, "apache2", resolved), serviceActive(probe, "warden", resolved),
+    ]);
+    const wardenConfigured = await exists(join(resolved, ".warden", "warden-env.yml")) || await exists(join(resolved, ".env"));
+    const env = await readFile(join(resolved, ".env"), "utf8").catch(() => "");
+    const domain = env.match(/^TRAEFIK_(?:SUB)?DOMAIN=(.+)$/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+    const servers = [nginx && "nginx", apache && "apache"].filter(Boolean);
+    const activeServers = [nginxActive && "nginx", apacheActive && "apache"].filter(Boolean);
+    const serverConfig = await Promise.all(servers.map(async (server) => {
+        const paths = server === "nginx" ? ["/etc/nginx/sites-enabled", "/etc/nginx/conf.d"] : ["/etc/apache2/sites-enabled", "/etc/httpd/conf.d"];
+        for (const path of paths) {
+            const result = await probe.run(["sh", "-lc", `test -d ${path} && grep -R -h -E 'server_name|ServerName|root|DocumentRoot' ${path} 2>/dev/null || true`], resolved);
+            const vhost = parseVhosts(result.stdout, resolved);
+            if (vhost)
+                return { ...vhost, server };
+        }
+        return undefined;
+    }));
+    const magentoMode = detected ? await probe.run(["sh", "-lc", "test -x bin/magento && bin/magento deploy:mode:show --no-ansi || true"], resolved) : undefined;
+    return {
+        workspace: { root: resolved, empty: entries.length === 0, magentoRoot: detected }, source: { composer, binMagento },
+        database: { envConfigured: await exists(join(resolved, "app/etc/env.php")), dumps },
+        environments: { local: { available: php && composerCommand && mysql && activeServers.length > 0, php, composer: composerCommand, mysql, servers, activeServers, vhost: serverConfig.find(Boolean) }, warden: { available: warden, configured: wardenConfigured, running: wardenRunning, domain } },
+        magento: { detected, mode: magentoMode?.stdout.match(/(?:Current|Mode):\s*(\w+)/i)?.[1] }, diagnostics: detected ? [] : [`${basename(resolved)} is not a Magento root`]
+    };
+}

package/dist/provision/interview.d.ts

@@ -0,0 +1,9 @@
+import type { ProvisionInput, ProvisionPlan, ProvisionSnapshot } from "#provision/model";
+export interface ProvisionInterview {
+    resolve(snapshot: ProvisionSnapshot, initial: ProvisionInput): Promise<ProvisionInput>;
+    approve(plan: ProvisionPlan): Promise<boolean>;
+}
+export declare class TerminalProvisionInterview implements ProvisionInterview {
+    resolve(snapshot: ProvisionSnapshot, initial: ProvisionInput): Promise<ProvisionInput>;
+    approve(plan: ProvisionPlan): Promise<boolean>;
+}

package/dist/provision/interview.js

@@ -0,0 +1,29 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+export class TerminalProvisionInterview {
+    async resolve(snapshot, initial) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            const environment = initial.environment ?? await rl.question(`Environment (${snapshot.environments.warden.available ? "warden" : "local"}/local): `);
+            const source = initial.source ?? (snapshot.workspace.magentoRoot ? "existing" : await rl.question("Magento source (git URL, archive path, or HTTPS URL): ").then(parseSource));
+            const database = initial.database ?? (snapshot.database.dumps.length === 1 ? `dump:${snapshot.database.dumps[0]}` : await rl.question("Database (current, dump path, or HTTPS URL): ").then(parseDatabase));
+            const localDomain = environment === "local" && !snapshot.environments.local.vhost ? await rl.question("Local domain (blank for directory.test): ") : initial.localDomain;
+            return { environment, source, database, localDomain: localDomain || undefined };
+        }
+        finally {
+            rl.close();
+        }
+    }
+    async approve(plan) {
+        stdout.write("\nProvision plan:\n" + plan.actions.map((action, index) => `${index + 1}. ${action.type}${"command" in action ? ` (${action.command})` : ""}`).join("\n") + `\nSudo required: ${plan.requiresSudo ? "yes" : "no"}\n`);
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            return (await rl.question("Execute this plan? [y/N] ")).trim().toLowerCase() === "y";
+        }
+        finally {
+            rl.close();
+        }
+    }
+}
+function parseSource(value) { return /^https?:\/\//.test(value) ? (value.endsWith(".git") ? `git:${value}` : `https:${value}`) : `archive:${value}`; }
+function parseDatabase(value) { return value === "current" ? "current" : /^https?:\/\//.test(value) ? `https:${value}` : `dump:${value}`; }

package/dist/provision/model.d.ts

@@ -0,0 +1,82 @@
+/** Public, redacted state used to make a provision decision. */
+export type ProvisionEnvironment = "local" | "warden";
+export type SourceInput = "existing" | `git:${string}` | `archive:${string}` | `https:${string}`;
+export type DatabaseInput = "current" | `dump:${string}` | `https:${string}`;
+export type ProvisionInput = {
+    environment?: ProvisionEnvironment;
+    source?: SourceInput;
+    database?: DatabaseInput;
+    localDomain?: string;
+};
+export type WebServer = "nginx" | "apache";
+export type ProvisionSnapshot = {
+    workspace: {
+        root: string;
+        empty: boolean;
+        magentoRoot: boolean;
+    };
+    source: {
+        composer: boolean;
+        binMagento: boolean;
+    };
+    database: {
+        envConfigured: boolean;
+        dumps: string[];
+    };
+    environments: {
+        local: {
+            available: boolean;
+            php: boolean;
+            composer: boolean;
+            mysql: boolean;
+            servers: WebServer[];
+            activeServers: WebServer[];
+            vhost?: {
+                server: WebServer;
+                domain: string;
+                documentRoot: string;
+            };
+        };
+        warden: {
+            available: boolean;
+            configured: boolean;
+            running: boolean;
+            domain?: string;
+        };
+    };
+    magento: {
+        detected: boolean;
+        mode?: string;
+    };
+    diagnostics: string[];
+};
+export type ProvisionAction = {
+    type: "acquire-source";
+    source: Exclude<SourceInput, "existing">;
+} | {
+    type: "install-dependencies";
+} | {
+    type: "start-warden";
+} | {
+    type: "import-database";
+    database: Exclude<DatabaseInput, "current">;
+} | {
+    type: "configure-database";
+} | {
+    type: "magento-setup";
+    command: "app:config:import" | "setup:upgrade" | "cache:clean" | "indexer:reindex" | "maintenance:disable";
+} | {
+    type: "configure-web-server";
+    server: WebServer;
+    domain: string;
+} | {
+    type: "verify-storefront";
+    url?: string;
+};
+export type ProvisionPlan = {
+    actions: ProvisionAction[];
+    rationale: string[];
+    blocked: string[];
+    requiresSudo: boolean;
+};
+export declare function redactProvisionSnapshot(snapshot: ProvisionSnapshot): ProvisionSnapshot;

package/dist/provision/model.js

@@ -0,0 +1,5 @@
+export function redactProvisionSnapshot(snapshot) {
+    // The contract intentionally has no credential fields. Copying also prevents callers
+    // from accidentally attaching private process data to the advisor payload.
+    return JSON.parse(JSON.stringify(snapshot));
+}

package/dist/provision/planner.d.ts

@@ -0,0 +1,4 @@
+import type { ProvisionInput, ProvisionPlan, ProvisionSnapshot } from "#provision/model";
+/** Deterministic planner. It has no process or filesystem side effects. */
+export declare function createProvisionPlan(snapshot: ProvisionSnapshot, input: ProvisionInput): ProvisionPlan;
+export declare function unresolvedInputs(snapshot: ProvisionSnapshot, input: ProvisionInput): string[];

package/dist/provision/planner.js

@@ -0,0 +1,51 @@
+const sourceMissing = (snapshot, input) => !snapshot.workspace.magentoRoot && (!input.source || input.source === "existing");
+const databaseMissing = (snapshot, input) => !input.database && snapshot.database.dumps.length !== 1;
+/** Deterministic planner. It has no process or filesystem side effects. */
+export function createProvisionPlan(snapshot, input) {
+    const blocked = [];
+    const rationale = [];
+    const actions = [];
+    const environment = input.environment;
+    if (!environment)
+        blocked.push("Select --env local or --env warden.");
+    if (sourceMissing(snapshot, input))
+        blocked.push("Provide --source existing, a Git URL, archive path, or HTTPS archive URL.");
+    if (databaseMissing(snapshot, input))
+        blocked.push("Provide --database current, a dump path, or an HTTPS dump URL.");
+    if (input.database === "current" && !snapshot.database.envConfigured)
+        blocked.push("--database current requires an existing usable Magento database configuration.");
+    if (environment === "warden" && !snapshot.environments.warden.available)
+        blocked.push("Warden is not installed or available on PATH.");
+    if (environment === "local" && (!snapshot.environments.local.php || !snapshot.environments.local.composer || !snapshot.environments.local.mysql))
+        blocked.push("Local provisioning requires PHP, Composer, and the MySQL client.");
+    if (environment === "local" && snapshot.environments.local.activeServers.length === 0)
+        blocked.push("Start nginx or Apache before local provisioning.");
+    if (environment === "local" && snapshot.environments.local.activeServers.length > 1 && !input.localDomain)
+        blocked.push("Both nginx and Apache are active; choose a local domain/server interactively.");
+    if (blocked.length)
+        return { actions, rationale, blocked, requiresSudo: false };
+    if (!snapshot.workspace.magentoRoot && input.source && input.source !== "existing")
+        actions.push({ type: "acquire-source", source: input.source });
+    actions.push({ type: "install-dependencies" });
+    if (environment === "warden" && !snapshot.environments.warden.running)
+        actions.push({ type: "start-warden" });
+    const database = input.database ?? (snapshot.database.dumps.length === 1 ? `dump:${snapshot.database.dumps[0]}` : undefined);
+    if (environment === "local" && !snapshot.database.envConfigured)
+        actions.push({ type: "configure-database" });
+    if (database && database !== "current")
+        actions.push({ type: "import-database", database });
+    actions.push({ type: "magento-setup", command: "app:config:import" }, { type: "magento-setup", command: "setup:upgrade" }, { type: "magento-setup", command: "cache:clean" }, { type: "magento-setup", command: "indexer:reindex" }, { type: "magento-setup", command: "maintenance:disable" });
+    const vhost = snapshot.environments.local.vhost;
+    if (environment === "local" && !vhost) {
+        const server = snapshot.environments.local.activeServers[0];
+        const domain = input.localDomain ?? `${snapshot.workspace.root.split("/").filter(Boolean).pop().replace(/[^a-z0-9-]/gi, "-").toLowerCase()}.test`;
+        actions.push({ type: "configure-web-server", server, domain });
+        rationale.push(`Create a minimal ${server} virtual host for ${domain}.`);
+    }
+    actions.push({ type: "verify-storefront", url: environment === "warden" ? snapshot.environments.warden.domain : vhost?.domain ?? input.localDomain });
+    rationale.push("Composer uses the lock file; Magento deployment mode is preserved.");
+    return { actions, rationale, blocked, requiresSudo: actions.some((action) => action.type === "configure-web-server") };
+}
+export function unresolvedInputs(snapshot, input) {
+    return createProvisionPlan(snapshot, input).blocked;
+}

package/dist/provision/runner.d.ts

@@ -0,0 +1,35 @@
+import type { CommandExecutor } from "#environments/executor";
+import type { ProvisionAction, ProvisionEnvironment, ProvisionInput } from "#provision/model";
+export type ProvisionRunner = {
+    run(argv: string[], options?: {
+        cwd?: string;
+        input?: string;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+};
+export declare class BackendProvisionRunner implements ProvisionRunner {
+    private readonly backend;
+    constructor(backend: CommandExecutor);
+    run(argv: string[], options?: {
+        cwd?: string;
+        input?: string;
+    }): Promise<import("#environments/executor").CommandResult>;
+}
+export declare function validateArchiveEntry(entry: string): boolean;
+export declare function vhostConfig(server: "nginx" | "apache", projectRoot: string, domain: string): string;
+export declare class DefaultProvisionExecutor {
+    private readonly runner;
+    private readonly root;
+    private readonly environment;
+    private readonly magentoRunner;
+    constructor(runner: ProvisionRunner, root: string, environment: ProvisionEnvironment, magentoRunner?: ProvisionRunner);
+    execute(action: ProvisionAction, input: ProvisionInput): Promise<void>;
+    private acquire;
+    private importDatabase;
+    private configureVhost;
+    private verify;
+    private must;
+}

package/dist/provision/runner.js

@@ -0,0 +1,98 @@
+import { mkdir, rm, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+export class BackendProvisionRunner {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    run(argv, options = {}) { return this.backend.run(argv, { input: options.input }); }
+}
+export function validateArchiveEntry(entry) {
+    return entry.length > 0 && !entry.startsWith("/") && !entry.split(/[\\/]+/).includes("..");
+}
+export function vhostConfig(server, projectRoot, domain) {
+    if (!/^[a-z0-9-]+\.test$/i.test(domain))
+        throw new Error("Local domain must be a sanitized .test hostname");
+    const root = join(resolve(projectRoot), "pub");
+    return server === "nginx" ? `server { listen 80; server_name ${domain}; root ${root}; index index.php; location / { try_files $uri $uri/ /index.php?$args; } location ~ \\.php$ { try_files $uri =404; fastcgi_pass unix:/run/php/php-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }\n` : `<VirtualHost *:80>\n  ServerName ${domain}\n  DocumentRoot ${root}\n  <Directory ${root}>\n    AllowOverride All\n    Require all granted\n  </Directory>\n</VirtualHost>\n`;
+}
+export class DefaultProvisionExecutor {
+    runner;
+    root;
+    environment;
+    magentoRunner;
+    constructor(runner, root, environment, magentoRunner = runner) {
+        this.runner = runner;
+        this.root = root;
+        this.environment = environment;
+        this.magentoRunner = magentoRunner;
+    }
+    async execute(action, input) {
+        switch (action.type) {
+            case "acquire-source": return this.acquire(action.source);
+            case "install-dependencies": return this.must(["composer", "install", "--no-interaction", "--prefer-dist", "--no-progress"], this.magentoRunner);
+            case "start-warden": return this.must(["warden", "env", "config"]).then(() => this.must(["warden", "env", "start"]));
+            case "import-database": return this.importDatabase(action.database);
+            case "configure-database": throw new Error("Database configuration is required but no safe credential source was supplied. Add app/etc/env.php or use a current configured database.");
+            case "magento-setup":
+                if (action.command === "app:config:import") {
+                    const result = await this.magentoRunner.run(["bin/magento", action.command, "--no-interaction"], { cwd: this.root });
+                    if (result.exitCode !== 0 && !/does not exist|Nothing to import/i.test(result.stderr + result.stdout))
+                        throw new Error(result.stderr || result.stdout);
+                    return;
+                }
+                return this.must(["bin/magento", action.command, "--no-interaction"], this.magentoRunner);
+            case "configure-web-server": return this.configureVhost(action.server, action.domain);
+            case "verify-storefront": return this.verify(action.url);
+        }
+    }
+    async acquire(source) {
+        const entries = await stat(this.root).then(() => import("node:fs/promises").then(({ readdir }) => readdir(this.root))).catch(() => []);
+        if (entries.length)
+            throw new Error("Refusing to acquire source into a non-empty non-Magento directory.");
+        if (source.startsWith("git:"))
+            return this.must(["git", "clone", source.slice(4), "."]);
+        const location = source.replace(/^(archive|https):/, "");
+        const home = process.env.MERCHANTDUO_HOME ?? join(process.env.XDG_STATE_HOME ?? "/tmp", "merchantduo");
+        const stage = join(home, "provisions", `${Date.now()}-${basename(location).replace(/[^a-z0-9._-]/gi, "-")}`);
+        await mkdir(stage, { recursive: true });
+        try {
+            const archive = source.startsWith("https:") ? join(stage, "source.archive") : resolve(location);
+            if (source.startsWith("https:"))
+                await this.must(["curl", "--fail", "--location", "--output", archive, location]);
+            const listed = await this.runner.run(["tar", "-tzf", archive]);
+            if (listed.exitCode !== 0 || listed.stdout.split("\n").filter(Boolean).some((entry) => !validateArchiveEntry(entry)))
+                throw new Error("Archive is invalid or contains unsafe paths.");
+            await this.must(["tar", "-xzf", archive, "-C", this.root, "--strip-components=1"]);
+            const magento = await this.runner.run(["sh", "-lc", "test -f composer.json && (test -x bin/magento || grep -q 'magento/' composer.json)"], { cwd: this.root });
+            if (magento.exitCode !== 0)
+                throw new Error("Extracted archive does not contain a Magento root.");
+        }
+        finally {
+            await rm(stage, { recursive: true, force: true });
+        }
+    }
+    async importDatabase(database) {
+        const source = database.replace(/^(dump|https):/, "");
+        if (this.environment === "warden")
+            return this.must(["warden", "db", "import", source]);
+        if (database.startsWith("https:"))
+            throw new Error("Download the local database dump before local import; database credentials are never accepted as CLI arguments.");
+        return this.must(["sh", "-lc", `${source.endsWith(".gz") ? "gzip -dc --" : "cat --"} "$1" | mysql`, "merchantduo-db-import", source]);
+    }
+    async configureVhost(server, domain) {
+        const config = vhostConfig(server, this.root, domain);
+        const file = server === "nginx" ? `/etc/nginx/sites-available/${domain}` : `/etc/apache2/sites-available/${domain}.conf`;
+        const encoded = Buffer.from(config).toString("base64");
+        await this.must(["sudo", "sh", "-lc", `echo ${encoded} | base64 -d > ${file}`]);
+        if (server === "nginx")
+            await this.must(["sudo", "sh", "-lc", `ln -sfn ${file} /etc/nginx/sites-enabled/${domain} && nginx -t && systemctl reload nginx`]);
+        else
+            await this.must(["sudo", "sh", "-lc", `a2ensite ${domain}.conf && apachectl configtest && systemctl reload apache2`]);
+        await this.must(["sudo", "sh", "-lc", `grep -qE '^[[:space:]]*127\\.0\\.0\\.1[[:space:]].*\\b${domain}\\b' /etc/hosts || echo '127.0.0.1 ${domain}' >> /etc/hosts`]);
+    }
+    async verify(url) { if (url)
+        await this.must(["curl", "--fail", "--location", "--max-time", "20", `http://${url}`]); }
+    async must(argv, runner = this.runner) { const result = await runner.run(argv, { cwd: this.root }); if (result.exitCode !== 0)
+        throw new Error(`${argv.join(" ")} failed: ${result.stderr || result.stdout}`); }
+}

package/dist/shared/package-paths.d.ts

@@ -0,0 +1,3 @@
+/** Resolve an installed package asset from either src/shared or dist/shared. */
+export declare function packageRoot(): string;
+export declare function packagePath(...segments: string[]): string;

package/dist/shared/package-paths.js

@@ -0,0 +1,10 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const compiledModuleDirectory = dirname(fileURLToPath(import.meta.url));
+/** Resolve an installed package asset from either src/shared or dist/shared. */
+export function packageRoot() {
+    return resolve(compiledModuleDirectory, "../..");
+}
+export function packagePath(...segments) {
+    return resolve(packageRoot(), ...segments);
+}

package/dist/testing/discovery.d.ts

@@ -0,0 +1,10 @@
+import type { EnvironmentBackend } from "#environments/backend";
+import type { Environment } from "#environments/model";
+import type { TestingOptions, TestingSnapshot } from "#testing/model";
+export declare function discoverTesting(environment: Environment, backend: EnvironmentBackend, cwd: string, options: TestingOptions, tools?: {
+    http?: string;
+    browser?: string;
+    magerun?: string;
+}): Promise<TestingSnapshot>;
+export declare function wardenRouting(projectRoot: string): Promise<string | undefined>;
+export declare function findExecutable(candidates: string[]): Promise<string | undefined>;