#375 Add list/search as a factory method that produces many data artifacts (Drive files.list, gmail messages.list, etc.)

Problem

Auto-generated @swamp/gcp/* extensions only emit per-resource verbs (create, get, update, delete, sync). Collection-level operations from the Discovery API — files.list, messages.list, events.list, spreadsheets.search, etc. — are not surfaced as methods, even though they're the primary discovery path for almost every Workspace API.

Without a list method, you can only address Drive content if you already know its fileId. To find a fileId you have to leave swamp entirely (e.g. gws drive files list), feed the result back into the model, and lose all the affordances that swamp normally provides (data caching, version history, CEL wiring, fan-out).

The README itself documents this gap implicitly: "files.update requires a fileId. Use the files.list method to retrieve the ID for a file" — but files.list doesn't exist as a method.

Proposed Shape

A factory method per collection-supporting Discovery operation, producing many data artifacts in a single call. This matches the project's fan-out pattern ("Prefer fan-out methods over loops") and mirrors how AWS and other infrastructure extensions handle indexed resources.

For @swamp/gcp/drive/files:

swamp model method run my-drive list \\
  --input q='"FOLDER_ID" in parents and trashed=false' \\
  --input fields='files(id,name,mimeType,modifiedTime),nextPageToken' \\
  --input pageSize=1000

Behaviour:

• Pages through drive.files.list until exhaustion (or a configurable cap).
• Produces one state data artifact per file, named by the file's id or name (configurable, with collision handling).
• Sets lifetime/gc so the produced artifacts behave like ephemeral query results, not long-lived tracked resources.
• Caller can then refer to any matched file via standard CEL like data.latest('my-drive', '<name>').attributes.modifiedTime in workflows.

Why a Factory, Not a New Model Type

A separate @swamp/gcp/drive/files-list model type would force users to maintain two unrelated definitions for the same resource and would not let list and get share state. A single files model with both an "identifier-driven" lane (current get) and a "factory" lane (proposed list) keeps the abstraction clean and lets workflows fan out from a search to per-file methods on the same model.

Implications for the Generator

_lib/gcp.ts already has a readViaList() helper that paginates and filters — a natural building block. The generator would need to:

1. Detect Discovery operations of the form <collection>.list (well-known shape: returns { items|files|messages|...: [...], nextPageToken: string }).
2. Emit a new method per detected list operation, with the operation's parameters mapped onto method inputs.
3. Use the resource's identifier field (typically id) as the data-artifact name.
4. Apply a sensible default fields projection that includes at least the identifier and the fields the model schema declares as required.

This pattern repeats across most Google APIs (and probably AWS/Azure equivalents): Gmail messages.list, Calendar events.list, Sheets spreadsheets.search, Admin SDK users.list, Cloud Resource Manager projects.list, etc. A fix in the generator improves the entire @swamp/gcp/* family at once.

Workaround Today

Users have to:

1. Leave swamp to enumerate (gws, gcloud, raw API call, ...).
2. Pipe the IDs back in, one swamp model method run my-drive get --input identifier=<id> per file.
3. Pay the per-call lock contention (the project rules explicitly call this out as a footgun: "Multiple parallel calls against the same model contend on the per-model lock").

This makes the extension awkward for any real Drive task.

Related

• Bug #373 (ADC token misuse) — also affects the proposed list method.
• Bug #374 (sparse fields projection) — an explicit fields input on list would be a natural place to fix the projection problem at the same time.

Environment

• swamp 20260516.045246.0-sha.e6eda98d
• @swamp/gcp/drive 2026.05.18.2 (latest)

Upstream repository: https://github.com/systeminit/swamp-extensions

Environment

• Extension: @swamp/gcp/[email protected]
• swamp: 20260516.045246.0-sha.e6eda98d
• OS: darwin (aarch64)
• Deno: 2.7.14+19bd3d8
• Shell: /bin/zsh