diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..30873a9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,94 @@ +# make-oss-test + +Testing repository for the Make.com GitHub open-source apps workflow. Validates the end-to-end lifecycle: clone from Make → edit locally → validate schemas → deploy back to Make. + +## Tech Stack + +- npm (package manager) +- `@integromat/make-cli` — CLI tool for clone/pull/push/deploy operations against Make.com API +- `@integromat/oss-schema` — JSON schemas for validating IML files +- `ajv` v8 + `ajv-formats` — schema validation engine +- `jsonc-parser` — used by `scripts/validate-app.js` to parse JSONC (JSON with comments) + +## Domain Concepts + +**IML (Integromat Markup Language)** — JSON-based format defining Make app components. All component files use the `.iml.json` extension and are JSONC (allow comments). + +**App manifest** — `makecomapp.json` in each app's `src/` dir. Defines all components (`connection`, `module`, `function`, `rpc`, `webhook`), maps component names to their code files, and declares `origins` (remote Make API endpoints with `baseUrl`, `appId`, `appVersion`, and `idMapping`). Also references `apikeyFile: "../.secrets/apikey"` for local auth (outside repo). + +**Module file types** — Each module has up to 6 files: +- `*.communication.iml.json` — HTTP request/response definition (validated against `api.json` schema) +- `*.mappable-params.iml.json` / `*.params.iml.json` / `*.interface.iml.json` — parameter definitions (`parameters.json` schema) +- `*.samples.iml.json` — sample output data (`samples.json` schema) +- `*.scope.iml.json` — OAuth scopes (no schema match in current mapping) +- `*.static-params.iml.json` — static parameters (`parameters.json` schema) + +**Base config** — `general/base.iml.json` defines app-wide HTTP defaults: `baseUrl`, default `Authorization` header (`{{connection.apiKey}}`), error format, and log sanitization. Validated against `base.json` schema. + +**Module groups** — `modules/groups.json` defines UI grouping of modules. Validated against `groups.json` schema. + +## App Structure + +Apps live under `apps//src/`. Currently one app: `apps/oss-app-test`. The manifest at `apps/oss-app-test/src/makecomapp.json` is the authoritative source for all component definitions and remote origin mappings. + +Connections live in `connections//` with `.communication.iml.json` and `.params.iml.json`. Modules live in `modules//` with their 6 file types. + +## Authentication + +**Local development**: `make-cli` reads API key from `apps//.secrets/apikey` (outside repo, referenced in `makecomapp.json` as `apikeyFile: "../.secrets/apikey"`). + +**CI**: `MAKE_API_TOKEN` and `MAKE_HOST` injected from GitHub Secrets into all workflows that call `make-cli` or `scripts/test-make.sh`. + +Export `MAKE_API_TOKEN=` before running any CLI commands locally. + +## Key Scripts + +**`scripts/validate-app.js`** — takes `` as CLI arg, recursively validates all `.iml.json` files against their schemas from `@integromat/oss-schema`. Schema mapping defined at top of file (14 rules, filename glob → schema name). Resolves schemas: local path first, then `@integromat/oss-schema/dist/json/.json`. Flags: `--allow-warnings` suppresses non-zero exit on warnings. Exit 0 = valid, 1 = errors/warnings. + +**`scripts/detect-changed-apps.sh`** — diffs `HEAD` against PR/push base SHA, extracts `apps/` directories with changes, filters against `WHITELISTED_APPS`. Default whitelist: `apps/oss-app-test` only. Exit 1 if non-whitelisted apps changed. To add new apps to CI, uncomment entries in this script. + +**`scripts/test-make.sh`** — validates API connectivity. Requires `MAKE_HOST` and `MAKE_API_TOKEN`. Makes a single authenticated GET, exits 0 on HTTP 200-399. Run via `npm run test:setup`. Optional `SHOW_BODY=1` prints response body. + +## CI Workflows + +**`validate-schema.yml`** — triggers on PRs touching `apps/**`, `scripts/validate-app.js`, `package.json`, or `package-lock.json`. Runs `detect-changed-apps.sh` then `node scripts/validate-app.js ` for each changed app. Posts PR comment with results. + +**`deploy-app.yml`** — triggers on push to `master` touching `apps/**`. Runs `detect-changed-apps.sh`, deploys each changed whitelisted app via `make-cli deploy --no-prompt`. If `makecomapp.json` changes post-deploy, opens and auto-merges a PR on `chore/make-app-deploy-sync`. + +**`app-sync.yml`** — hourly cron + manual dispatch. Pulls all `apps/*` from Make, opens/auto-merges PR on `chore/make-app-auto-sync` if changes detected. + +**`validate-pr.yml`** — all PRs. Runs `@integromat/actions-toolkit validate-pr` for PR title/label conventions. + +All CI workflows use `NPM_TOKEN` for private npm registry access when installing `@integromat/make-cli`. + +## Local Development Workflow + +``` +# One-time clone +mkdir -p apps/ +npx make-cli clone --local-dir ./apps/ --make-host + +# Sync from Make +npm run pull # prompts for app name + +# Deploy to Make +npm run push # prompts for app name + +# Validate schemas +npm ci +node scripts/validate-app.js apps/oss-app-test +``` + +## Schema Validation Notes + +- `makecomapp.json` uses a local schema path (`./syntaxes/local-development/schemas/makecomapp.schema.json`) that does not exist in the repo — it falls back to the package or skips. +- `*.scope.iml.json` files (the actual extension used) have no matching pattern in `validate-app.js`'s mapping — they are not validated. The mapping only covers `*.scope-list.iml.json`, `*.default-scope.iml.json`, `*.required-scope.iml.json`. +- AJV configured with `allErrors: true, strict: false, allowUnionTypes: true`. + +## Cursor Commands + +Three Cursor IDE commands exist in `.cursor/commands/` — inspect that directory for available AI-assisted workflows. + +## Keeping AGENTS.md current + +When your changes alter anything described in this file — project map, env vars, architectural patterns, API client behavior, error handling, test patterns, or packaging — notify the user that AGENTS.md should be updated and suggest the specific edit. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md