google-forms

# Google Forms ## Purpose Manage Google Forms through `hatch_gws_cli`; the vendored Google Workspace CLI is the only implementation path. ## Tooling Use `exec` to run: ```sh hatch_gws_cli forms <resource> <method> [flags] ``` ### Connection management ```sh hatch_gws_cli forms status hatch_gws_cli forms disconnect ``` ### Forms operations Core patterns: - `hatch_gws_cli forms status` - `hatch_gws_cli forms disconnect` - `hatch_gws_cli schema forms.forms.get` - `hatch_gws_cli schema forms.forms.create` - `hatch_gws_cli schema forms.forms.batchUpdate` - `hatch_gws_cli schema forms.forms.responses.list` - `hatch_gws_cli schema forms.forms.responses.get` Common raw API calls: - `hatch_gws_cli forms forms get --params '{"formId":"<form_id>"}'` - `hatch_gws_cli forms forms create --json '{"info":{"title":"Feedback Survey","documentTitle":"Feedback Survey"}}'` - `hatch_gws_cli forms forms batchUpdate --params '{"formId":"<form_id>"}' --json '{"requests":[{"updateFormInfo":{"info":{"description":"Quarterly survey"},"updateMask":"description"}}]}'` - `hatch_gws_cli forms forms responses list --params '{"formId":"<form_id>","pageSize":20}'` - `hatch_gws_cli forms forms responses get --params '{"formId":"<form_id>","responseId":"<response_id>"}'` JSON output contract: - `status`: parse `status`, `connect_url`, and `disconnect_url` - `disconnect`: parse `ok`, `action`, `status`, and `disconnect_url` ## Auth Authentication is handled by the wrapper's `status` and `disconnect` subcommands. Do not hand-write credential files or run raw `gws auth ...`. ## First-use setup flow 1. Run `hatch_gws_cli forms status`. 2. If `status` is `unavailable`, tell the user that Google Forms is not available on this device. Do not offer alternative integration approaches or ask the user for credentials. 3. If `status` is `not_connected` and `connect_url` is present, replace `<connect_url>` with the returned URL and share exactly this Markdown link: `[Connect Google Forms](<connect_url>)`; do not paste the raw URL separately. Wait for the user to reconnect. 4. Once `status` is `connected`, proceed with Forms operations. ## Operating Rules 1. Use `schema` before unfamiliar Forms methods so `--params` and `--json` match the current vendored CLI contract. 2. Creating a form and editing an unpublished form owned only by the user may proceed from a clear request. Confirm before editing a shared or published form, or publishing one, because its contents can reach other people. 3. Run `forms.get` before presenting response data so you can map question IDs to human-readable form structure. 4. Treat form IDs and response IDs as opaque strings and only use IDs returned by prior commands or explicit user input. 5. Run `hatch_gws_cli forms disconnect`. After running it, when `disconnect_url` is present, replace `<disconnect_url>` with the returned URL and share exactly this Markdown link: `[Disconnect Google Forms](<disconnect_url>)`; do not paste the raw URL separately. 6. Paginate through responses when the user asks for all responses; stop when `nextPageToken` is absent. 7. After a read or write action, confirm the user-visible result only. Do not surface raw API identifiers (form, response, and question IDs) or other internal response fields (page tokens/cursors, raw JSON) in text shown to the user unless the user asks for them or you need them to troubleshoot a failure; keep using them internally to chain follow-up commands. 8. Response reads retain Google's raw timestamps and add semantic UTC and user-local forms for response creation/submission times.