George Lambert
b4150c8250
Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
36 lines
2.3 KiB
Markdown
36 lines
2.3 KiB
Markdown
# `zapier-platform-cli` Architecture
|
|
|
|
## Purpose
|
|
|
|
- This package, released as `zapier-platform-cli` publicly on [npm](https://www.npmjs.com/package/zapier-platform-cli), powers the Zapier CLI (invoked via the `zapier-platform` command).
|
|
- Developers install and use this tool to complete operations required to develop an integration on the Zapier platform.
|
|
- The `core`, `schema`, and `cli` packages are always released together under matching version numbers.
|
|
|
|
## Technical Organization
|
|
|
|
> `cli/...`, when used in a path to a file, is shorthand for `zapier-platform/packages/cli/...`
|
|
|
|
### Commands
|
|
|
|
- We use the [oclif](https://github.com/oclif/oclif) (created for the Heroku CLI) to power our CLI
|
|
- Each command (`zapier-platform push`, `zapier-platform test`, etc) gets its own file in the `cli/src/oclif/commands` directory.
|
|
- Some sub-commands live in sub-directories, such as `zapier-platform env:get` (which is found in `cli/src/oclif/commands/env/get.js`).
|
|
- All commands inherit from `ZapierBaseCommand`, which provides convenient methods for parsing flags, printing structured data, and verifying authentication
|
|
- Command code should be responsible for all user-facing behavior, including:
|
|
- loading indicators
|
|
- printing data
|
|
- supplying and parsing args/flags
|
|
- throwing descriptive error messages
|
|
- Core functionality should mostly live in the `utils` folder (though we hope to organize it better eventually); see next section
|
|
|
|
### Everything Else
|
|
|
|
- All other functionality (especially as it relates to calling APIs) lives in the `cli/src/utils` folder); It's a bit of a kitchen sink
|
|
- The most important file is probably `cli/src/utils/api.js`, which controls authentication and API calls against the Zapier monolith
|
|
- The next most important file is probably `cli/src/utils/display.js`, which powers the loading spinner and printing tables. In a command you typically won't use these directly (prefer methods on `ZapierBaseCommand`).
|
|
- While commands should be user-facing functionality, "business logic" should prefer to live in this folder. It may get a new name at some point
|
|
|
|
### Tests
|
|
|
|
- Most functions in `cli/src/utils` have unit test coverage (`cli/src/tests/utils`).
|
|
- There are also "smoke tests", which simulate the full flow of the user journey (install, create an app, scaffold a trigger, run the tests), found in `cli/src/smoke-tests`
|