Milestone 0: import zappier billing, Verae middleware, and Zapier research

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.
This commit is contained in:
George Lambert 2026-09-09 02:37:36 -04:00
commit b4150c8250
1364 changed files with 6814366 additions and 0 deletions

View file

@ -0,0 +1,18 @@
# Development Quick Reference
This directory provides quick reference information for both human developers and AI tools working on the Zapier Platform codebase.
## Documentation Map
### Existing Documentation (main repository docs)
- **[README.md](../README.md)** - Repository overview and all documentation links
- **[ARCHITECTURE.md](../ARCHITECTURE.md)** - Repository structure and technical organization
- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Setup, testing, development workflow, and pnpm linking
### Quick Reference (this directory)
- **[install-dev.md](install-dev.md)** - Development CLI setup and aliases
- **[commands.md](commands.md)** - Command cheat sheet organized by task
- **[package-info.md](package-info.md)** - Package purposes and key relationships
## For AI Tools
AI tools should reference both the existing documentation and these quick reference files to avoid duplicating information while getting task-oriented summaries.

View file

@ -0,0 +1,97 @@
# Command Quick Reference
## Root-Level Commands (run from repository root)
### Installation & Setup
```bash
pnpm install # Install all dependencies
```
### Testing
```bash
pnpm test # Run all tests (all packages + schema-to-ts)
pnpm smoke-test # Run smoke tests (cli, core, schema only)
pnpm validate # Full validation (test + smoke-test + lint)
```
### Code Quality
```bash
pnpm lint # Lint all packages
pnpm lint:fix # Fix linting issues
```
### Build & Release
```bash
pnpm generate-types # Generate TypeScript declarations
pnpm bump # Bump versions across packages
```
## Package-Specific Commands (cd into package first)
### CLI (`packages/cli/`)
```bash
pnpm test # Unit tests
pnpm smoke-test # Smoke tests
pnpm validate # test + smoke-test + lint
```
### Core (`packages/core/`)
```bash
pnpm main-tests # Unit tests only
pnpm type-tests # TypeScript definition tests
pnpm test # main-tests + solo test + type-tests
pnpm integration-test # Integration tests
pnpm smoke-test # Smoke tests
pnpm validate # Full validation
```
### Schema (`packages/schema/`)
```bash
pnpm test # Unit tests
pnpm smoke-test # Smoke tests
pnpm validate # test + smoke-test + lint
```
### Schema-to-ts (`schema-to-ts/`)
```bash
pnpm test # Uses vitest (not mocha)
```
## Development Workflow Tips
- **Individual package testing**: Always `cd` into package directory first
- **Full validation**: Use `pnpm validate` at root for comprehensive checking
- **Focused testing**: Use `.only` in Mocha for specific test cases
- **TypeScript types**: Generated automatically via husky precommit hooks
## Package Linking for Integration Development
When developing integrations, you may want to link to your local development versions of core and schema instead of the published npm packages.
### Setup Links
```bash
# Register the packages for linking
cd packages/core && pnpm link
cd packages/schema && pnpm link
```
### Use in Integration Project
```bash
# In your integration project directory
pnpm link zapier-platform-core
pnpm link zapier-platform-schema
```
### Verify Linking
```bash
# Check that packages are symlinked
ls -hl node_modules/zapier-platform-*
# Should show: node_modules/zapier-platform-core -> .../pnpm/global/5/node_modules/zapier-platform-core
```
### Unlink
```bash
# Return to npm packages
pnpm unlink zapier-platform-core
pnpm unlink zapier-platform-schema
```

View file

@ -0,0 +1,56 @@
# Installing Development Version of Zapier Platform CLI
## Prerequisites
Before installing the development version of the Zapier Platform CLI, ensure you have:
- Node.js (refer to `.tool-versions` for the recommended version)
- pnpm
- Git
We recommend using `asdf` to manage Node.js and pnpm versions consistently.
To try out the latest development version of the Zapier Platform CLI tool, you can pull the source code from GitHub and run it directly. Follow the instructions below.
## First Time Setup
Clone the zapier-platform repo and install the dependencies:
```
cd ~/projects # or wherever you want to clone the repo
git clone git@github.com/zapier/zapier-platform.git
cd zapier-platform
pnpm install
```
Then add this line to your shell configuration file, such as `~/.bashrc` or `~/.zshrc`:
```
# Replace `/absolute/path/to/zapier-platform` with the actual path where you cloned the repository.
alias zapier-dev="node /absolute/path/to/zapier-platform/packages/cli/src/bin/run"
```
Restart your shell with `exec $SHELL` and `zapier-dev` should be available. Test it out by running `zapier-dev` in your terminal. You should see output similar to:
```
$ zapier-dev
The CLI for managing integrations in Zapier Developer Platform.
VERSION
zapier-platform-cli/15.16.0 darwin-arm64 node-v21.7.1
USAGE
$ zapier [COMMAND]
```
## Updating the CLI
To update, pull from the main branch or any feature branch, and update the dependencies:
```
cd ~/projects/zapier-platform
git fetch origin main # or a feature branch
git pull origin main # or a feature branch
pnpm install
```

View file

@ -0,0 +1,49 @@
# Package Information
## Core Packages
### zapier-platform-cli (`packages/cli/`)
**Purpose**: Developer-facing CLI tool
**Key Commands**: `push`, `promote`, `test`, `validate`, `init`
**Dependencies**: Uses core and schema packages
**Testing**: Mocha with smoke tests
### zapier-platform-core (`packages/core/`)
**Purpose**: Runtime functionality for all Zapier apps
**Key Features**: HTTP middlewares, request handling, app execution
**Dependencies**: Depends on schema for validation
**Testing**: Unit tests + type tests + integration tests
**TypeScript**: Includes generated type definitions
### zapier-platform-schema (`packages/schema/`)
**Purpose**: Source of truth for app structure validation
**Key Output**: `exported-schema.json` used by other packages
**Dependencies**: Standalone, depended on by others
**Testing**: Functional constraints and schema validation
### zapier-platform-legacy-scripting-runner (`packages/legacy-scripting-runner/`)
**Purpose**: Backward compatibility for Legacy Web Builder apps
**Key Function**: Provides shim layer for legacy apps
**Dependencies**: Minimal, focused compatibility layer
## Supporting Tools
### schema-to-ts (`schema-to-ts/`)
**Purpose**: Generate TypeScript declarations for core package
**Input**: `exported-schema.json` from schema package
**Output**: Type definitions bundled into core package
**Build Process**: Runs via `generate-types` script and husky hooks
**Testing**: Uses vitest instead of mocha
## Key Relationships
1. **Schema → Core**: Schema validates app structure, core provides runtime
2. **Core → CLI**: CLI orchestrates core functionality
3. **Schema → schema-to-ts → Core**: Types flow from schema through generator to core
4. **All → Legacy Runner**: Provides compatibility bridge
## Monorepo Structure
- **Root**: Tooling, configuration, examples, documentation
- **packages/**: Main platform packages
- **example-apps/**: Sample integrations
- **boilerplate/**: Minimal app template for Visual Builder