@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/totals.ts

@@ -0,0 +1,314 @@
+/**
+ * The order totals engine — the single source of truth for pricing math.
+ * Used by: commerce/storefront-cart `totals` (preview), commerce/storefront-checkout
+ * `place-order` (authoritative), commerce/admin-orders `create`/`recalculate`.
+ *
+ * Pipeline (standard commerce semantics): resolve lines → coupons → fees → shipping → tax → totals.
+ * All internal math is ex-tax; tax-inclusive catalog prices are netted first.
+ */
+import { round2, distributeProportionally } from "./money.ts";
+import { applyRates, extractInclusiveTax, matchTaxRates, sumTax } from "./tax.ts";
+import { availableMethods, matchZone } from "./shipping.ts";
+import { applyCoupons } from "./coupons.ts";
+import { getSetting } from "./settings.ts";
+import { uuid } from "./sequence.ts";
+
+export interface TotalsItem {
+  product: any;
+  variation?: any;
+  quantity: number;
+  attributes?: Array<{ name: string; option: string }>;
+  meta_data?: Array<{ key: string; value: string }>;
+}
+
+export interface TotalsFee {
+  name: string;
+  amount: number;
+  tax_class?: string;
+  tax_status?: string; // taxable | none
+  line_id?: string;
+}
+
+export interface TotalsInput {
+  items: TotalsItem[];
+  coupons?: any[];  // validated Coupon records, in application order
+  fees?: TotalsFee[];
+  billing?: any;
+  shipping_address?: any;
+  chosenShippingMethodId?: string; // ShippingZoneMethod id
+  settings: Record<string, any>;   // groups object from getSettings()
+  taxRates?: any[];
+  zones?: any[];
+  zoneMethods?: any[];
+}
+
+export interface TotalsResult {
+  line_items: any[];
+  shipping_lines: any[];
+  tax_lines: any[];
+  fee_lines: any[];
+  coupon_lines: any[];
+  subtotal: number;
+  discount_total: number;
+  discount_tax: number;
+  shipping_total: number;
+  shipping_tax: number;
+  cart_tax: number;
+  total_tax: number;
+  total: number;
+  prices_include_tax: boolean;
+  available_shipping_methods: Array<{ id: string; method_id: string; title: string; cost: number }>;
+  matched_zone_id: string | null;
+}
+
+/** Effective tax class/status with variation "parent" inheritance. */
+function effectiveTax(product: any, variation?: any): { tax_class: string; tax_status: string } {
+  const status = variation?.tax_status && variation.tax_status !== "parent"
+    ? variation.tax_status
+    : product.tax_status ?? "taxable";
+  const cls = (variation?.tax_class || product.tax_class) ?? "standard";
+  return { tax_class: cls, tax_status: status };
+}
+
+function resolveTaxAddress(input: TotalsInput): any {
+  const basedOn = getSetting(input.settings, "tax", "tax_based_on", "shipping");
+  if (basedOn === "billing") return input.billing ?? input.shipping_address ?? {};
+  if (basedOn === "base") return getSetting(input.settings, "general", "address", {});
+  return input.shipping_address ?? input.billing ?? {}; // "shipping" default
+}
+
+/** Run the full totals pipeline. Pure aside from reading its inputs. */
+export function calculateTotals(input: TotalsInput): TotalsResult {
+  const settings = input.settings ?? {};
+  const taxesEnabled = !!getSetting(settings, "general", "enable_taxes", true);
+  const pricesIncludeTax = taxesEnabled && !!getSetting(settings, "tax", "prices_include_tax", false);
+  const taxRates = input.taxRates ?? [];
+  const taxAddress = resolveTaxAddress(input);
+
+  // ── 1. resolve lines (ex-tax) ────────────────────────────────────────────
+  const lines = (input.items || []).map((it) => {
+    const src = it.variation ?? it.product;
+    const { tax_class, tax_status } = effectiveTax(it.product, it.variation);
+    const rates = taxesEnabled && tax_status === "taxable" ? matchTaxRates(taxRates, taxAddress, tax_class) : [];
+    let unitPrice = Number(src.price ?? it.product?.price ?? 0);
+    let subtotal = round2(unitPrice * it.quantity);
+    if (pricesIncludeTax && rates.length) {
+      const { net } = extractInclusiveTax(subtotal, rates);
+      subtotal = net;
+      unitPrice = it.quantity ? net / it.quantity : 0;
+    }
+    return {
+      line_id: uuid(),
+      product_id: it.product?.id ?? "",
+      variation_id: it.variation?.id ?? "",
+      name: it.product?.name ?? "",
+      sku: (it.variation?.sku || it.product?.sku) ?? "",
+      quantity: it.quantity,
+      unit_price: unitPrice,
+      tax_class,
+      tax_status,
+      rates,
+      subtotal,
+      discount: 0,
+      total: subtotal,
+      subtotal_tax: 0,
+      total_tax: 0,
+      taxes: [] as any[],
+      attributes: it.attributes ?? [],
+      meta_data: it.meta_data ?? [],
+      shipping_class_id: (it.variation?.shipping_class_id || it.product?.shipping_class_id) ?? "",
+      virtual: !!(it.variation?.virtual ?? it.product?.virtual),
+      product: it.product,
+      variation: it.variation,
+    };
+  });
+
+  const itemsSubtotal = round2(lines.reduce((a, l) => a + l.subtotal, 0));
+
+  // ── 2. coupons ───────────────────────────────────────────────────────────
+  const couponsEnabled = !!getSetting(settings, "general", "enable_coupons", true);
+  const coupons = couponsEnabled ? input.coupons ?? [] : [];
+  const couponLines = applyCoupons(lines, coupons, settings);
+  for (const l of lines) l.total = round2(l.subtotal - l.discount);
+  const discountTotal = round2(lines.reduce((a, l) => a + l.discount, 0));
+  const itemsAfterDiscount = round2(lines.reduce((a, l) => a + l.total, 0));
+
+  // ── 3. fees ──────────────────────────────────────────────────────────────
+  const feeLines = (input.fees || []).map((f) => ({
+    line_id: f.line_id ?? uuid(),
+    name: f.name,
+    tax_class: f.tax_class ?? "standard",
+    tax_status: f.tax_status ?? "taxable",
+    total: round2(Number(f.amount) || 0),
+    total_tax: 0,
+    taxes: [] as any[],
+  }));
+
+  // ── 4. shipping ──────────────────────────────────────────────────────────
+  const shippingEnabled = getSetting(settings, "shipping", "enable_shipping", true) !== false;
+  const needsShipping = lines.some((l) => !l.virtual);
+  const shippingLines: any[] = [];
+  let available: Array<{ id: string; method_id: string; title: string; cost: number }> = [];
+  let matchedZoneId: string | null = null;
+
+  if (shippingEnabled && needsShipping && input.shipping_address?.country) {
+    const zone = matchZone(input.zones ?? [], input.shipping_address);
+    if (zone) {
+      matchedZoneId = zone.id ?? null;
+      const cart = { lines, itemsSubtotal, itemsSubtotalAfterDiscount: itemsAfterDiscount };
+      const offers = availableMethods(zone, input.zoneMethods ?? [], cart, settings, coupons);
+      available = offers.map((o) => ({
+        id: o.method.id,
+        method_id: o.method.method_id,
+        title: o.method.title || defaultMethodTitle(o.method.method_id),
+        cost: o.cost,
+      }));
+      if (input.chosenShippingMethodId) {
+        const chosen = offers.find((o) => o.method.id === input.chosenShippingMethodId);
+        if (chosen) {
+          shippingLines.push({
+            line_id: uuid(),
+            method_id: chosen.method.method_id,
+            instance_id: chosen.method.id,
+            method_title: chosen.method.title || defaultMethodTitle(chosen.method.method_id),
+            total: chosen.cost,
+            total_tax: 0,
+            taxes: [] as any[],
+          });
+        }
+      }
+    }
+  }
+
+  // ── 5. tax ───────────────────────────────────────────────────────────────
+  // aggregated per rate for order-level tax_lines
+  const agg = new Map<string, { rate: any; tax_total: number; shipping_tax_total: number }>();
+  const bump = (rate: any, tax: number, shippingTax: number) => {
+    const key = rate.id ?? `${rate.name}-${rate.priority}`;
+    const cur = agg.get(key) ?? { rate, tax_total: 0, shipping_tax_total: 0 };
+    cur.tax_total = round2(cur.tax_total + tax);
+    cur.shipping_tax_total = round2(cur.shipping_tax_total + shippingTax);
+    agg.set(key, cur);
+  };
+
+  if (taxesEnabled) {
+    for (const l of lines) {
+      if (!l.rates.length) continue;
+      const subApplied = applyRates(l.subtotal, l.rates);
+      const totApplied = applyRates(l.total, l.rates);
+      l.subtotal_tax = sumTax(subApplied);
+      l.total_tax = sumTax(totApplied);
+      l.taxes = totApplied.map((t, i) => ({
+        rate_id: t.rate.id ?? "",
+        total: t.amount,
+        subtotal: subApplied[i]?.amount ?? 0,
+      }));
+      for (const t of totApplied) bump(t.rate, t.amount, 0);
+    }
+    for (const fee of feeLines) {
+      if (fee.tax_status !== "taxable") continue;
+      const rates = matchTaxRates(taxRates, taxAddress, fee.tax_class);
+      const applied = applyRates(fee.total, rates);
+      fee.total_tax = sumTax(applied);
+      fee.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
+      for (const t of applied) bump(t.rate, t.amount, 0);
+    }
+    if (shippingLines.length) {
+      // shipping_tax_class "inherit" = first taxable line's class (intended behavior)
+      const cfg = getSetting(settings, "tax", "shipping_tax_class", "inherit");
+      const cls = cfg === "inherit"
+        ? (lines.find((l) => l.tax_status === "taxable")?.tax_class ?? "standard")
+        : cfg;
+      const rates = matchTaxRates(taxRates, taxAddress, cls).filter((r) => r.shipping !== false);
+      for (const sl of shippingLines) {
+        const applied = applyRates(sl.total, rates);
+        sl.total_tax = sumTax(applied);
+        sl.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
+        for (const t of applied) bump(t.rate, 0, t.amount);
+      }
+    }
+  }
+
+  // ── 6. totals ────────────────────────────────────────────────────────────
+  const cartTax = round2(
+    lines.reduce((a, l) => a + l.total_tax, 0) + feeLines.reduce((a, f) => a + f.total_tax, 0),
+  );
+  const shippingTotal = round2(shippingLines.reduce((a, s) => a + s.total, 0));
+  const shippingTax = round2(shippingLines.reduce((a, s) => a + s.total_tax, 0));
+  const totalTax = round2(cartTax + shippingTax);
+  const feesTotal = round2(feeLines.reduce((a, f) => a + f.total, 0));
+
+  // discount tax = tax saved by the discounts (subtotal tax − total tax per line),
+  // allocated across coupon lines proportionally to their discounts
+  const discountTax = round2(lines.reduce((a, l) => a + (l.subtotal_tax - l.total_tax), 0));
+  if (discountTax > 0 && couponLines.length) {
+    const shares = distributeProportionally(discountTax, couponLines.map((c) => c.discount));
+    couponLines.forEach((c, i) => { c.discount_tax = shares[i] ?? 0; });
+  }
+
+  const total = round2(itemsSubtotal - discountTotal + feesTotal + shippingTotal + totalTax);
+
+  const taxLines = [...agg.values()].map(({ rate, tax_total, shipping_tax_total }) => ({
+    rate_id: rate.id ?? "",
+    rate_code: buildRateCode(rate),
+    label: rate.name ?? "Tax",
+    rate_percent: Number(rate.rate) || 0,
+    compound: !!rate.compound,
+    tax_total,
+    shipping_tax_total,
+  }));
+
+  return {
+    line_items: lines.map(stripLine),
+    shipping_lines: shippingLines,
+    tax_lines: taxLines,
+    fee_lines: feeLines,
+    coupon_lines: couponLines,
+    subtotal: itemsSubtotal,
+    discount_total: discountTotal,
+    discount_tax: discountTax,
+    shipping_total: shippingTotal,
+    shipping_tax: shippingTax,
+    cart_tax: cartTax,
+    total_tax: totalTax,
+    total,
+    prices_include_tax: pricesIncludeTax,
+    available_shipping_methods: available,
+    matched_zone_id: matchedZoneId,
+  };
+}
+
+/** Convert an engine line to the embedded Order.line_items shape. */
+function stripLine(l: any): any {
+  return {
+    line_id: l.line_id,
+    product_id: l.product_id,
+    variation_id: l.variation_id,
+    name: l.name,
+    sku: l.sku,
+    quantity: l.quantity,
+    price: l.quantity ? round2(l.total / l.quantity) : 0, // post-discount ex-tax unit price
+    tax_class: l.tax_class,
+    subtotal: l.subtotal,
+    subtotal_tax: l.subtotal_tax,
+    total: l.total,
+    total_tax: l.total_tax,
+    taxes: l.taxes,
+    attributes: l.attributes,
+    meta_data: l.meta_data,
+  };
+}
+
+function buildRateCode(rate: any): string {
+  const parts = [rate.country || "ANY", rate.state || "", (rate.name || "TAX").replace(/\s+/g, "-"), String(rate.priority ?? 1)];
+  return parts.filter(Boolean).join("-").toUpperCase();
+}
+
+function defaultMethodTitle(methodId: string): string {
+  switch (methodId) {
+    case "flat_rate": return "Flat rate";
+    case "free_shipping": return "Free shipping";
+    case "local_pickup": return "Local pickup";
+    default: return methodId;
+  }
+}

package/base44/shared/commerce/webhooks.ts

@@ -0,0 +1,116 @@
+/**
+ * Webhook dispatch (standard webhook headers + HMAC signature).
+ * Fire-and-forget safe: every failure is swallowed and logged — a broken
+ * webhook endpoint must never break an order flow.
+ */
+
+const MAX_BODY = 32 * 1024; // truncate logged request/response bodies at 32KB
+const TIMEOUT_MS = 10_000;
+const AUTO_DISABLE_AFTER = 5; // consecutive failures
+
+async function hmacSha256Base64(secret: string, payload: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
+  let bin = "";
+  for (const b of new Uint8Array(sig)) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+
+/**
+ * Deliver `payload` to every active webhook subscribed to `topic`
+ * (e.g. "order.created"). Logs each attempt as a WebhookDelivery, maintains
+ * failure_count, and auto-disables a hook after 5 consecutive failures.
+ */
+export async function dispatch(sr: any, topic: string, payload: unknown): Promise<void> {
+  try {
+    const hooks = (await sr.entities["commerce.Webhook"].filter({ status: "active", topic })) ?? [];
+    for (const hook of hooks) {
+      await deliverOne(sr, hook, topic, payload);
+    }
+  } catch (e) {
+    console.error(`webhook dispatch(${topic}) failed:`, e);
+  }
+}
+
+/** Deliver to a single webhook record; used by dispatch and commerce/admin-webhooks test/redeliver. */
+export async function deliverOne(sr: any, hook: any, topic: string, payload: unknown): Promise<any> {
+  const [resource, event] = topic.split(".");
+  const body = JSON.stringify(payload ?? {});
+  const started = Date.now();
+
+  // create the delivery record first so its id can ride in the header
+  let delivery: any = null;
+  try {
+    delivery = await sr.entities["commerce.WebhookDelivery"].create({
+      webhook_id: hook.id,
+      topic,
+      delivery_url: hook.delivery_url,
+      request_headers: {},
+      request_body: body.slice(0, MAX_BODY),
+      response_code: 0,
+      response_body: "",
+      duration_ms: 0,
+      success: false,
+    });
+  } catch (e) {
+    console.error("webhook delivery log create failed:", e);
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Commerce-Webhook-Topic": topic,
+    "X-Commerce-Webhook-Resource": resource ?? "",
+    "X-Commerce-Webhook-Event": event ?? "",
+    "X-Commerce-Webhook-ID": hook.id ?? "",
+    "X-Commerce-Webhook-Delivery-ID": delivery?.id ?? "",
+  };
+  if (hook.secret) {
+    try {
+      headers["X-Commerce-Webhook-Signature"] = await hmacSha256Base64(hook.secret, body);
+    } catch { /* signature best-effort */ }
+  }
+
+  let responseCode = 0;
+  let responseBody = "";
+  let success = false;
+  try {
+    const res = await fetch(hook.delivery_url, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    responseCode = res.status;
+    responseBody = (await res.text()).slice(0, MAX_BODY);
+    success = res.ok;
+  } catch (e) {
+    responseBody = String((e as Error)?.message ?? e).slice(0, MAX_BODY);
+  }
+
+  const duration = Date.now() - started;
+  try {
+    if (delivery) {
+      await sr.entities["commerce.WebhookDelivery"].update(delivery.id, {
+        request_headers: headers,
+        response_code: responseCode,
+        response_body: responseBody,
+        duration_ms: duration,
+        success,
+      });
+    }
+    const failureCount = success ? 0 : (hook.failure_count ?? 0) + 1;
+    const patch: any = { failure_count: failureCount };
+    if (!success && failureCount >= AUTO_DISABLE_AFTER) patch.status = "disabled";
+    await sr.entities["commerce.Webhook"].update(hook.id, patch);
+  } catch (e) {
+    console.error("webhook delivery bookkeeping failed:", e);
+  }
+
+  return { delivery_id: delivery?.id ?? "", response_code: responseCode, success, duration_ms: duration };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@base44/app-plugin-commerce",
+  "version": "0.1.0",
+  "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
+  "keywords": [
+    "base44",
+    "base44-plugin",
+    "commerce",
+    "ecommerce",
+    "store",
+    "template"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/base44/app-plugin-commerce.git"
+  },
+  "homepage": "https://github.com/base44/app-plugin-commerce#readme",
+  "bugs": {
+    "url": "https://github.com/base44/app-plugin-commerce/issues"
+  },
+  "files": [
+    "base44",
+    "scripts",
+    "skills",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Base44 Commerce Template — static installer.
+ *
+ * Assumes this entire template repository has been copied into the target
+ * Base44 app at `<app-root>/examples/commerce/`, so this script runs from
+ * `<app-root>/examples/commerce/scripts/`. From the app root:
+ *
+ *   node examples/commerce/scripts/install.js
+ *
+ * It copies the template's static file set into the app. Paths are relative
+ * to this script's folder — the template root is `..` and the app root is
+ * `../../..` (scripts → commerce → examples → app root):
+ *
+ *   ../base44/entities/commerce.*.jsonc  →  ../../../base44/entities/
+ *   ../base44/functions/commerce/        →  ../../../base44/functions/commerce/
+ *   ../base44/shared/commerce/           →  ../../../base44/shared/commerce/
+ *   ../base44/agents/commerce/           →  ../../../base44/agents/commerce/
+ *   ../src/commerce/admin/               →  ../../../src/commerce/admin/
+ *   ../src/commerce/utils/               →  ../../../src/commerce/utils/
+ *   ../skills/commerce/                  →  ../../../skills/commerce/
+ *
+ * Merge semantics: directories are merged — files owned by the template are
+ * overwritten (so re-running after a template update is safe), everything
+ * else in the app is left untouched.
+ *
+ * This is only the static part of the install. The remaining steps live in
+ * ../skills/commerce/installation-guidelines.md (deps, deploy, seeding) and
+ * ../skills/commerce/post-installation.md (mounting the /admin route, admin
+ * role, AGENTS.md registration); day-2 guidance starts at
+ * ../skills/commerce/SKILL.md. The skill folder carries all of this
+ * documentation into the app.
+ *
+ * Written with dynamic import() and process.argv[1] (instead of require/
+ * __dirname) so it runs unchanged whether the host app's package.json is
+ * CommonJS or "type": "module".
+ */
+
+(async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+
+  const fail = (msg) => {
+    console.error(`install.js: ${msg}`);
+    process.exit(1);
+  };
+
+  const scriptArg = process.argv[1];
+  if (!scriptArg) fail("cannot determine the script location (run as: node examples/commerce/scripts/install.js)");
+  const scriptDir = path.dirname(path.resolve(scriptArg));
+  const templateRoot = path.resolve(scriptDir, "..");        // <app>/examples/commerce
+  const appRoot = path.resolve(scriptDir, "..", "..", ".."); // <app>
+
+  // ── sanity checks ──────────────────────────────────────────────────────────
+  const entitiesSrc = path.join(templateRoot, "base44", "entities");
+  if (!fs.existsSync(entitiesSrc)) {
+    fail(`template assets not found at ${path.join(templateRoot, "base44")} — is the repo intact?`);
+  }
+  if (!fs.existsSync(path.join(appRoot, "package.json"))) {
+    fail(
+      `no package.json at ${appRoot} — expected the template at <app-root>/examples/commerce/ ` +
+      `so that the app root is three levels above this script's folder.`
+    );
+  }
+  const relToApp = path.relative(appRoot, templateRoot).split(path.sep).join("/");
+  if (relToApp !== "examples/commerce") {
+    console.warn(
+      `install.js: warning — template is installed at "${relToApp}" instead of "examples/commerce"; ` +
+      `proceeding, but doc references assume examples/commerce.`
+    );
+  }
+
+  // ── copy helpers (merge: overwrite template-owned files, keep the rest) ───
+  let filesCopied = 0;
+  const copyFile = (src, dest) => {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    filesCopied += 1;
+  };
+  const copyDir = (src, dest) => {
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const s = path.join(src, entry.name);
+      const d = path.join(dest, entry.name);
+      if (entry.isDirectory()) copyDir(s, d);
+      else copyFile(s, d);
+    }
+  };
+
+  // ── retired files ─────────────────────────────────────────────────────────
+  // Copying merges, so a template file that gets renamed would otherwise linger
+  // in the app forever — and stale guidance is worse than none, since agents
+  // read whatever is in skills/. Anything this template used to own and no
+  // longer ships is listed here and removed on install.
+  const RETIRED = [
+    ["skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
+  ];
+  let retiredRemoved = 0;
+  for (const parts of RETIRED) {
+    const target = path.join(appRoot, ...parts);
+    if (!fs.existsSync(target)) continue;
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      retiredRemoved += 1;
+      console.log(`✓ removed    ${parts.join("/")} (retired by a newer template version)`);
+    } catch (e) {
+      console.warn(`install.js: warning — could not remove retired ${parts.join("/")}: ${e.message}`);
+    }
+  }
+
+  // ── the static installation ───────────────────────────────────────────────
+  const entityFiles = fs
+    .readdirSync(entitiesSrc)
+    .filter((n) => n.startsWith("commerce.") && n.endsWith(".jsonc"));
+  if (entityFiles.length === 0) fail(`no commerce.*.jsonc entity schemas found in ${entitiesSrc}`);
+  for (const name of entityFiles) {
+    copyFile(path.join(entitiesSrc, name), path.join(appRoot, "base44", "entities", name));
+  }
+  console.log(`✓ entities   ${entityFiles.length} commerce.*.jsonc schemas → base44/entities/`);
+
+  const dirJobs = [
+    { label: "functions", from: ["base44", "functions", "commerce"], to: ["base44", "functions", "commerce"] },
+    { label: "shared", from: ["base44", "shared", "commerce"], to: ["base44", "shared", "commerce"] },
+    // StoreAdmin agent — registered as "commerce/StoreAdmin" (folder = namespace).
+    { label: "agents", from: ["base44", "agents", "commerce"], to: ["base44", "agents", "commerce"] },
+    { label: "admin UI", from: ["src", "commerce", "admin"], to: ["src", "commerce", "admin"] },
+    // Storefront helpers (variant selection) — framework-free, for the
+    // customer-facing UI the app builds itself.
+    { label: "utils", from: ["src", "commerce", "utils"], to: ["src", "commerce", "utils"] },
+    // Commerce skill — SKILL.md, install/post-install guides, references/
+    // and docs/, the guidance agents read before working on the store.
+    { label: "skills", from: ["skills", "commerce"], to: ["skills", "commerce"] },
+  ];
+  for (const job of dirJobs) {
+    const src = path.join(templateRoot, ...job.from);
+    if (!fs.existsSync(src)) fail(`missing template directory: ${src}`);
+    const before = filesCopied;
+    copyDir(src, path.join(appRoot, ...job.to));
+    console.log(`✓ ${job.label.padEnd(10)} ${filesCopied - before} files → ${job.to.join("/")}/`);
+  }
+
+  console.log(
+    `\nDone — ${filesCopied} files installed into ${appRoot}` +
+    (retiredRemoved ? ` (${retiredRemoved} retired file${retiredRemoved === 1 ? "" : "s"} removed)` : ""),
+  );
+  console.log(
+    "\nNext steps (see skills/commerce/installation-guidelines.md + post-installation.md):\n" +
+    "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
+    "     Base44 template — just confirm they're there (npm i sonner recharts if not)\n" +
+    '  2. Mount the admin router: <Route path="/admin/*" element={<AdminApp />} />\n' +
+    "     and implement the payment return page /order-received (post-installation.md)\n" +
+    "  3. Grant your user the admin role, then settle the store's data — generate a catalog,\n" +
+    "     seed the demo data, or initialize defaults from /admin (post-installation.md §2)\n" +
+    "  4. Register the template + skill in AGENTS.md (see skills/commerce/post-installation.md)\n" +
+    "  5. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
+  );
+})();