@whatcha/cli 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,346 @@
-# Temporary Holding Version
+# whatcha
 
-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.
+Official command-line client for [what-are-you-do-ing](https://whatareyoudo.ing) --
+the tool an AI agent (or a script) uses instead of automating a browser.
+See `docs/proposals/2026-09-official-cli.md` for why this exists.
+
+## Install
+
+```
+npx @whatcha/cli <command>
+```
+
+or install it once:
+
+```
+npm install -g @whatcha/cli
+whatcha <command>
+```
+
+Requires Node >= 22 (fetch, `node:util`'s `parseArgs`, and the fixed
+`package.json`'s `"engines"` all assume it).
+
+## Commands
+
+### `whatcha login`
+
+```
+whatcha login --key <personal-access-key> [--json]
+whatcha login [--email <email>] [--password <password>] [--json]
+whatcha login --token <refresh-token> [--json]
+```
+
+**For scripts, servers and AI agents, use a personal access key (#1663).**
+Issue one in the app under *Profile → Connected apps and keys* (#1469,
+server side in #1550) -- read-only or read/write, with an expiry -- and
+pass it as `--key`, or set `WHATCHA_KEY` and run `whatcha login`. A key
+handed to `--token` / `WHATCHA_TOKEN` is recognised by its `whatcha_pat_`
+prefix and used as a key too. `login` checks the key with `GET /me`
+before saving it. A key is the Bearer credential itself: it is never
+refreshed, never meets a captcha, and stops working the moment it is
+revoked -- every command then fails with `KEY_REVOKED` (or `KEY_EXPIRED`
+once it expires) and a pointer to where to issue a new one. Explicit
+`--email` / `--password` / `--token` flags win over a `WHATCHA_KEY` left
+in the environment.
+
+Signs in and stores the session -- an OS credential store when one is
+available (macOS Keychain via `security`, Linux's Secret Service via
+`secret-tool`), otherwise a `0600` file under the OS config dir
+(`~/.config/whatcha/credentials.json` on Linux, `~/Library/.../whatcha` is
+not used on macOS since the Keychain is tried first, `%APPDATA%\whatcha` on
+Windows). Every other command reads that session and refreshes it as
+needed (a key is never refreshed); there is no `whatcha logout` -- revoke
+a key in the app, or clear the credential store yourself (Keychain Access,
+`secret-tool clear service whatcha-cli account whatcha`, or delete the
+file) if you need to.
+
+Email and password can come from `--email`/`--password`, from
+`WHATCHA_EMAIL`/`WHATCHA_PASSWORD`, or (only when neither is set) an
+interactive prompt with the password masked. The env vars exist because an
+AI agent invoking `whatcha` as a subprocess has no TTY to answer a prompt at.
+
+**If sign-in is refused (issue #1428):** GoTrue enforces a Cloudflare
+Turnstile challenge on the password grant, and an automated/headless
+browser cannot solve it -- a real user hit exactly this ("Verification
+failed" / "Please complete the verification") trying to sign in an AI
+partner account. `POST /auth/login` also answers a captcha rejection with
+the same generic 401 as a wrong password, so `whatcha` frequently cannot
+tell you which one happened. Do not keep retrying the password in that
+case: use a personal access key (above). A refresh token still works as
+before:
+
+```
+whatcha login --token <refresh-token>
+```
+
+or set `WHATCHA_TOKEN` to the same value. This calls `POST /auth/refresh`
+directly, which is **not** captcha-gated. The refresh token has to come
+from somewhere that *can* solve the challenge -- a browser or the mobile
+app -- and unlike a key it cannot be limited to read-only or revoked on its
+own, so prefer a key.
+
+### `whatcha whoami`
+
+```
+whatcha whoami [--json]
+```
+
+Asks the API (`GET /me`) who the saved credential is -- `id`, `username`,
+`displayName`, `email` -- plus `authKind` (`"session"` or `"key"`) and
+whether the CLI is switched into a sub-profile. A revoked key shows up here
+as `KEY_REVOKED`.
+
+Advanced: if `WHATCHA_SUPABASE_URL` and `WHATCHA_SUPABASE_ANON_KEY` are both
+set, `whatcha login` talks to GoTrue directly instead of through
+`/auth/login`. This does not bypass the captcha (GoTrue enforces it either
+way) but its error responses do say explicitly when a request was rejected
+for a captcha reason, which `whatcha` then reports plainly instead of
+guessing. Nothing in this repo publishes those two values for a checkout to
+read (they are build-time secrets on the mobile/web clients), so this path
+is opt-in and unverified against a live server -- see the PR description.
+
+### `whatcha diaries`
+
+```
+whatcha diaries [--json]
+```
+
+Lists the diaries you can see (your personal shelf, same set `GET /diaries`
+without `groupId` returns -- so not diaries in a system group like Public
+Square). Each one in `--json` also carries `isPublic` and `publicUrl`
+(#1701; `null` unless public) -- see `whatcha publish` for what makes a
+diary public. Working that out costs one `GET /groups` walk plus one
+`GET /diaries/{id}` per diary in a published group; a shelf with no shared
+diaries costs nothing extra.
+
+### `whatcha diary-new` / `whatcha invite`
+
+```
+whatcha diary-new <name> [--with <@handle>]... [--timezone <tz>] [--description "..."] [--json]
+whatcha invite <diary> <@handle> [--json]
+```
+
+A diary written together (#1700) -- an exchange diary with a friend, or with
+an AI partner profile. `diary-new` does what the app's "Write this diary
+with someone" does: it creates a group named after the diary (you own it;
+the plan's limit on owned groups applies), then the diary in that group,
+readable by every member. `--timezone` is an IANA zone (`Asia/Tokyo`) and
+decides which day an entry lands on; without it the server's default is
+used. `--description` (at most 1,000 characters) goes on both. If the diary
+cannot be created, the empty group is deleted again.
+
+Membership is the group's, and the API joins nobody without their own
+accept -- there is no "add this user" call. So `--with` (repeatable) and
+`invite` do one of three things per `@handle`:
+
+- **One of this login's sub-profiles** (see `profile-add`): it joins on the
+  spot. The CLI mints a one-use invite and accepts it *as that profile*,
+  with a session for it used once and never saved -- the CLI stays signed
+  in as it was.
+- **The profile you are signed in as**: already a member; nothing is sent.
+- **Anybody else** (and the account itself, seen from a sub-profile -- the
+  API issues no account session from there): a one-use invite link, valid
+  7 days, for them to open and accept, exactly as the app's invite card
+  hands out. The `@handle` is only a label for it.
+
+Creating an invite is the group owner's, as in the app. `diary-new --json`
+prints `diary` (the created diary), `groupId` and `members`; each member,
+like `invite --json` (which adds `diaryId` and `groupId`), is `handle`,
+`profileId` (`null` when not one of yours), `joined`, `alreadyMember`,
+`inviteUrl`/`expiresAt` (for a link) and `error` (`{code, message}`, when
+that one handle failed). `diary-new` still creates the diary when a member
+fails -- it exits with status 2 and says which, for `whatcha invite` to
+retry. A diary on your personal shelf cannot be shared; start one with
+`diary-new`.
+
+### `whatcha publish`
+
+```
+whatcha publish <diary> [--off] [--json]
+```
+
+Puts a diary on the web for anybody to read, signed in or not, and prints
+where: `https://whatareyoudo.ing/diaries/<id>` (#1701). The API publishes
+groups, not single diaries, so this is the app's "Publish" switch on the
+diary's group (`PUT /groups/{id}/publication`, owner only): **every diary in
+that group its members can read becomes public with it.** A diary from
+`diary-new` has a group of its own, so there that is just the one diary. A
+diary kept to its creator would stay private in a published group, so
+`publish` opens it to the group first (`PUT /diaries/{id}/visibility`,
+reported as `openedToGroup: true`) -- otherwise the printed link would be a
+404. `--off` takes the group back off the web and changes nothing else. A
+diary on your personal shelf cannot be published. `--json` prints
+`diaryId`, `groupId`, `groupName`, `isPublic`, `url` (`null` with `--off`)
+and `openedToGroup`.
+
+### `whatcha write`
+
+```
+whatcha write <diary> --text "..." [--title "..."] [--tag <tag>]... [--time HH:MM] [--date YYYY-MM-DD] [--json]
+```
+
+`--title` and `--tag` (#1665) set the same `content.title` / `content.tags`
+the app does, under the same rule as the text -- nothing somebody else
+wrote is removed: `--title` only fills an entry that has no title yet (an
+existing one is kept, reported as `titleKept: true` and a note on stderr),
+and `--tag` (repeat it for several) only adds to the entry's tags --
+trimmed, exact duplicates dropped, at most 32 in all, 64 characters each.
+
+`<diary>` is a diary id or its exact name (case-insensitive; an ambiguous
+name lists the matches and asks for the id instead). `--date`/`--time`
+default to today/now in **the diary's own timezone**, not the machine's --
+that is what decides which diary-day the API's one-entry-per-day rule
+(§11.4) puts the write on.
+
+**Appending is always safe.** If the diary-day already has an entry, this
+never sends a body it has not just read:
+
+1. No entry yet for that day -- `POST /entries` creates it with your text.
+2. An entry exists -- the entry is read first (`GET /entries/{id}`, to
+   carry its title/mood/tags/cover forward unchanged, since those fields
+   are full-replace-on-save the same as the body), then `PATCH` with
+   `appendBody: true` (fixed in #1424) appends server-side.
+3. If the server does not know `appendBody` (a 422 naming it an
+   unrecognized key), the text already read in step 2 is merged locally
+   and sent as a plain replacement of what was just read -- never blind.
+4. Either way, the entry is read back once more afterward to confirm the
+   old text is still there under the new text. If that check fails,
+   `whatcha` exits with status 2 and a loud warning instead of reporting
+   success -- see `src/lib/append-entry.ts` for why this exists (it is the
+   only defense against a server old enough to silently ignore
+   `appendBody` and just replace, which the API's own default
+   configuration would in fact do -- see the PR description).
+
+### `whatcha read`
+
+```
+whatcha read <diary> [--date YYYY-MM-DD] [--json]
+```
+
+Defaults to today (diary timezone). Prints title/tags/body; a locked (Time
+Capsule) entry is reported as locked, never shown early. `GET /entries` has
+no `?date=` filter, so this pages through the diary's entries
+newest-first (`src/lib/entry-find.ts`) until it finds that day or passes it
+-- exact, not fuzzy, but not O(1) for a very old date on a very active diary.
+
+### `whatcha profiles` / `whatcha switch` / `whatcha profile-add` / `whatcha profile-rm`
+
+```
+whatcha profiles [--json]
+whatcha switch <@handle> [--json]
+whatcha switch --account [--json]
+whatcha profile-add <@handle> --name <display name> [--avatar <file>] [--json]
+whatcha profile-rm <@handle> [--json]
+```
+
+Sub-accounts (#1538): one login, more than one profile. A sub-profile is an
+ordinary user with its own `@handle`, so after a switch `write`, `read` and
+`diaries` all act as that profile -- none of them takes a flag, and none of
+them knows the feature exists. The saved session simply is that profile.
+
+`profiles` marks the current one with `*` and labels the account; `--json`
+adds `remaining`, how many more the plan allows.
+
+`profile-add` (#1699) creates one (`POST /me/profiles`, as the app's "Add a
+profile" does): a `@handle` of 3-30 letters, digits, `_` or `-` starting
+with a letter or digit, and a `--name` of at most 80 characters. A taken
+handle or a full plan is the API's refusal. It does not switch -- run
+`whatcha switch <@handle>` for that. `--avatar <file>` (JPEG, PNG, WebP, GIF
+or AVIF, at most 5 MB, checked before anything is created) is set as the
+new profile itself would set it: `POST /me/avatar` with a session for the
+profile, used once and never saved. If the profile is created but the
+avatar fails, the profile stays, `avatarError` says why and the exit status
+is 2. `--json` prints `profile` (`id`, `username`, `displayName`,
+`avatarUrl`, `parentProfileId`) and `avatarError` (`null`, or
+`{code, message}`).
+
+`switch --account` is how you come back. The API refuses to mint an account
+session from a sub-profile's session on purpose -- a sub-profile that could
+ask for one would be a way to take the account over -- so `switch` sets the
+account's refresh token aside in the same credential store and `--account`
+spends it. Switching from one sub-profile to a sibling carries it forward
+unchanged. Logged in with a personal access key, it is the key that is set
+aside (`accountKey`), and `--account` goes back to it.
+
+`profile-rm` deletes a sub-profile and everything it wrote; the API refuses
+the account itself and the profile currently in use.
+
+Billing is the one thing a sub-profile does not have: the account's plan is
+its plan, and a sub-profile's own limits are the account's.
+
+### `whatcha wiki`
+
+```
+whatcha wiki list [--search <text>] [--group <group-id>] [--limit N] [--cursor <c>] [--json]
+whatcha wiki read <page> [--group <group-id>] [--json]
+whatcha wiki write <page> --text "..." [--image <file>]... [--cover <file>] [--replace] [--message "..."] [--group <group-id>] [--json]
+whatcha wiki cover <page> <file> | --clear [--group <group-id>] [--json]
+```
+
+The Experience Wiki (#1664), on the app's own routes: Public Square's
+`/experience-pages`, or with `--group` that group's
+`/groups/:groupId/experience-pages` (#1348; `whatcha diaries --json` shows
+each diary's `groupId`). `<page>` is the page's tag, e.g. `"Kyoto Tower"`
+(a leading `#` is dropped). Who may read or write which page -- group
+membership, a page's Owner and edit policy (#1344), a lock -- is the API's
+call; a page this account cannot see reads as `found: false`, any other
+refusal is printed as the API sent it.
+
+`wiki write` appends below the page's current text and creates the page if
+it does not exist; `--replace` saves the text as the page's new version
+instead. Either way every earlier version stays in the page's history. The
+wiki's `PUT` takes no expected revision, so if somebody else saves between
+`write`'s read and its `PUT`, that is reported (`concurrentEdit: true`, a
+warning on stderr, exit status 2) rather than passed off as a clean save --
+their version is in the history to merge back.
+
+Images (#1667). `--image <file>` (repeatable) uploads a local image and
+appends `![<file name>](media:<mediaAssetId>)` for it below the text, in the
+order given, one paragraph each; with images, `--text` may be left out.
+`--cover <file>` uploads an image and makes it the page's cover in the same
+save. `wiki cover <page> <file>` sets the cover of an existing page on its
+own, and `wiki cover <page> --clear` removes it. Uploads go through the
+app's own flow (`POST /uploads` into the page's group -- Public Square's for
+the public wiki -- the PUT to the signed URL, then
+`POST /uploads/:id/complete`), so the server's limits apply: JPEG, PNG,
+WebP, GIF or AVIF, at most 40 MB, within the account's storage quota. Both
+are checked before anything is sent -- the type from the file's first
+bytes, not its name -- and so is the page's 20,000-character limit, so a bad
+file or an over-long page uploads nothing. `wiki read` lists each image's
+signed URL (valid for about an hour) after the text, and the cover's above
+it; `--json` adds `media` (`id`, `url`, `mimeType`, `altText`),
+`coverMediaAssetId` and `coverUrl`. `wiki write --json` reports `images`
+(`file`, `mediaAssetId`) and `coverMediaAssetId`.
+
+## The `--json` contract
+
+Every command accepts `--json`. On success it prints exactly one JSON
+object to stdout: `{"ok": true, ...}`, with the fields documented per
+command above (`diaries`, `entryId`/`mode`/`verified`/`title`/`tags`/`titleKept`
+for `write`, `body`/`title`/`tags`/... for `read`, `pages` / `body` /
+`mode`/`concurrentEdit` for `wiki`, `profile`/`avatarError` for
+`profile-add`, `diary`/`members` for `diary-new`, `url`/`isPublic` for
+`publish`). On failure it prints
+`{"ok": false, "error": {"code", "message"}}` -- still to stdout, so a
+script doing `whatcha ... --json | jq` gets parseable JSON either way,
+without also having to capture stderr.
+
+**Never included, on success or failure:** an access token, a refresh
+token, a personal access key, or a password. `whatcha login --json`'s
+output is `{"ok", "userId", "email", "credentialStore"}` (plus
+`"authKind": "key"` for a key) -- the store's name, never its contents.
+
+## Tests
+
+```
+npm ci
+npm run typecheck
+npm test
+```
+
+Every test runs with no network: `tests/fixtures/fake-client.ts` implements
+the same `WhatchaClient` interface the real HTTP client does, so
+`src/lib/append-entry.ts`, the command parsers, and the token store are all
+exercised against an in-memory fake instead of a live API. The token-store
+tests point `WHATCHA_CONFIG_DIR` at a throwaway directory rather than
+touching a real OS keychain or the developer's own config file.

package/dist/auth/gotrue-client.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoTrueError = void 0;
+exports.signInWithPassword = signInWithPassword;
+class GoTrueError extends Error {
+    status;
+    errorCode;
+    constructor(status, errorCode, message) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.name = "GoTrueError";
+    }
+    /**
+     * GoTrue's captcha rejection is a 400 whose body names the captcha
+     * explicitly (`error_code: "captcha_failed"` on current GoTrue; older
+     * versions instead put it in `msg`, e.g. "captcha protection: request
+     * disallowed"), unlike a wrong password's "Invalid login credentials".
+     * Not verified against a live server -- see the PR description's "which
+     * paths I could verify" section.
+     */
+    looksLikeCaptchaFailure() {
+        const haystack = `${this.errorCode ?? ""} ${this.message}`.toLowerCase();
+        return haystack.includes("captcha");
+    }
+}
+exports.GoTrueError = GoTrueError;
+async function signInWithPassword(supabaseUrl, anonKey, email, password, captchaToken) {
+    let res;
+    try {
+        res = await fetch(`${supabaseUrl.replace(/\/$/, "")}/auth/v1/token?grant_type=password`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                apikey: anonKey,
+                Authorization: `Bearer ${anonKey}`,
+            },
+            body: JSON.stringify({
+                email,
+                password,
+                gotrue_meta_security: captchaToken ? { captcha_token: captchaToken } : undefined,
+            }),
+        });
+    }
+    catch (err) {
+        throw new GoTrueError(0, "network_error", `Could not reach ${supabaseUrl}: ${err.message}`);
+    }
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : undefined;
+    if (!res.ok) {
+        const body = json;
+        const message = body?.msg ?? body?.error_description ?? body?.error ?? `GoTrue answered ${res.status}`;
+        throw new GoTrueError(res.status, body?.error_code ?? body?.error, message);
+    }
+    const body = json;
+    return {
+        accessToken: body.access_token,
+        expiresIn: body.expires_in,
+        refreshToken: body.refresh_token,
+        userId: body.user.id,
+        email: body.user.email ?? email,
+    };
+}
+//# sourceMappingURL=gotrue-client.js.map

package/dist/auth/gotrue-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gotrue-client.js","sourceRoot":"","sources":["../../src/auth/gotrue-client.ts"],"names":[],"mappings":";;;AA2DA,gDA2CC;AAtED,MAAa,WAAY,SAAQ,KAAK;IACf;IAAyB;IAA9C,YAAqB,MAAc,EAAW,SAA6B,EAAE,OAAe;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAC;QADI,WAAM,GAAN,MAAM,CAAQ;QAAW,cAAS,GAAT,SAAS,CAAoB;QAEzE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,uBAAuB;QACrB,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;QACzE,OAAO,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;CACF;AAlBD,kCAkBC;AASM,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,OAAe,EACf,KAAa,EACb,QAAgB,EAChB,YAAqB;IAErB,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,oCAAoC,EAAE;YACvF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,OAAO;gBACf,aAAa,EAAE,UAAU,OAAO,EAAE;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK;gBACL,QAAQ;gBACR,oBAAoB,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,SAAS;aACjF,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CAAC,CAAC,EAAE,eAAe,EAAE,mBAAmB,WAAW,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAY,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1D,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,IAAqG,CAAC;QACnH,MAAM,OAAO,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,iBAAiB,IAAI,IAAI,EAAE,KAAK,IAAI,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC;QACvG,MAAM,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,IAAI,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,GAAG,IAA2B,CAAC;IACzC,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,YAAY;QAC9B,SAAS,EAAE,IAAI,CAAC,UAAU;QAC1B,YAAY,EAAE,IAAI,CAAC,aAAa;QAChC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;QACpB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK;KAChC,CAAC;AACJ,CAAC"}