Ace commands

node ace configure @adocommercekit/core registers the core command entrypoint in adonisrc.ts, and node ace configure @adocommercekit/id registers the Indonesian commands. Run commands from the host AdonisJS application.

commerce:doctor

node ace commerce:doctor

Starts the application and verifies:

• every required Adocommerce Kit table exists under the configured prefix, including payment_instructions, state_transitions, order_number_counters, and outbox;
• every payment driver can report its capabilities;
• every deferred driver implements retrieveIntent;
• each driver’s optional healthCheck() succeeds; Midtrans and Xendit ping their API with the configured credentials, while kode-unik checks that its lease tables are reachable;
• production hosts with a deferred driver registered use jobs.dispatcher: 'queue';
• the reorder_point column exists on inventory_levels, which the admin list filters and dashboard low-stock panel depend on;
• stored inventory reserved totals equal the reservation ledger.

With @adocommercekit/admin-api configured it also checks the audit table, unmapped abilities, group authentication, per-route ability coverage, and CSRF exemptions. With @adocommercekit/admin configured it adds the panel’s routes preload, group authentication, per-route ability coverage, CSRF exemptions, the Tailwind v4 Vite plugin, the dashboard page, the host UI dependency set, and the content hash of every vendored coss/Bklit file. A vendored file that no longer matches its recorded hash is a warning, not a failure: doctor cannot distinguish a deliberate re-pull with npx shadcn@latest add from tampering, so it names the files and leaves the judgement to you. Every check is skipped when the package that owns it is not installed.

The command exits with code 1 and prints every detected failure. Run it after migrations, configuration changes, package upgrades, and production deployment.

Doctor does not mutate data, repair inventory, or replace application-specific health checks. It reaches the network only through a driver that implements healthCheck().

commerce:seed:demo

node ace commerce:seed:demo

Creates a deterministic Field Supply sample store in the current database:

• web and retail channels;
• a category tree (Apparel, Footwear, Packs, Camp, Accessories);
• 20 outdoor products with product-specific option matrices, descriptions, and mixed statuses;
• USD, EUR, and IDR prices with quantity breaks;
• two stock locations with healthy, low, empty, reserved, and backorder inventory;
• shipping methods and US/ID tax records used by the storefront guide.

If the products table already contains a product, the command makes no changes. Use it only for development, demonstrations, or disposable review environments.

node ace commerce:id:seed:demo

Playground-only follow-on for the Indonesian Field Supply demo. Requires commerce:seed:demo first. It:

• switches the web channel default currency to IDR and stamps host brand values;
• imports a small synthetic Indonesia region tree;
• creates member/wholesale customer groups, Indonesian customers, and addresses;
• seeds ~50 FS-* orders across payment and fulfillment lifecycles with relative date windows;
• adds QRIS / BCA VA / GoPay / COD / kode unik payment rows, shipments, and refunds;
• gives every order the completed cart it converted from, then layers abandoned, active, and checking-out carts on top so the dashboard funnel narrows from carts to paid orders;
• adds IDR local delivery and loft pickup shipping methods.

Re-running skips operational history when FS-* orders already exist, but still refreshes the IDR catalog overlay and regions.

commerce:extend <model>

node ace commerce:extend product

Publishes a host subclass in app/models/commerce and adds its lazy loader to config/commerce.ts.

Supported registry keys:

channel
product
productOption
productOptionValue
productVariant
category
priceList
price
customerGroup
customer
address
cart
cartLine
cartAdjustment
shippingMethod
taxZone
taxRate
taxCategory

Add host columns with a new host migration. Do not change the inherited Adocommerce Kit table name or registry key. See Extend a model.

commerce:upgrade

node ace commerce:upgrade
node ace commerce:upgrade --yes

Compares installed publication baselines, host files, package sources, and migration markers.

The command also offers any missing ordered Adocommerce Kit migrations. It never edits an already-published migration.

When @adocommercekit/admin is installed, the report gains four panel sections before the prompts: vendored: re-vendored, new, or dropped UI components with their upstream repository, commit, and previous hash; i18n: catalog keys this engine version added; nav: navigation items it added; and ability: abilities it added, with a reminder that an unmapped ability leaves its route at 403.

Without --yes, every changed publication and migration batch requires confirmation. --yes accepts every offered add/update/stage action, but it does not resolve conflicts.

Publication bases live under .commercekit/publications; conflicts live under .commercekit/incoming. Commit the bases so each environment uses the same three-way merge ancestor. Follow the upgrade procedure before deployment.

commerce:id:regions-import

node ace commerce:id:regions-import --file=storage/regions/kemendagri-2025-01.json

Imports an administrative-region source into the host database. No region rows ship inside @adocommercekit/id, so this command is the only way to populate them, and the licensed source is the host’s responsibility.

The JSON document requires a provenance object and a regions array:

A non-HTTPS URL or a checksum that is not a 64-character SHA-256 digest aborts the import. On success the command reports the imported region and postal-mapping counts with the stored version and checksum. Each import is a new version, so provenance stays auditable.

commerce:id:ppn-audit

node ace commerce:id:ppn-audit --month=2026-07
node ace commerce:id:ppn-audit --month=2026-07 --output=storage/ppn/2026-07.csv

Exports a ledger-reconciled PPN CSV for one YYYY-MM month and prints the ledger total. Without --output the CSV goes to stdout.

The export reflects what ppnCalculator() recorded in adjustment metadata: statutory rate, DPP fraction and amount, rounding, price mode, and category. PPnBM is not calculated. Do not describe the output as e-Faktur or Coretax compatible without a separately certified mapping.

commerce:id:cod-import

node ace commerce:id:cod-import --file=storage/cod/biteship-2026-07-20.csv

Imports a courier COD remittance CSV and settles matched orders. The import is idempotent, so re-running the same file settles nothing twice.

The command reports settled, duplicates, unmatched, ambiguous, and invalid counts, then prints one warning per problem row with its line number, order number, reference, and reason. Rows that do not match exactly one order are never guessed; reconcile them by hand.

commerce:admin:perf-gate

Ships with the playground, not with a published package: it is the performance gate for the admin read seams, not a host-facing command.

pnpm admin:perf                                    # migrate fresh, seed, gate
node ace commerce:admin:perf-gate --skip-seed      # re-gate an existing dataset

Seeds 100,000 disposable orders (ADMIN-PERF- numbers) with a proportional payment ledger, then times every admin list method against a 250 ms budget and every AdminMetricsService method against 500 ms.

On PostgreSQL the gate is normative and exits with code 1 on a miss. It additionally asserts that every covering index the admin_seams migration ships is present and that each documented filter/sort combination reaches the orders table through an index rather than a sequential scan.

On MySQL and SQLite the rehearsal seed is skipped and the timings are informational — the normative gate is the PostgreSQL CI job.

Related

• Configuration reference
• Deployment and operations
• Troubleshooting