petdex 0.4.7 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +35 -23
  2. package/dist/petdex.js +81 -429
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # petdex
2
2
 
3
- The Petdex CLI: browse, install, and submit animated pets for [OpenAI Codex](https://openai.com/codex) from your terminal.
3
+ The Petdex CLI: browse, install, and submit animated pets for your coding agents from your terminal.
4
+
5
+ The pets themselves are shown by [Petdex Desktop](https://petdex.dev/download), which
6
+ connects your agents from its own Settings window. This CLI is the catalog client.
4
7
 
5
8
  - **Gallery & docs:** <https://petdex.dev>
6
9
  - **Repo:** <https://github.com/crafter-station/petdex>
@@ -23,16 +26,21 @@ Requires Node.js 20+ (also runs on Bun).
23
26
  ```sh
24
27
  petdex login # opens browser, OAuth + PKCE via Clerk
25
28
  petdex list # browse approved pets
26
- petdex install boba # drops boba into ~/.codex/pets/boba/
27
- petdex select # pick active mascot from installed pets (interactive)
28
- petdex select boba # set active mascot directly
29
- petdex submit ~/.codex/pets/boba # share a single pet
30
- petdex submit ~/.codex/pets # bulk submit every subfolder
29
+ petdex install boba # drops boba into ~/.petdex/pets/boba/
30
+ petdex submit ~/.petdex/pets/boba # share a single pet
31
+ petdex submit ~/.petdex/pets # bulk submit every subfolder
31
32
  petdex whoami # confirm signed-in identity
32
33
  petdex logout # clear stored credentials
33
34
  ```
34
35
 
35
- After installing a pet, set it as active with `petdex select` or inside Codex: **Settings → Appearance → Pets → Select**. Use `/pet` inside Codex to wake or tuck it away.
36
+ After installing a pet, pick the active mascot in Petdex Desktop: hover the pet and
37
+ press <kbd>Cmd</kbd>+<kbd>,</kbd> to open Settings.
38
+
39
+ ## Desktop app
40
+
41
+ The floating mascot ships as the **Petdex desktop app**, not through this CLI. The app installs agent hooks from its Settings window (one click per agent) and updates itself. Download it at <https://petdex.dev/download>.
42
+
43
+ The `init`, `up`, `down`, `toggle`, `desktop`, `update`, `doctor`, and `hooks` commands were removed in v1.0.0; running them prints a pointer to the app.
36
44
 
37
45
  ## Commands
38
46
 
@@ -42,9 +50,10 @@ After installing a pet, set it as active with `petdex select` or inside Codex: *
42
50
  | `petdex logout` | Clear local credentials. |
43
51
  | `petdex whoami` | Print the signed-in user's identity. |
44
52
  | `petdex list` | List approved pets in the gallery. |
45
- | `petdex install <slug>` | Install a pet into `~/.codex/pets/<slug>/` and `~/.petdex/pets/<slug>/`. |
46
- | `petdex select [slug]` | Set the active pet shown by Petdex Desktop. No args = interactive picker; pass a slug to skip the prompt. |
53
+ | `petdex install <slug>` | Install a pet into `~/.petdex/pets/<slug>/` and `~/.codex/pets/<slug>/`. |
47
54
  | `petdex submit <path>` | Submit a pet folder, zip, or parent of pets (bulk). |
55
+ | `petdex edit <slug>` | Edit a pet you own (`--desc`, `--displayName`, `--sprite`, `--meta`, `--zip`). |
56
+ | `petdex telemetry [on\|off\|status]` | Manage anonymous usage telemetry. |
48
57
  | `petdex --version` | Print the CLI version. |
49
58
 
50
59
  ## How `submit` works
@@ -52,9 +61,9 @@ After installing a pet, set it as active with `petdex select` or inside Codex: *
52
61
  The CLI accepts three input shapes:
53
62
 
54
63
  ```sh
55
- petdex submit ~/.codex/pets/boba # single folder (must contain pet.json + spritesheet.{webp,png})
64
+ petdex submit ~/.petdex/pets/boba # single folder (must contain pet.json + spritesheet.{webp,png})
56
65
  petdex submit ~/Downloads/boba.zip # single zip with the same root layout
57
- petdex submit ~/.codex/pets # parent folder: every subfolder containing pet.json is submitted
66
+ petdex submit ~/.petdex/pets # parent folder: every subfolder containing pet.json is submitted
58
67
  ```
59
68
 
60
69
  Per submission the CLI:
@@ -69,7 +78,8 @@ A spinner shows progress per pet; a summary lists failures with reasons. Slugs a
69
78
  ## Validation rules
70
79
 
71
80
  - `pet.json` and `spritesheet.webp` (or `.png`) must exist at the root.
72
- - Spritesheet ≥ 256×256. Recommended **1536×1872** (8×9 frame grid).
81
+ - Spritesheet must be an 8x9 grid (**1536x1872**) or a v2 8x11 grid (**1536x2288**),
82
+ or a clean scale of either. ChatGPT pet exports are already the v2 shape.
73
83
  - Rate limit: **10 submissions / 24h** per user. Admins bypass.
74
84
 
75
85
  ## Configuration
@@ -92,15 +102,17 @@ petdex login
92
102
 
93
103
  The flow uses the [`@clerk/cli-auth`](https://github.com/Railly/clerk-cli-auth-example) reference implementation, vendored into this package.
94
104
 
95
- ## How to make a pet (creation lives inside Codex)
105
+ ## How to make a pet
106
+
107
+ This CLI distributes pets. It does not generate them.
96
108
 
97
- This CLI distributes pets. It does not generate them. To create one:
109
+ **In the ChatGPT desktop app.** Type `/pet` and describe what you want, then submit
110
+ the folder it writes: `petdex submit ~/.codex/pets/<slug>`.
98
111
 
99
- 1. Open the **Codex desktop app** (download at <https://openai.com/codex>).
100
- 2. Go to **Skills** in the top navbar → install **Hatch Pet**.
101
- 3. In a Codex chat, type `/pet` and describe what you want (e.g. *"a tiny otter sipping bubble tea"*).
102
- 4. Codex generates the spritesheet and animations into `~/.codex/pets/<slug>/`.
103
- 5. Submit it: `petdex submit ~/.codex/pets/<slug>`.
112
+ **From a ChatGPT pet export.** ChatGPT exports a 1536x2288 spritesheet, which is the
113
+ same atlas Petdex reads: nine state rows, matching frame counts. Download the PNG and
114
+ drop it on <https://petdex.dev/submit>. The grid is measured for you and the `pet.json`
115
+ the export omits is generated before you name it.
104
116
 
105
117
  The full step-by-step (with tips on what makes a great pet) lives at <https://petdex.dev/create>.
106
118
 
@@ -111,22 +123,22 @@ The full step-by-step (with tips on what makes a great pet) lives at <https://pe
111
123
  | `Not signed in` | No tokens or session expired | `petdex login` |
112
124
  | `presign 401` | Bearer rejected by Clerk userinfo | `petdex logout && petdex login` |
113
125
  | `presign 429` | 10/24h rate limit hit | Wait 24h or open a [submit-fallback issue](https://github.com/crafter-station/petdex/issues/new?labels=submit-fallback) |
114
- | `register 400 invalid_spritesheet` | Sprite < 256×256 | Regenerate with bigger dims (recommend 1536×1872) |
115
- | `register 400 missing_field` | Folder missing `pet.json` or `spritesheet.{webp,png}` | Inspect folder contents, re-export from Codex if needed |
126
+ | `register 400 invalid_spritesheet` | Not an 8x9 or 8x11 grid | Re-export at 1536x1872 or 1536x2288 |
127
+ | `register 400 missing_field` | Folder missing `pet.json` or `spritesheet.{webp,png}` | Inspect folder contents, re-export the pet if needed |
116
128
  | `R2 PUT 403` | Presigned URL expired (60s TTL) | Retry the failed submission. CLI auto-presigns fresh URLs |
117
129
 
118
130
  ## Common install issues
119
131
 
120
132
  The CLI is a single bundled JS file with no native dependencies.
121
133
  install path is just `fetch a JSON manifest, write two files to
122
- ~/.codex/pets/<slug>/`. Most "stuck" reports trace to one of these:
134
+ ~/.petdex/pets/<slug>/`. Most "stuck" reports trace to one of these:
123
135
 
124
136
  | Symptom | Cause | Fix |
125
137
  | --- | --- | --- |
126
138
  | Hangs at `Need to install the following packages: petdex@x` | `npx`'s own confirmation prompt, not a hang. Press `y` or auto-confirm | `npx -y petdex install <slug>` |
127
139
  | `npm ERR! engine Unsupported engine` | Node < 20 | Upgrade Node to 20+ (`nvm install 20` is the easiest path) |
128
140
  | `manifest fetch 5xx` / network timeout | Slow connection or corporate/national firewall blocking `petdex.dev` | Set a proxy: `HTTPS_PROXY=http://your.proxy:port npx petdex install <slug>` |
129
- | `EACCES: permission denied … ~/.codex/pets/` | Pets dir owned by another user | `sudo chown -R "$USER" ~/.codex` or remove the dir and retry |
141
+ | `EACCES: permission denied … ~/.petdex/pets/` | Pets dir owned by another user | `sudo chown -R "$USER" ~/.petdex` or remove the dir and retry |
130
142
  | Windows: `'sh' is not recognized` | CLI version older than 0.1.1 piped through `curl … \| sh` | Upgrade: `npm i -g petdex@latest` or `npx petdex@latest install <slug>` |
131
143
 
132
144
  The CLI bundles `@clack/prompts`, `picocolors`, and `jszip` into the