Architecture

One shared automation engine. Many form configs. A new Google Form is a new YAML file — not a new code path.

Packages

packages/core/src/     @zamdevio/gform-core — config, engine, paths, content, artifacts
packages/cli/src/      Commander commands + edit/--ask UI
dist/cli.js            published bin (tsup from root)
docs/                  canonical user docs (synced into apps/docs)
apps/docs/             VitePress site → thegform.pages.dev
maintainer/            contributor systems / phases (not published)
forms/_template.yaml   starter shipped with root package files[]
profiles/              unused stub — not runtime

Surface	Package
CLI bin gform	root package gform
Engine SDK	@zamdevio/gform-core
Re-export	gform/core from the root package

import { loadFormConfig, runFormBatch } from "@zamdevio/gform-core";
// or
import { loadFormConfig, runFormBatch } from "gform/core";

Runtime Node adapters publish via @zamdevio/gform-core’s documented runtime entry points as the purity refactor lands — hosts supply adapters; core does not silently default-resolve Node for new code paths.

Data flow

$GFORM_HOME/forms/<form>.yaml  (or optional ./forms/)
      │
      ▼
@zamdevio/gform-core load  ──zod──► FormConfig
      │
      ▼
runner (+ inspect preflight)
      │
      ├─ browser.launch (+ storageState only if CLI --auth)
      ├─ page.goto(url)
      └─ for step in steps: runStep(page, step)
            │
            ▼
      artifacts/<16-hex>/  + history.jsonl

Why Playwright (not raw POST)

Google Forms UI is multi-page JS. A /formResponse POST needs hidden entry.* IDs and page history that break when the owner edits the form. Playwright follows visible controls — slower to run, easier to maintain when the form changes.

Design rules

1. Core knows actions, not business answers
2. Form YAML owns URL + ordered answers
3. Auth is optional and CLI-opt-in (--auth)
4. CLI stays thin; logic lives in @zamdevio/gform-core
5. Interactive --ask UI lives in packages/cli
6. Soft walls → human assist; hard walls → reason + artifacts
7. No CAPTCHA bypass

Contributor maps and phases live in the repository under maintainer/ (not published). See also CONTRIBUTING.md.