@shbernal/buzon 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shbernal
+
+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,152 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/banner/banner-dark.svg">
+  <img alt="buzon: disposable and long-lived email addresses on your own domain, for you and your agents" src="assets/banner/banner-light.svg">
+</picture>
+
+[![License][license-badge]][license]
+[![Bun][bun-badge]][bun]
+
+---
+
+[Install](#install) • [Quickstart](#quickstart) • [Commands](#commands) • [Agent skill](#agent-skill) • [How it works](#how-it-works) • [Docs](#docs)
+
+---
+
+</div>
+
+<img alt="buzon new ste creates an address, buzon wait prints the verification code, buzon delete removes it, buzon list shows the registry" src="assets/demo/demo.gif">
+
+buzon is a CLI for a self-hosted [cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email)
+instance, a mail server that runs on a Cloudflare Worker with D1.
+It creates addresses on your domain, waits for the verification code or magic link, and keeps
+a local record of which address belongs to which account.
+
+- Three tiers in the address name: `ste` for one code, `mte` for a few weeks, `lte` for a real
+  account. The instance deletes expired ones by itself.
+- `wait --code` and `wait --link` print just the code or the link, ready for a script or an
+  agent.
+- A local registry of every address with its site and note, so "which address did I use for
+  GitHub?" has an answer.
+- Deploys and upgrades of the upstream release, with every database patch shown and confirmed.
+- An agent skill that tells an AI agent when to pick each tier and how to get a code.
+
+## Why
+
+Public temp-mail services are blocked by most sign-up forms, and their inboxes are readable by
+anyone who guesses the name. A catch-all on your own domain avoids both, but turns into a pile
+of addresses nobody remembers. buzon puts a lifetime on each address, cleans up the short ones,
+and records the long ones.
+
+## Install
+
+buzon runs on [Bun](https://bun.sh). It reads its passwords from `BUZON_SITE_PASSWORD` and
+`BUZON_ADMIN_PASSWORD`, or else from the keyring: the Secret Service through `secret-tool` on
+Linux, the Keychain on macOS.
+
+```sh
+bun add -g @shbernal/buzon
+```
+
+No instance yet? [docs/deploying.md](docs/deploying.md) goes from a domain on Cloudflare to a
+running one.
+
+## Quickstart
+
+1. Store the instance's site password in the keyring, on Linux:
+
+   ```sh
+   secret-tool store --label="buzon site-password" service buzon key site-password
+   ```
+
+   On macOS:
+
+   ```sh
+   security add-generic-password -s buzon -a site-password -w
+   ```
+
+   Elsewhere, export `BUZON_SITE_PASSWORD` instead.
+
+2. Point buzon at the instance. It checks that the instance answers, serves the domain and
+   accepts the password before writing anything:
+
+   ```sh
+   buzon init --url https://mail.example.com --domain example.com
+   ```
+
+3. Create a one-shot address and use it on a sign-up form:
+
+   ```sh
+   buzon new ste
+   ```
+
+4. Wait for the code, then delete the address:
+
+   ```sh
+   buzon wait ste-2610-9qa --code --since 10m
+   ```
+
+   ```sh
+   buzon delete ste-2610-9qa
+   ```
+
+For an account you will come back to, keep the address and say what it is for:
+
+```sh
+buzon new lte --site github --note "GitHub account for side projects"
+```
+
+## Commands
+
+| Command                          | Does                                                       |
+| -------------------------------- | ---------------------------------------------------------- |
+| `new <ste\|mte\|lte>`            | Create an address, with `--site` and `--note`              |
+| `new custom <name>`              | Create an address with a name you choose, such as `jane`   |
+| `wait <address>`                 | Wait for new mail and print its `--code`, `--link` or text |
+| `read <address>`                 | Print the latest mail, `--all`, or one `--id`              |
+| `list`, `show <address>`         | Registry entries, filtered by `--tier` or `--site`         |
+| `note`, `delete`, `adopt`        | Edit, remove, or take in an address made elsewhere         |
+| `deploy`, `upgrade`, `export-db` | Ship a release, move to a newer one, dump the database     |
+
+Every command takes `--json`. `buzon --help` lists every command and flag.
+
+## Agent skill
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/agent-session/agent-session-dark.svg">
+  <img alt="An agent signs up for a trial: it creates an mte address with buzon, submits the form, waits for the code and enters it" src="assets/agent-session/agent-session-light.svg">
+</picture>
+
+[`skills/buzon`](skills/buzon/SKILL.md) teaches an agent to pick the tier, get a code or link,
+and find an address again later. Install it with:
+
+```sh
+npx skills add shbernal/buzon
+```
+
+A test fails the build when the skill names a command or flag the CLI does not have.
+
+## How it works
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/how-it-works/how-it-works-dark.svg">
+  <img alt="Mail to example.com goes through Cloudflare Email Routing to a Worker and D1; buzon talks to the Worker over HTTPS and keeps a local registry" src="assets/how-it-works/how-it-works-light.svg">
+</picture>
+
+Cloudflare Email Routing hands every message for your domain to the Worker, which stores it in D1.
+A daily cron deletes expired `ste` and `mte` addresses by the tier in their name.
+buzon talks to the Worker over its HTTPS API, and keeps the registry of sites and notes on your
+machine only.
+
+## Docs
+
+- [Deploying an instance](docs/deploying.md)
+- [Tiers and cleanup](docs/tiers.md)
+- [Files](docs/files.md)
+- [Upgrading](docs/upgrading.md)
+
+[license]: LICENSE
+[license-badge]: https://img.shields.io/github/license/shbernal/buzon?style=for-the-badge&color=c8452f
+[bun]: https://bun.sh
+[bun-badge]: https://img.shields.io/badge/bun-%E2%89%A51.4-2f5fa7?style=for-the-badge&logo=bun&logoColor=white

package/bin/buzon

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/bin.ts'

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@shbernal/buzon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "CLI and agent skill for a self-hosted cloudflare_temp_email instance: tiered addresses, codes and links, a local registry, and deploys.",
+  "keywords": [
+    "agent-skill",
+    "cli",
+    "cloudflare",
+    "disposable-email",
+    "temp-email"
+  ],
+  "license": "MIT",
+  "author": "shbernal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shbernal/buzon.git"
+  },
+  "bin": {
+    "buzon": "bin/buzon"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "prose": "charcheck"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3",
+    "charcheck": "^0.4.0",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "oxlint-tsgolint": "^7.0.2004",
+    "typescript": "^7"
+  },
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "packageManager": "bun@1.4.3"
+}

package/skills/README.md

@@ -0,0 +1,15 @@
+# Skills
+
+The agent-facing skill for buzon lives here so it versions with the CLI it describes.
+
+```sh
+npx skills add shbernal/buzon
+```
+
+| Skill                     | Use it for                                                              |
+| ------------------------- | ----------------------------------------------------------------------- |
+| [`buzon`](buzon/SKILL.md) | Addresses for sign-ups and accounts, verification codes and magic links |
+
+A skill that has drifted from the tool it describes is worse than no skill, so
+`tests/skill.test.ts` fails the build when `SKILL.md` names a command or flag the CLI does
+not have.

package/skills/buzon/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: buzon
+description: Create email addresses on the user's own temp-mail domain and read what arrives, including verification codes and magic links. Use when a sign-up form, trial, job application or service needs an email address, when a site sends a code or confirmation link, or when asked which address was used for an account.
+---
+
+# buzon
+
+`buzon` creates addresses on the user's self-hosted mail domain and reads their inbox. It
+keeps a local registry of every address with its tier, site and note.
+
+buzon is the only interface. Never call the mail API yourself, and never print, log or pass
+on the tokens buzon stores. Add `--json` to any command for machine-readable output; errors
+then come on stderr as `{"error": …, "causes": […]}`.
+
+## Pick the tier
+
+| Situation                                                       | Tier                           |
+| --------------------------------------------------------------- | ------------------------------ |
+| One code or link, then nothing more                             | `ste`, deleted after use       |
+| A process lasting weeks: a trial, one application cycle         | `mte`                          |
+| A real account the user may need again: a job portal, a service | `lte --site <site> --note "…"` |
+
+When the user asks for a specific name, such as `jane@`, use `buzon new custom jane --note "…"`.
+It is kept like `lte`.
+
+When unsure between `mte` and `lte`, pick `lte`: buzon keeps it and its site and note make
+the account findable later.
+
+`--site` is 1 to 12 lowercase letters or digits naming the platform, such as `greenhouse`,
+`lever` or `github`. `ste` takes no `--site`.
+
+An `lte` note says what the account is for and when it was made, in the user's words where
+possible: `--note "Greenhouse account for Acme job applications, 2026-10"`. Fix a note later
+with `buzon note <address> "…"`.
+
+## Get a code or a link
+
+```sh
+buzon new ste --json                  # prints the address
+# submit the form with that address
+buzon wait <address> --code --since 10m --json
+buzon delete <address>                # ste only
+```
+
+Delete an `ste` as soon as its code or link is in hand, without asking. If another code is
+needed later, a new `ste` costs nothing.
+
+`wait` takes `--code` for a verification code, `--link` for a confirmation or magic link,
+or neither for the whole mail. `--since 10m` also takes mail that landed before `wait`
+started; without it, `wait` only sees mail that arrives after it starts. Narrow a busy inbox
+with `--from <regex>` or `--subject <regex>`. It gives up after `--timeout 300` seconds and
+exits 1.
+
+To read mail that is already there: `buzon read <address>` for the latest, `--all` for every
+mail, `--id <n>` for one.
+
+## When nothing arrives
+
+1. `buzon read <address> --all`: the mail may be there but not match your filters, or carry
+   the code in a form `--code` did not pick up.
+2. Retry once: resend from the site if it offers that, then `wait` again.
+3. Still nothing: stop and tell the user which address you used and what you waited for.
+
+## Find and keep addresses
+
+```sh
+buzon list --site greenhouse --json   # also --tier ste|mte|lte|custom
+buzon show <address> --json           # registry entry and mail count
+```
+
+Before creating an `lte`, check `list --site` for one the user already has on that platform.
+
+Never delete an `lte` or `custom` address unless the user asks. buzon refuses without
+`--force`; pass it only on that explicit request.
+
+## Privacy
+
+Mail bodies are the user's private mail. Quote a code or link where the task needs it, and
+keep the rest out of unrelated outputs, files and commits.

package/src/bin.ts

@@ -0,0 +1,3 @@
+import { main } from './cli.ts'
+
+await main(process.argv.slice(2))

package/src/cli.ts

@@ -0,0 +1,149 @@
+import { parseArgv, UsageError } from './core/args.ts'
+import { causeChain } from './core/errors.ts'
+import { HELP } from './core/help.ts'
+import pkg from '../package.json' with { type: 'json' }
+
+export const COMMANDS = [
+  'init',
+  'new',
+  'list',
+  'show',
+  'note',
+  'delete',
+  'reissue',
+  'adopt',
+  'read',
+  'wait',
+  'delete-mail',
+  'deploy',
+  'upgrade',
+  'export-db',
+] as const
+
+type Command = (typeof COMMANDS)[number]
+
+const isCommand = (command: string): command is Command =>
+  (COMMANDS as readonly string[]).includes(command)
+
+const interactive = () => process.stdout.isTTY && process.stdin.isTTY
+
+function print<T>(json: boolean, payload: T, text: (payload: T) => string): void {
+  console.log(json ? JSON.stringify(payload, null, 2) : text(payload))
+}
+
+async function createContext() {
+  const { readConfig } = await import('./core/config.ts')
+  const { createApi } = await import('./core/api.ts')
+  const config = readConfig()
+  return { config, api: createApi(config) }
+}
+
+export async function run(argv: string[]): Promise<number> {
+  const parsed = parseArgv(argv)
+  const { command, flags } = parsed
+  const json = flags.json === true
+
+  if (flags.help || flags.h || command === 'help' || command === '') {
+    console.log(HELP)
+    return 0
+  }
+  if (flags.version || flags.v) {
+    console.log(pkg.version)
+    return 0
+  }
+
+  if (!isCommand(command)) throw new UsageError(`unknown command "${command}"\n\n${HELP}`)
+  switch (command) {
+    case 'init': {
+      const { init, initText } = await import('./commands/init.ts')
+      print(json, await init(flags, !json && interactive()), initText)
+      return 0
+    }
+    case 'new':
+    case 'list':
+    case 'show':
+    case 'note':
+    case 'delete':
+    case 'reissue':
+    case 'adopt': {
+      const commands = await import('./commands/addresses.ts')
+      const context = await createContext()
+      switch (command) {
+        case 'new':
+          print(json, await commands.create(parsed, context), commands.createText)
+          break
+        case 'list':
+          print(json, commands.list(parsed), commands.listText)
+          break
+        case 'show':
+          print(json, await commands.show(parsed, context), commands.showText)
+          break
+        case 'note':
+          print(json, commands.setNote(parsed, context), commands.setNoteText)
+          break
+        case 'delete':
+          print(json, await commands.remove(parsed, context), commands.removeText)
+          break
+        case 'reissue': {
+          const result = await commands.reissue(parsed, context)
+          print(json, result, commands.reissueText)
+          return result.missing.length > 0 ? 1 : 0
+        }
+        case 'adopt':
+          print(json, await commands.adopt(parsed, context), commands.adoptText)
+          break
+      }
+      return 0
+    }
+    case 'read':
+    case 'wait':
+    case 'delete-mail': {
+      const commands = await import('./commands/mail.ts')
+      const context = await createContext()
+      if (command === 'read') print(json, await commands.read(parsed, context), commands.readText)
+      if (command === 'wait') print(json, await commands.wait(parsed, context), commands.waitText)
+      if (command === 'delete-mail') {
+        print(json, await commands.removeMail(parsed, context), commands.removeMailText)
+      }
+      return 0
+    }
+    case 'deploy':
+    case 'upgrade':
+    case 'export-db': {
+      const commands = await import('./commands/deploy.ts')
+      const context = await createContext()
+      if (command === 'deploy')
+        print(json, await commands.deploy(parsed, context), commands.deployText)
+      if (command === 'upgrade') {
+        const result = await commands.upgrade(parsed, context, interactive())
+        print(json, result, commands.upgradeText)
+      }
+      if (command === 'export-db') {
+        print(json, await commands.exportDb(parsed, context), commands.exportDbText)
+      }
+      return 0
+    }
+    default:
+      return command satisfies never
+  }
+}
+
+export async function main(argv: string[]): Promise<void> {
+  const json = argv.includes('--json')
+  try {
+    process.exitCode = await run(argv)
+  } catch (error) {
+    const usage = error instanceof UsageError
+    const [message, ...causes] = usage ? [error.message] : causeChain(error)
+    if (json) {
+      console.error(JSON.stringify({ error: message, causes }))
+    } else {
+      console.error(message)
+      for (const cause of causes) console.error(`  caused by: ${cause}`)
+    }
+    if (process.env.BUZON_DEBUG && error instanceof Error && error.stack) {
+      console.error(error.stack)
+    }
+    process.exitCode = usage ? 2 : 1
+  }
+}