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:setup
node ace commerce:setup
node ace commerce:setup --jsonInspects declared commerce dependencies without booting the application or changing files.
It checks package-specific config/route sentinels, driver environment declarations in
.env, .env.example, or the process environment, and driver registration tokens in
config/commerce.ts. It counts migration sources containing commercekit: and publication
baseline entries, then prints the remaining setup steps. These are source-presence checks,
not proof that migrations ran or credentials work; finish with migrations and doctor.
Exit codes are 0 when ready, 1 when setup is incomplete, and 2 for a missing or invalid
host package.json. --json prints one report instead of the human-readable checklist.
commerce:doctor
node ace commerce:doctor
node ace commerce:doctor --jsonStarts the application and verifies:
- every required Adocommerce Kit table exists under the configured prefix, including
payment_instructions,state_transitions,order_number_counters, andoutbox; - 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_pointcolumn exists oninventory_levels, which the admin list filters and dashboard low-stock panel depend on; - stored inventory reserved totals equal the reservation ledger;
- existing outbound webhook destinations warn when the outbox is disabled;
- older Stripe drivers warn when their exponent-2 assumptions disagree with a configured currency and they lack currency-scaling support; upgrade the driver rather than changing the money ledger to silence the warning.
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 on detected failures; warnings alone do not fail it. --json prints one report containing ok, failures, and warnings. 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:maintenance <task>
node ace commerce:maintenance reservations
node ace commerce:maintenance carts
node ace commerce:maintenance checkouts
node ace commerce:maintenance outbox --jsonRuns one scheduled implementation immediately, with real writes: reservations invokes
ExpireStaleReservations, carts invokes ExpireAbandonedCarts, checkouts invokes
ReconcileStuckCheckouts, and outbox invokes DrainEventOutbox. --json reports
{ affected } for the first three or { sent, failed } for outbox. Failed outbox deliveries
exit with 1; an unknown task exits with 2.
Pending-payment expiry, external-operation reconciliation, and idempotency purging are scheduled jobs, not additional maintenance CLI tasks. See scheduled jobs.
commerce:search:reindex
node ace commerce:search:reindex
node ace commerce:search:reindex --batch-size=250 --jsonRebuilds the configured product search index through SearchService.reindex().
--batch-size defaults to 250; --json prints an ok report with the indexed count.
Run after configuring or replacing a search driver.
commerce:seed:demo
node ace commerce:seed:demoCreates a deterministic Field Supply sample store in the current database:
webandretailchannels;- 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:demoPlayground-only follow-on for the Indonesian Field Supply demo. Requires commerce:seed:demo first. It:
- switches the
webchannel default currency to IDR and stamps hostbrandvalues; - 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
completedcart 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 productPublishes a host subclass in app/models/commerce and adds its lazy loader to config/commerce.ts.
Supported registry keys:
channel product productImage productOption productOptionValue productVariant
category priceList price customerGroup customer address cart cartLine cartAdjustment
shippingMethod taxZone taxRate taxCategory order orderLine paymentIntent payment
paymentInstruction shipment stockLocation inventoryItem inventoryLevel reservation
inventoryMovement inventoryTransfer orderAdjustment shipmentLine refund capture
paymentCustomer paymentMethod webhookEvent paymentOperation idempotencyKey eventOutbox
webhookDestination webhookDelivery mediaAsset returnReason returnRequest returnLineAdd host columns with a new host migration. Do not change the inherited Adocommerce Kit table name or registry key. See Extend a model.
commerce:make:driver <kind> <name>
node ace commerce:make:driver shipping warehouse-rateAll 14 kinds are payment, shipping, tax, inventory, fulfillment, shipping-quote, cart-token, pricing, search, image-storage, shipping-eligibility, tax-address, order-number, and job-dispatcher. Files are published under app/services/commerce/drivers; registration instructions are printed, not silently inserted.
The first four kinds delegate to built-in behavior (payment uses the manual provider). The additional typed adapter factories require an explicit working existingDriver delegate; they are not independently functioning integrations. Register a job dispatcher with JobDispatcherService.use() in a host provider’s boot hook after commerce, not as a new config/commerce.ts dispatcher string. See driver authoring.
commerce:upgrade
node ace commerce:upgrade
node ace commerce:upgrade --yes
node ace commerce:upgrade --check
node ace commerce:upgrade --jsonCompares installed publication baselines, host files, package sources, and migration markers.
| Classification | Meaning |
|---|---|
add |
Missing new publication in a package already owned through a recorded baseline. |
update |
Host matches its base; incoming stock can replace it safely. |
noop |
Host and incoming stock are equivalent; apply heals its baseline. |
conflict |
Both host and incoming diverged from the base; stage incoming and merge instructions. |
kept |
Host is customized but incoming stock still matches the base; retain host changes. |
removed-by-host |
A recorded host publication was deleted; preserve the deletion. |
unconfigured |
No recorded ownership baseline; skip rather than publishing merely because the package is installed. |
error |
Artifact inspection or loading failed; report the cause without writing it. |
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.
Comparisons ignore a leading BOM, CRLF differences, and trailing newlines only. Optional loaders cover storefront/admin surfaces, Indonesia, promotions, preorders, store credit, engagement, WhatsApp, and Biteship. Missing core migrations come from the exported ordered coreMigrations registry. Advisory IDs and summaries are printed and advisory/error metadata is included in JSON; an advisory on an unmerged conflict (or a pending update under --check) causes a nonzero check status, while an advisory on a kept copy is reported only. --check and --json inspect without writing. Apply mode heals noop baselines even though no host-file update is needed. Combining --check with --yes exits with 2.
commerce:id:regions-import
node ace commerce:id:regions-import --file=storage/regions/kemendagri-2025-01.jsonImports 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:
| Provenance field | Requirement |
|---|---|
source |
Human-readable source name |
sourceUrl |
Must use HTTPS |
version |
Source-assigned version |
retrievedAt |
Retrieval date |
license |
License name |
licenseUrl |
Must use HTTPS |
expectedChecksum |
SHA-256 hex digest of the region payload |
corrections |
Optional list of host-applied corrections |
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.csvExports 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.csvImports 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 datasetSeeds 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.