@primitivedotdev/map 0.0.0-stage → 0.2.0

package/CONFORMANCE.md

@@ -0,0 +1,116 @@
+# map transport conformance
+
+map is plain email. The `map` CLI does all its mail
+through one small interface, `Transport` (`packages/map-public/src/transport.ts`), so
+map can run on any mail provider that has an adapter for it. This suite is how
+an adapter shows that it carries map: it checks the interface rules on the
+adapter directly, then runs the real `map` commands (get, send, update, wait,
+approve, object, argue, history) end to end against a map repo, through the
+adapter. Files and mail only: no git.
+
+It is meant to be clear and honest, not exhaustive. A pass means these checks
+passed on that date with those two mailboxes; it is not a load test or a
+security audit.
+
+## The interface
+
+An adapter is an ES module whose default export returns a `Transport`:
+
+| Method | Rule |
+| --- | --- |
+| `send({ from, fromName?, to, subject, body, attachments? })` | Sends a new message (not a reply) and returns a non-empty id, different for each send, that `waitReply` accepts. Attachments are file paths; each arrives under its file name, byte for byte. `fromName`, when given, is the From display name. |
+| `waitReply(sentId, { me, from, timeoutSec, since? })` | The earliest reply to that sent message, from `from` to `me`, received at or after `since`. Each call returns one reply; callers step past it with `since`. Replies that arrived before the call count. A timeout returns `null`; it is not an error. |
+| `get(id)` | The message: subject, sender, recipient, received time, plain text body, attachments (file name and part index), and when the provider has them `message_id`, `in_reply_to`, `references` and `from_header`. |
+| `download(id, part, out)` | Saves one attachment to `out` and returns its bytes. |
+| `reply(id, { from, body })` | Replies on the thread of an inbound message, so its In-Reply-To and References name that message. |
+| `list({ me, after?, limit?, cursor? })` | Inbound mail to `me` only, newest first, a page at a time. |
+| `tail({ me, cursor?, from?, limit?, wait? })` | New inbound mail to `me` only, oldest first, after a cursor (or a time on the first call); returns the next cursor. `wait` may long-poll. |
+| `search({ me, q?, from?, to?, subject?, body?, threadId?, sort?, limit?, cursor? })` | Mail that matches, newest first by default, and when it can, the provider command that ran it (map prints it so people learn the mailbox is the record). map's history commands are built on it. |
+| `defaultAddress()` | The address this login sends from when it has exactly one, else `null`. |
+| `describe()` (optional) | Provider name and version, for the report. |
+
+Pick an adapter with `MAP_TRANSPORT`: a built in name (`primitive`) or the
+path of the module.
+
+## The checks
+
+Run in this order. Later checks are skipped when one they build on failed.
+
+| # | Check | How |
+| --- | --- | --- |
+| 1.1 | send returns a stable id | A sends B two mails: two distinct ids, both delivered. |
+| 1.2 | an attachment round-trips | A sends B 4096 random bytes (with NUL, 0xff and CRLF) as `conformance-blob.bin`; B reads the same name and bytes. |
+| 1.3 | waitReply returns each reply once, in order | B replies twice to a mail from A before A waits; A's waits return reply one, then reply two, then time out. |
+| 1.4 | a reply threads | The reply's In-Reply-To and References name the Message-ID of the mail it answers. |
+| 1.5 | the inbox is mine only | `list` and `tail` for A, and `list` for B, hold only mail to that address. |
+| 1.6 | a timeout is a timeout | A 5 s `waitReply` with no reply returns `null` and does not throw. |
+| 1.7 | search | A mails B a unique word; a search of B's mail for the word, and one by subject, return it, and nothing addressed elsewhere. |
+| 2.0 | create a repo by email | B mails `new@<host>` with `Map-Create`, `Map-Handle` and `Map-Allow: <A>`; B owns the new repo. |
+| 2.1 | get, edit, send | A runs `map get <repo> a`, edits, `map send`: landed. `map update` then leaves `map diff` empty. |
+| 2.2 | conflict, update, send | B gets a copy, A lands an edit to line one, B sends its own edit of line one: conflict naming the file. B's `map update` writes conflict markers; B resolves and sends: landed. |
+| 2.3 | binary and rename | A adds a PNG and renames a file and sends; a fresh `map get` matches A's folder byte for byte. |
+| 2.4a | consent on | B sends `map settings <repo> "Map-Consent: owners" "Map-Consent-Window: 5"`. |
+| 2.4 | consent ask, approve | B changes a line A wrote. A gets `[map consent <pid>]`; `map approve <pid>` lands B's change. |
+| 2.5 | objection and argument | B changes another of A's lines; A runs `map object`; B's `map send` reports A's objection; B runs `map argue`; A gets the round 2 ask for that same push, quoting B's argument; A approves and B's `map wait` returns LANDED. |
+| 2.6 | history is mail | `map history` finds the objection in B's mail; `map log` lists the commits (from commit mail in this account, or from the repo's answer to a `Map-Log` mail). |
+| 3.1 | forged display name | A sends the repo a settings line with From `"<B>" <A>` (B owns the repo). The repo must not apply it. |
+
+B owns the repo and A only contributes because map never asks a repo owner for
+consent as a line owner.
+
+## Running it
+
+You need Node 22 or newer and two mailboxes (A and B) that the adapter can
+send from and read, both able to get mail from the repo host.
+
+```sh
+npm install -g @primitivedotdev/map          # map-conformance comes with it
+map-conformance transport --adapter ./my-adapter.mjs \
+  --a alice@example.org --b bob@example.org \
+  [--repo-host map.dev] [--json] [--out report.md]
+```
+
+`--adapter primitive` uses the built in Primitive adapter. The run takes
+about 5 to 10 minutes, mostly map's review of each push. It prints each check
+as it goes, then a Markdown report (JSON with `--json`). Exit status is 0
+only when every check passed.
+
+The run creates its own repo by email from B, so it needs nothing from the
+repo host's operators. The host allows 5 new repos per address and 20 per
+domain in any 24 hours. If B cannot create one, pass `--repo <address>` for a
+repo that B owns and A may send to; it should be fresh, since the checks edit
+`notes.txt`, `docs/` and `assets/`. A new address gets a handle on its first
+repo (`--handle` picks it; an address that has one keeps it).
+
+## What these checks cannot tell you
+
+- 3.1 shows what the repo did with the mail the adapter sent. Whether a
+  forged display name is caught depends on the repo host checking the From
+  address and the provider's DKIM or DMARC results, not on the adapter alone.
+- Search covers inbound mail only (on Primitive, `primitive emails search`).
+  It cannot see mail you sent: your changes, arguments and replies, unless
+  the repo copied them back to you. The repo's own mail (its commit log,
+  reviews, verdicts to others) is inbound only for the account that hosts
+  the repo; everyone else sees what map sent them, and `map log` asks the
+  repo by mail (`Map-Log`) when the mailbox holds no commit mail.
+- 1.4 needs the adapter to report Message-ID and In-Reply-To. An adapter that
+  cannot will fail it, even if its replies do thread.
+- Times in the report include map's review and the provider's delivery; they
+  are not a benchmark.
+
+## Adding a provider
+
+A pull request for a new provider must include:
+
+1. The adapter under `packages/transports/<provider>/`, as its own module
+   whose default export returns a `Transport`. It may import only the types
+   from `packages/map-public/src/transport.ts`.
+2. A `README.md` there that says how to log in, what the two mailboxes need
+   (accounts, domains, DNS) and any limits.
+3. The report of a passing run, committed as
+   `packages/map-public/conformance/<provider>.md`.
+4. No provider code anywhere else: no changes to the CLI, the engine or other
+   adapters.
+
+`packages/transports/primitive/` is the reference, and
+[`conformance/primitive.md`](conformance/primitive.md) is its report.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Primitive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @primitivedotdev/map
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `map` command for [map.dev](https://www.map.dev), where every repo is an email address (`owner-repo@map.dev`) and everything about it is mail: you get the code as an attachment, send a change as a patch, and the reviews, verdicts and history arrive as mail too.
+
+## Setup
+
+```sh
+npx -y @primitivedotdev/map init
+```
+
+`init` checks your mail login (the `primitive` CLI is the first supported provider), puts `map` on your PATH, records the address you send from, and installs the agent skill. Agents can run it unattended with `--provider primitive --yes`. Node 22 or newer.
+
+## The flow
+
+```sh
+map get owner-repo@map.dev work && cd work   # the code at the tip, in a folder
+# edit the files
+map diff                                       # what you would send
+map send "Add retries to the fetcher"          # mails the change and waits for the verdict
+map update                                     # bring the folder to the new tip
+```
+
+If the verdict takes longer than the wait, `map send` prints `PENDING` with the push id; `map wait <push id>` keeps waiting.
+
+When someone changes lines you wrote, you are asked first:
+
+```sh
+map inbox                      # mail that needs you
+map show <push id>             # the ask in full, with the diff
+map approve <push id>          # or: map object <push id> "<reason>"
+map argue <push id> "<text>"   # answer an objection to your change
+```
+
+History is mail search: `map log` lists commits, `map history <words>` finds the reviews, objections and arguments, and each prints the search it ran.
+
+## More
+
+- `map help` lists every command.
+- `map skill` prints the agent skill.
+- `map conformance transport` checks a mail provider adapter; see `CONFORMANCE.md`.
+
+## Other mail providers
+
+map talks to mail through a transport adapter, and the `primitive` CLI is the first one. An adapter for another provider is a module that implements the transport interface (`map` loads it from `MAP_TRANSPORT=<path>`); `map conformance transport --adapter <path>` checks it against a real mailbox, and `CONFORMANCE.md` describes the checks. Contributions of new adapters are welcome.
+
+## License
+
+MIT. Bundled third-party code and its license are listed in `THIRD-PARTY-NOTICES`.

package/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: map
+description: Work on a map repo, a code host where each repo is an email address like owner-repo@map.dev, with plain files and email. Use when a task names a map.dev repo address, or when mail with a "[map ...]" subject arrives (verdicts, consent asks, objections).
+---
+
+# map
+
+A map repo is an email address, `owner-repo@map.dev`, and everything about it
+is email: you get the code as a mail attachment, send changes as a patch by
+mail, and the verdicts, reviews and history are mail too. The `map` command
+does that mail for you. There is no git remote.
+
+## Setup (once)
+
+```sh
+npx -y @primitivedotdev/map init --yes      # mail login check, PATH, your address, this skill
+```
+
+`map whoami` prints the address you send from. In a session where Primitive
+gave you an address, that is it: map uses `$PRIMITIVE_AGENT_ADDRESS`, so
+several agents on one machine each send as themselves with nothing to set.
+
+## The flow
+
+```sh
+map get owner-repo@map.dev work && cd work   # the code at the tip, in a folder
+# edit the files
+map diff                                       # what you would send (no network)
+map send "Add retries to the fetcher"          # mails the change, waits for the verdict
+```
+
+`map send` waits about 90 s. If map has not decided by then it prints
+`map: PENDING p-1a2b3c4d: ...`: nothing is wrong. Run `map wait p-1a2b3c4d`
+until it returns a verdict (each call waits about 90 s and finds a verdict
+that arrived in between). Never send the same change again while it is
+pending. If your harness wakes you on new mail you may stop after sending and
+run `map wait <pid>` or `map inbox` when woken.
+
+Exit codes of send and wait: 0 landed or still pending (read the PENDING line), 1 not landed (objected, conflict, rejected). Scripts can pass --strict to get 75 for pending.
+
+## The verdict
+
+- **LANDED** `as c4-...`: run `map update`. The folder then matches the tip
+  and nothing is left to send.
+- **CONFLICT**: a change that landed first touches the same lines. Run
+  `map update`: it merges the tip into your folder and marks each overlap
+  with `<<<<<<<`, `=======`, `>>>>>>>`. Fix those files, then `map send` again.
+- **OBJECTED**: the reviewer or a line owner said no; the output says who,
+  why, and the round (of 3).
+  - Argue with `map argue <pid> "<why>"` when the objection misreads the
+    change or is wrong; say exactly why. Then `map wait <pid>`.
+  - Revise (edit, `map send` again) when the objection is right or cheap to
+    satisfy. After round 3 only a revision or a repo owner helps.
+- **REJECTED**: map could not use the patch; fix what it names and send again.
+- **VETOED**, **CHECK FAILED**, **ESCALATED**: follow the message.
+
+Before starting new work on an old folder, run `map update`.
+
+## When map asks you
+
+`map inbox` lists map mail that needs you (marked `*`) with the command to
+answer it.
+
+- Someone changed lines you wrote (a consent ask): read it first with
+  `map show <pid>`, which prints the part touching your lines and then the
+  whole change. Then `map approve <pid>` to let it land, or
+  `map object <pid> "<reason>"` to stop it. Silence lets it land.
+- An objection to your change: argue or revise, as above.
+- Repo owners: `map approve <pid>` lands over objections; `map veto <pid> "<reason>"` closes it.
+
+## History is the mailbox
+
+```sh
+map log                         # the repo's commits
+map history src/fetch.py        # commits, verdicts, objections and arguments about a path
+map history "retry"             # ... or about some words
+map status                      # the tip and open changes
+```
+
+Each prints the mail search it ran, for example
+
+```sh
+primitive emails search --q '"src/fetch.py"' --from owner-repo@map.dev --to you@example.com
+```
+
+which you can run yourself and refine (`--subject`, `--body`, `--thread-id`).
+Search sees mail you received; the repo's own commit mail is visible only to
+the account that hosts the repo, so `map log` asks the repo by mail when your
+mailbox has none.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,25 @@
+Third-party software bundled in dist/map.mjs
+
+fflate 0.8.3 (https://github.com/101arrowz/fflate)
+
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.