Capture
@puddleworks/capturev2026.10.27.5
01README
Capture turns what someone asks for into an agreed outcome spec. A request is raised as a draft, discussed by its outcome owner and builders, given a specification, agreed, and exported as outcome-spec/v1 JSON or Markdown. Everything is kept in swamp data.
Models
@puddleworks/capture/requests: the people list and every request, with a method for each step: create_request (safe to retry with an idempotency key), submit, invite, join_request, post_message, edit_specification, propose, agree, export_outcome_spec and more. Each request has a number (#1, #2, …) that methods take in place of its id. Each change says who is acting withas, and Capture's rules decide what they may do.@puddleworks/capture/web: a read-only page on 127.0.0.1 showing every request and the people list, reloaded as the data changes.
Workflows
@puddleworks/capture-log-request: log a request as a draft from another tool, such as puddlerouter, keyed on where it came from.
02Behaviors
@puddleworks/capture/requestsv2026.10.27.5capture.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| appUrl? | url | Where the request pages are served, with no trailing slash. Exported outcome specs link to <appUrl>/requests/<id>. |
| defaultAs? | Who acts when a method's `as` is left out, such as the account a workflow logs requests for. |
fn add_person(email: email, name: string)
Add someone to the people list, so they can act and be invited.
| Argument | Type | Description |
|---|---|---|
| Their email; it is who they are in Capture. | ||
| name | string | Their name, as others will see it. |
fn update_person(email: email, name?: string)
Change someone's name or whether they build. Requests keep the name they joined with.
| Argument | Type | Description |
|---|---|---|
| Their email. | ||
| name? | string | Their new name. |
fn create_request(title: string, description: string, currentProcess?: string, idempotencyKey?: string)
Log a request as a draft owned by the person acting. Pass idempotencyKey so a retry gives back the same request.
| Argument | Type | Description |
|---|---|---|
| title | string | A short name for the request. |
| description | string | What is wanted, in the requester's words. |
| currentProcess? | string | How it is done today, if at all. |
| idempotencyKey? | string | The same key from the same person always gives the same request, so a retry never makes a second one. |
fn get_request()
Read one request as the person acting sees it.
fn list_requests(scope?: enum, status?: enum, max?: coerce.number)
List the requests the person acting is on, or, for a builder, the open ones they could join.
| Argument | Type | Description |
|---|---|---|
| scope? | enum | mine: requests the person is on. available: open requests a builder could join. |
| status? | enum | Only requests in this state. |
| max? | coerce.number | Stop after this many requests. |
fn export_outcome_spec()
Export an agreed request as outcome-spec/v1 (or Markdown). The request moves to Exported.
fn import(path: string)
Bring in a capture-snapshot/v1 file, as Capture's old Node app exported. Adds only what isn't here yet, so it is safe to run again.
| Argument | Type | Description |
|---|---|---|
| path | string | The snapshot file, relative to the repository. |
Resources
request(infinite)— One request and everything on it, with the version count and what was kept from before Capture.
person(infinite)— Someone in the people list: who they are and whether they build.
view(infinite)— One request as the person who asked sees it, with what they may do now.
requestList(infinite)— The requests in one scope and status, as the person who asked sees them.
outcomeSpec(infinite)— An exported outcome-spec/v1 document.
outcomeSpecMarkdown(infinite)— An exported outcome spec as Markdown.
importResult(infinite)— What the last import brought in and what it found already here.
@puddleworks/capture/webv2026.10.27.5capture_web.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| requests? | string | The name of the @puddleworks/capture/requests behavior to show. |
fn serve(port?: coerce.number)
Serve the Capture page on 127.0.0.1 until Ctrl-C: every request, read-only, reloaded as it changes
| Argument | Type | Description |
|---|---|---|
| port? | coerce.number | The port on 127.0.0.1; 0, the default, picks a free one |
03Workflows
@puddleworks/capture-log-requestaebff000-c16d-48bd-8f01-08d64fec1596
Log a request in Capture as a draft. sourceRef is the idempotency key, so logging the same thing twice gives one request. Needs a @puddleworks/capture/requests behavior named capture, with defaultAs set to the person the requests are logged for.
main
1.create-requestcapture.create_request
04Previous Versions
2026.10.27.4MIT
2026.10.27.3MIT(was none)
2026.10.27.2yanked
2026.10.27.1yanked
05Stats
A
100 / 100
Downloads
0
Archive size
74.5 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
06Platforms
07Labels