@antscorp/create-zma-loyalty

Public CLI package for transactionally creating and maintaining brand-neutral Zalo Mini App loyalty projects.

Create

Interactive terminal:

npx @antscorp/create-zma-loyalty@latest

The installed binary remains create-zma-loyalty.

The wizard asks for a setup mode and an explicit project folder name. The recommended Antsomi starter requires the brand key, OA ID, and App ID, then suggests at.zma.<brand-key> as an editable folder name while supplying replace-later public materials and placeholders for remaining platform values. The folder basename is also written as package.json#name; custom setup keeps the full field-by-field workflow.

After creation, human output shows the absolute project path, exact local run commands, and a short reminder to replace replace-with-* values through the supported configuration workflow. JSON mode keeps the same commands in data.nextSteps without terminal formatting.

Non-interactive starter mode:

create-zma-loyalty at.zma.pho24 \
  --preset antsomi \
  --brand-key pho24 \
  --oa-id your-public-oa-id \
  --app-id your-public-app-id \
  --yes --no-install --no-git

Deterministic config-file mode:

create-zma-loyalty at.zma.pho24 \
  --config ./project.yaml \
  --yes \
  --no-install \
  --no-git \
  --json

The target must be an absent conservative npm-safe relative path. Its final folder segment becomes the generated npm package name, so apps/at.zma.pho24 produces package at.zma.pho24. Brand identity remains an independent configuration value. There is no force mode. Work is performed in a validated sibling staging directory. After generation, optional install, and optional Git initialization succeed, the CLI atomically reserves the target name and copies with fail-on-exist semantics while rechecking directory identities. Portable Node APIs cannot provide an atomic no-replace directory rename, so publication is cross-platform no-replace safe but does not provide all-at-once visibility; it never replaces a concurrently created target. Git initialization creates no commit or remote.

Configure

cd at.zma.pho24
create-zma-loyalty configure --sync-only --dry-run --json
create-zma-loyalty configure --config ../project.yaml

JSON/YAML input is validated by the same strict version 1 schema. Assets are validated and copied to canonical project destinations. Generated config, schema, TypeScript, CSS, app config, and .zma-template.json share a canonical SHA-256 config fingerprint. Configure leaves all non-declared human-owned files unchanged; dry-run writes nothing. Apply preflights and stages the entire owned file set, rolls every prior byte and mtime back on failure, and commits .zma-template.json last.

Doctor and upgrade

create-zma-loyalty doctor --json
create-zma-loyalty upgrade --dry-run --json
create-zma-loyalty upgrade --yes --json

Doctor is read-only and reports healthy or upgrade-available with the exact migration IDs. Upgrade validates the same project state, requires --yes for non-interactive apply, checks per-file SHA-256 preconditions, commits metadata last, and is idempotent. Migration manifest v1 can only replace existing files; there is no force mode, target-version selection, create, delete, or rename.

--json emits exactly one PASS/FAIL JSON value. Exit codes are 0 success, 1 validation/operation/cancellation, 2 usage, and 3 MIGRATION_CONFLICT with path-only diagnostics.

The embedded template includes a runnable React/Vite/ZMP shell with fixed non-sticky chrome, responsive semantic tokens, React Router, TanStack Query, reduced-motion defaults, injectable Zalo/API boundaries, mock-first data, and a narrow non-persistent Zustand notice store. Generated source is project-owned; only declared config, assets, metadata, and src/generated/** remain owned by the CLI. The runtime includes strict reward/voucher schemas, catalogue-backed detail, confirmation-first redeem, cursor voucher wallet, safe image fallback, URL-owned tabs/dialogs, and scroll-top pull-to-refresh without a live backend. It also includes URL-owned cursor activity history below the member QR, one strict content catalogue, safe structured news/legal rendering, public content routes, HTTP(S)-only external CTA through the platform adapter, and mock API plus platform defaults for credential-free browser development.