@merchantduo/code 0.3.0-beta.0 → 0.3.0-beta.2

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

@@ -16,6 +16,7 @@ type SearchParameters = {
  */
 export declare function searchCommand(params: SearchParameters, path: string): string;
 export declare function workspacePath(backend: EnvironmentBackend, cwd: string, candidate: string): string;
+export declare function wardenHostPathWarning(backend: EnvironmentBackend, cwd: string, candidate: string): string | undefined;
 /** Return only a declared MerchantDuo skill asset; project files remain environment-routed. */
 export declare function packagedSkillPath(candidate: string): string | undefined;
 export {};

package/dist/integrations/pi/workspace.js

@@ -1,9 +1,10 @@
 import { access as hostAccess, readFile as hostReadFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { Type } from "typebox";
 import { createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "@earendil-works/pi-coding-agent";
 import { runtime } from "#integrations/pi/session";
 import { packagePath } from "#shared/package-paths";
+import { postEditHints, validateMagentoXml } from "#workflows/post-edit";
 const shell = (value) => `'${value.replace(/'/g, "'\\''")}'`;
 const result = (value) => ({ content: [{ type: "text", text: value }], details: {} });
 const packageSkillRoots = [
@@ -34,9 +35,19 @@ function registerFileTools(pi) {
     const localRead = createReadToolDefinition(process.cwd());
     const localWrite = createWriteToolDefinition(process.cwd());
     const localEdit = createEditToolDefinition(process.cwd());
-    pi.registerTool({ ...localRead, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createReadToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
-    pi.registerTool({ ...localWrite, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createWriteToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
-    pi.registerTool({ ...localEdit, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createEditToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
+    pi.registerTool({ ...localRead, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createReadToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendNotice(response, wardenHostPathWarning(state.backend, ctx.cwd, params.path)); } });
+    pi.registerTool({ ...localWrite, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createWriteToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendPostEdit(response, state.backend, ctx.cwd, params.path, signal); } });
+    pi.registerTool({ ...localEdit, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createEditToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendPostEdit(response, state.backend, ctx.cwd, params.path, signal); } });
+}
+async function appendPostEdit(response, backend, cwd, path, signal) {
+    const target = workspacePath(backend, cwd, path);
+    const validation = await validateMagentoXml(backend, target, signal);
+    return appendNotice(response, [wardenHostPathWarning(backend, cwd, path), ...postEditHints(path), validation].filter((value) => Boolean(value)).join("\n"));
+}
+function appendNotice(response, notice) {
+    if (!notice)
+        return response;
+    return { ...response, content: [...response.content, { type: "text", text: `MerchantDuo: ${notice}` }] };
 }
 function fileOps(backend, cwd) {
     const readFile = async (path) => {
@@ -58,8 +69,27 @@ function fileOps(backend, cwd) {
             throw new Error("Path is inaccessible"); }, mkdir: async (path) => { const response = await backend.run(["mkdir", "-p", workspacePath(backend, cwd, path)]); if (response.exitCode)
             throw new Error(response.stderr || "Cannot create directory"); } };
 }
-export function workspacePath(backend, cwd, candidate) { const full = resolve(cwd, candidate); const value = relative(resolve(cwd), full); if (value === ".." || value.startsWith("../"))
-    throw new Error(`Path escapes workspace: ${candidate}`); return backend.path(value); }
+export function workspacePath(backend, cwd, candidate) {
+    if (backend.environment.type === "warden" && isAbsolute(candidate)) {
+        const containerPath = resolve(candidate);
+        if (contains(resolve(backend.environment.root), containerPath))
+            return containerPath;
+    }
+    const full = resolve(cwd, candidate);
+    const value = relative(resolve(cwd), full);
+    if (value === ".." || value.startsWith("../"))
+        throw new Error(`Path escapes workspace: ${candidate}`);
+    return backend.path(value);
+}
+export function wardenHostPathWarning(backend, cwd, candidate) {
+    if (backend.environment.type !== "warden" || !isAbsolute(candidate))
+        return undefined;
+    const hostPath = resolve(candidate);
+    if (!contains(resolve(cwd), hostPath))
+        return undefined;
+    const value = relative(resolve(cwd), hostPath);
+    return `Warden path warning: ${candidate} was mapped to ${backend.path(value)}. This session runs inside Warden; use the container path next time.`;
+}
 /** Return only a declared MerchantDuo skill asset; project files remain environment-routed. */
 export function packagedSkillPath(candidate) {
     const full = resolve(candidate);

package/dist/workflows/post-edit.d.ts

@@ -0,0 +1,7 @@
+import type { EnvironmentBackend } from "#environments/backend";
+/** Keep immediate post-edit guidance narrow; operational work remains an explicit request. */
+export declare function postEditHints(path: string): string[];
+export declare function isMagentoXml(path: string): boolean;
+/** Validate changed Magento XML in its own selected environment using Magento's URN resolver. */
+export declare function validateMagentoXml(backend: EnvironmentBackend, path: string, signal?: AbortSignal): Promise<string>;
+export declare function xmlValidationCommand(path: string): string[];

package/dist/workflows/post-edit.js

@@ -0,0 +1,51 @@
+const xsdValidator = String.raw `
+$file = $argv[1] ?? '';
+libxml_use_internal_errors(true);
+$dom = new DOMDocument();
+if (!$dom->load($file)) {
+    foreach (libxml_get_errors() as $error) fwrite(STDERR, trim($error->message) . " at line " . $error->line . "\n");
+    exit(2);
+}
+$root = $dom->documentElement;
+$schema = $root ? $root->getAttributeNS('http://www.w3.org/2001/XMLSchema-instance', 'noNamespaceSchemaLocation') : '';
+if (!$schema || strpos($schema, 'urn:magento:') !== 0) {
+    fwrite(STDERR, "Magento XML must declare xsi:noNamespaceSchemaLocation with a urn:magento schema.\n");
+    exit(2);
+}
+require getcwd() . '/app/bootstrap.php';
+$errors = Magento\Framework\Config\Dom::validateDomDocument($dom, $schema);
+if ($errors) {
+    foreach ($errors as $error) fwrite(STDERR, (string)$error . "\n");
+    exit(2);
+}
+echo "Magento XML XSD validation passed.\n";
+`;
+/** Keep immediate post-edit guidance narrow; operational work remains an explicit request. */
+export function postEditHints(path) {
+    const value = path.toLowerCase();
+    const hints = ["Inspect the changed file and its closest Magento precedent before continuing."];
+    if (value.endsWith(".php") || value.endsWith(".phtml"))
+        hints.push("Use magento_workflow action=syntax-check when PHP syntax verification is relevant.");
+    if (value.endsWith(".xml"))
+        hints.push("Review the XSD result below; preview a cache clean only when this configuration change requires it.");
+    if (value.endsWith("etc/module.xml") || value.endsWith("db_schema.xml") || value.endsWith("composer.json"))
+        hints.push("This may require setup:upgrade; explain the evidence and use magento_workflow only after the user directly requests execution.");
+    return hints;
+}
+export function isMagentoXml(path) {
+    return path.toLowerCase().endsWith(".xml")
+        && /(?:^|\/)(?:app\/(?:code|design)|vendor)\//.test(path.replace(/\\/g, "/"));
+}
+/** Validate changed Magento XML in its own selected environment using Magento's URN resolver. */
+export async function validateMagentoXml(backend, path, signal) {
+    if (!isMagentoXml(path))
+        return "";
+    const output = await backend.run(xmlValidationCommand(path), { signal });
+    const detail = `${output.stdout}${output.stderr}`.trim();
+    return output.exitCode === 0
+        ? detail || "Magento XML XSD validation passed."
+        : `Warning: Magento XML XSD validation failed for ${path}: ${detail || "validation could not run."}`;
+}
+export function xmlValidationCommand(path) {
+    return ["php", "-r", xsdValidator, path];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merchantduo/code",
-  "version": "0.3.0-beta.0",
+  "version": "0.3.0-beta.2",
   "private": false,
   "description": "Magento-native Pi-based Coding Agent",
   "type": "module",
@@ -12,7 +12,6 @@
     "#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",

package/skills/magento-2.4/SKILL.md

@@ -1,8 +1,247 @@
 ---
-name: magento-24x
-description: Magento Open Source and Adobe Commerce 2.4 implementation guidance.
+name: magento-extension-best-practices
+description: Choose and review Magento Open Source / Adobe Commerce 2.4.x extension architecture. Load for non-trivial work involving DI, plugins, preferences, observers, service contracts, persistence, schema/XML, caching, indexers, queues, Admin UI, Luma, Hyvä, REST, GraphQL, security, or testing.
 ---
 
+# Magento Extension Best Practices
+
+## Extension Decision Order
+
+When changing existing behavior, prefer the first mechanism that fully solves the requirement:
+
+1. XML or declarative configuration.
+2. Public `@api` contract or documented extension point.
+3. Existing strategy, pool, composite, provider, resolver, or other composition mechanism.
+4. Semantic event + observer for an independent reaction.
+5. `before` / `after` plugin for a narrow public-method change.
+6. `around` plugin only when execution must be wrapped, skipped, or replaced.
+7. Preference/inheritance for deliberate implementation replacement or non-interceptable behavior.
+8. Undocumented internals only as an isolated, upgrade-sensitive last resort.
+
+## Module Boundaries
+
+- Prefer public `@api` contracts across modules.
+- Isolate unavoidable concrete non-`@api` dependencies behind your own adapter/service and regression coverage.
+- Put package dependencies in `composer.json`.
+- Use `<sequence>` only when Magento config/setup/view load order matters.
+- Create interfaces for public contracts, substitution boundaries, multiple implementations, or deliberately stable module boundaries; not for every service.
+
+## DI and Object Creation
+
+- **DI:** normal dependency known at wiring time.
+- **Factory:** runtime/transient/entity instance creation.
+- **Proxy:** lazy-load an expensive dependency that is often unused.
+- **Virtual type:** same class with different constructor arguments in a specific injection context.
+- **Preference:** deliberate implementation binding/replacement.
+
+Do not use factories to hide ordinary dependencies or proxies as generic performance decoration.
+
+## Plugins, Preferences, Events
+
+### Plugins
+
+- `before`: small argument changes.
+- `after`: result changes.
+- `around`: only when wrapping/skipping/replacing execution is required.
+- If `before` or `after` works, do not use `around`.
+- Keep plugins small and stateless.
+- Delegate business logic to services.
+- Do not plugin your own module when direct composition/refactoring is available.
+- Interception is for supported public methods; final/non-public/static methods and constructors are not normal plugin targets.
+
+### Preferences / Inheritance
+
+Preferences are valid for deliberate implementation binding or full replacement.
+
+Avoid a preference merely to change one public method. If replacement is necessary:
+
+- override the minimum surface;
+- do not copy whole core/vendor classes;
+- isolate dependency on internals;
+- add upgrade regression coverage.
+
+### Events
+
+Use observers for existing semantic events and independent side effects. Use plugins when changing a method's arguments, result, or execution.
+
+Keep observers small and delegate work. Prefer area-specific `events.xml` when applicable. Do not rely on event-payload mutation as a hidden behavior override.
+
+## Data Access
+
+Repositories are module/API boundaries, not a universal internal persistence rule.
+
+Use repositories/service contracts for public or cross-module entity access, standard CRUD/list contracts, `SearchCriteria`, API data interfaces, and extension attributes.
+
+Internal code may use:
+
+- collections for filtering/list/batch reads;
+- resource models for persistence;
+- dedicated query services for joins, reports, projections, or aggregates;
+- `ResourceConnection` for deliberate bulk/index/import work.
+
+Avoid new Active Record-style `$model->load()` / `$model->save()` usage.
+
+### Direct SQL
+
+Direct SQL is acceptable in resource/query layers when Magento entity lifecycle is intentionally unnecessary.
+
+Use Magento DB adapters, resolved table names, and parameter bindings. Do not bypass required validation, business invariants, cache invalidation, events, or indexer/MView behavior.
+
+### Performance and Concurrency
+
+- Avoid repository/entity loads in large loops.
+- Prevent N+1 extension-attribute and GraphQL loading.
+- Prefer batch reads, joins, collections, or query services.
+- Keep DB transactions small; avoid network calls inside long transactions.
+- Use DB constraints, atomic updates, locks, or retries for concurrency-critical invariants.
+- Make retryable queue/cron/bulk handlers idempotent where duplicate delivery or overlap is possible.
+
+## Declarative Configuration
+
+Before runtime PHP, check for an existing Magento mechanism:
+
+`di.xml`, `events.xml`, `routes.xml`, `webapi.xml`, `acl.xml`, `system.xml`, `config.xml`, `menu.xml`, `email_templates.xml`, `cron.xml`, `communication.xml`, `queue_*`, `indexer.xml`, `mview.xml`, `extension_attributes.xml`, layout XML, UI component XML, `db_schema.xml`.
+
+Respect global vs area-scoped configuration. Do not assume every XML type merges identically.
+
+## Schema Changes
+
+For new Magento 2.4.x modules:
+
+- prefer `db_schema.xml` for schema;
+- use data patches for one-time data changes;
+- use schema patches only when imperative schema work is genuinely needed;
+- treat `InstallSchema`, `UpgradeSchema`, `InstallData`, and `UpgradeData` as legacy patterns.
+
+For large production tables, review locking, backfills, deployment safety, indexes, and foreign-key behavior.
+
+## Cache and Indexers
+
+Treat FPC as an architectural constraint.
+
+- Avoid broad `cacheable="false"`.
+- Keep customer-specific data out of public FPC output; use the proper private-content mechanism.
+- Return correct cache identities/tags.
+- Never global `cache:flush` after normal writes.
+- Invalidate only relevant cache data or rely on Magento lifecycle invalidation.
+- Include store/customer/website/authorization dimensions in cache variation when required.
+
+Code must work with indexers in both **Update on Save** and **Update by Schedule** modes.
+
+Do not full-reindex after every write. With direct SQL, verify index invalidation and MView changelog behavior.
+
+## Async Work
+
+Use message queues for slow, high-volume, retryable, or integration-heavy work.
+
+Use cron mainly for scheduling/discovery; use consumers for scalable units of work. Prefer Magento queue configuration over bespoke polling infrastructure.
+
+## Frontend
+
+### Luma
+
+Prefer:
+
+1. Layout XML.
+2. ViewModel.
+3. Minimal template override.
+4. RequireJS mixin for existing AMD behavior.
+5. New JS module/component with declarative initialization.
+6. Full replacement only when necessary.
+
+Use ViewModels for template-facing behavior/data. Prefer `data-mage-init` / `x-magento-init`. Avoid copying whole vendor PHTML/JS files. Do not instantiate services in templates.
+
+Use Knockout/UI Components where the existing Magento surface already uses them, especially checkout and complex Admin UI.
+
+### Hyvä
+
+Treat Hyvä as a separate frontend runtime.
+
+- Do not assume RequireJS, Knockout, jQuery, or Luma `customer-data` on normal Hyvä pages.
+- Prefer Alpine.js and Hyvä ViewModels/private-content mechanisms.
+- Check installed Hyvä versions before relying on Tailwind/Alpine details.
+- Use compatibility modules or isolated Luma fallback when appropriate.
+
+## Admin
+
+Use UI Components for standard Magento grids/forms where data sources, filters, bookmarks, mass actions, or existing component hierarchies are useful.
+
+For simple bespoke pages, layout + block/ViewModel/template may be clearer.
+
+Authorization must be backend-enforced. Controllers/routes and relevant UI data endpoints need proper ACL; hiding UI elements is not authorization.
+
+## REST / SOAP / GraphQL
+
+Expose stable service-contract methods through `webapi.xml` with correct ACL. Reuse business services across transports.
+
+Keep GraphQL resolvers thin. Delegate logic, batch-load to avoid N+1, enforce authentication plus ownership/resource access, and return cache identities when required. Prefer token-based API auth over PHP-session-dependent API designs.
+
+## State Boundaries
+
+Do not inject checkout/customer/backend sessions, `RequestInterface`, cookies, or implicit request state into reusable business services.
+
+Adapters should extract explicit context such as `customerId`, `quoteId`, `storeId`, or `websiteId` and pass it to services.
+
+## Security
+
+Verify:
+
+- context-appropriate output escaping;
+- CSRF/form-key and correct HTTP method for browser state changes;
+- Admin/API/GraphQL ACL and object ownership;
+- bound SQL parameters;
+- safe filesystem/upload handling and validation;
+- no unsafe unserialization or command execution on untrusted input.
+
+## Testing
+
+- **Unit:** pure services, value objects, algorithms.
+- **Integration:** DI/XML, DB, repositories, plugins, observers, indexers, cache.
+- **API functional:** REST/GraphQL contracts, auth, serialization.
+- **MFTF:** critical browser workflows.
+
+Test observable behavior, not interceptor implementation details. Add regression tests for upgrade-sensitive overrides.
+
+## Red Flags
+
+Redesign or explicitly justify:
+
+- `ObjectManager::get()` in feature code;
+- `$model->load()` / `$model->save()` in new code;
+- large observers;
+- business workflows in plugins;
+- `around` for simple argument/result changes;
+- preference for one public method;
+- copied core/vendor classes or unnecessary copied PHTML/JS;
+- repository/entity loads in large loops;
+- global cache flush after normal writes;
+- session/request state deep in business logic;
+- direct SQL bypassing required Magento lifecycle;
+- UI Components for every Admin page;
+- direct edits under `vendor/`.
+
+## Final Review
+
+Before finalizing an implementation, verify:
+
+1. Is there already an XML/declarative solution?
+2. Is there a public API or narrower documented extension point?
+3. Am I replacing more code than necessary?
+4. Am I relying on non-public internals?
+5. Could composition replace inheritance/preference?
+6. Is `around` truly required?
+7. Is business logic trapped in a plugin/observer/resolver/controller?
+8. Is the data-access method appropriate, or merely habitual?
+9. Can this create N+1 queries?
+10. Does request/session state leak into reusable services?
+11. Is it correct under FPC, indexers/MView, retries, concurrency, and production DI compilation?
+12. Are ACL, ownership, escaping, SQL bindings, and CSRF correct?
+13. Will it survive the next Magento/vendor patch update?
+
+For production-sensitive changes, validate relevant paths with `setup:di:compile`, production mode, static content deployment where applicable, cache/indexer modes, cron/consumers, and Magento Coding Standard checks.
+
+## MerchantDuo Magento 2.4 session workflow
+
 # Magento 2.4
 
 Confirm the installed Magento version, edition, and deployment mode before changing framework behavior. Prefer a focused module, declarative schema and data patches, dependency injection, service contracts, layout XML, and Magento CLI validation. Do not read `app/etc/env.php`.

package/dist/provision/advisor.d.ts

@@ -1,12 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,82 +0,0 @@
-/** 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

@@ -1,5 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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[];