codex-pet-share 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codex Pet Share contributors
+
+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

@@ -0,0 +1,41 @@
+# codex-pet-share
+
+Install shared Codex pets from codex-pet-share.
+
+```sh
+npx codex-pet-share add pet-slug
+npx codex-pet-share add-collection collection-slug
+```
+
+Pets are installed into:
+
+```sh
+$HOME/.codex/pets/{pet-id}
+```
+
+## Commands
+
+### `add {pet-id}`
+
+Downloads the pet package by slug from codex-pet-share and writes `pet.json` and `spritesheet.webp` into the local Codex pets directory.
+
+```sh
+npx codex-pet-share add tiny-dino
+```
+
+### `add-collection {collection-slug}`
+
+Downloads every pet in a codex-pet-share collection and writes each package into the local Codex pets directory.
+
+```sh
+npx codex-pet-share add-collection cats
+```
+
+## Configuration
+
+The CLI defaults to the production API at `https://codex-pets.net`. To use a
+different deployment, set:
+
+```sh
+CODEX_PETS_API_BASE=https://your-deployment.example.com
+```

package/bin/codex-pets.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`codex-pet-share: ${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "codex-pet-share",
+  "version": "0.3.0",
+  "description": "Install shared Codex pets from codex-pet-share.",
+  "type": "module",
+  "bin": {
+    "codex-pet-share": "bin/codex-pets.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "format": "prettier --write ."
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/portons/codex-pet-share.git",
+    "directory": "codex-pets-installer"
+  },
+  "homepage": "https://codex-pets.net",
+  "bugs": {
+    "url": "https://github.com/portons/codex-pet-share/issues"
+  },
+  "keywords": [
+    "codex",
+    "codex-pets",
+    "pets",
+    "cli",
+    "installer"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "prettier": "^3.5.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,68 @@
+import { addPet, addPetCollection } from "./installer.js";
+
+const helpText = `Usage:
+  codex-pet-share add {pet-id}
+  codex-pet-share add-collection {collection-slug}
+
+Options:
+  -h, --help     Show this help message
+
+Environment:
+  CODEX_PETS_API_BASE   Override the codex-pet-share API base URL`;
+
+export async function runCli(args) {
+  const [command, value, ...extraArgs] = args;
+
+  if (!command || command === "-h" || command === "--help") {
+    console.log(helpText);
+    return;
+  }
+
+  if (command === "add") {
+    await runAddCommand(value, extraArgs);
+    return;
+  }
+
+  if (command === "add-collection") {
+    await runAddCollectionCommand(value, extraArgs);
+    return;
+  }
+
+  throw new Error(`unknown command "${command}"`);
+}
+
+async function runAddCommand(petId, extraArgs) {
+  if (!petId || extraArgs.length > 0) {
+    throw new Error("usage: codex-pet-share add {pet-id}");
+  }
+
+  const result = await addPet({ petId });
+  console.log(`Installed ${result.displayName} (${result.id})`);
+  console.log(result.installPath);
+}
+
+async function runAddCollectionCommand(collectionSlug, extraArgs) {
+  if (!collectionSlug || extraArgs.length > 0) {
+    throw new Error(
+      "usage: codex-pet-share add-collection {collection-slug}",
+    );
+  }
+
+  const result = await addPetCollection({
+    collectionSlug,
+    onPetInstalled: ({ pet, current, total }) => {
+      console.log(
+        `Installed ${current}/${total}: ${pet.displayName} (${pet.id})`,
+      );
+    },
+  });
+
+  if (result.total === 0) {
+    console.log(`No pets found in ${result.collection.displayName}`);
+    return;
+  }
+
+  console.log(
+    `Installed ${result.total} pets from ${result.collection.displayName}`,
+  );
+}

package/src/constants.js

@@ -0,0 +1,2 @@
+export const defaultApiBase = "https://codex-pets.net";
+export const petSlugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/src/installer.js

@@ -0,0 +1,233 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { defaultApiBase, petSlugPattern } from "./constants.js";
+import { extractZipEntries } from "./zip.js";
+
+const requiredPetFiles = ["pet.json", "spritesheet.webp"];
+
+export async function addPet({
+  petId,
+  apiBase = process.env.CODEX_PETS_API_BASE ||
+    process.env.PETSHARE_API_BASE ||
+    defaultApiBase,
+  codexDirectory = process.env.CODEX_HOME || path.join(homedir(), ".codex"),
+  fetchImpl = fetch,
+}) {
+  const normalizedPetId = normalizePetId(petId);
+  const baseUrl = normalizeApiBase(apiBase);
+  const pet = await fetchPet(baseUrl, normalizedPetId, fetchImpl);
+  return installPetPackage({
+    baseUrl,
+    pet,
+    codexDirectory,
+    fetchImpl,
+  });
+}
+
+export async function addPetCollection({
+  collectionSlug,
+  apiBase = process.env.CODEX_PETS_API_BASE ||
+    process.env.PETSHARE_API_BASE ||
+    defaultApiBase,
+  codexDirectory = process.env.CODEX_HOME || path.join(homedir(), ".codex"),
+  fetchImpl = fetch,
+  onPetInstalled,
+} = {}) {
+  const normalizedCollectionSlug = normalizeCollectionSlug(collectionSlug);
+  const baseUrl = normalizeApiBase(apiBase);
+  const collection = await fetchPetCollection(
+    baseUrl,
+    normalizedCollectionSlug,
+    fetchImpl,
+  );
+  const installedPets = [];
+  const totalPets = collection.pets.length;
+
+  for (const [index, pet] of collection.pets.entries()) {
+    const result = await installPetPackage({
+      baseUrl,
+      pet,
+      codexDirectory,
+      fetchImpl,
+    });
+    installedPets.push(result);
+    onPetInstalled?.({
+      pet: result,
+      current: index + 1,
+      total: totalPets,
+    });
+  }
+
+  return {
+    collection: collection.collection,
+    pets: installedPets,
+    total: installedPets.length,
+  };
+}
+
+async function installPetPackage({ baseUrl, pet, codexDirectory, fetchImpl }) {
+  const zipBytes = await fetchDownload(baseUrl, pet, fetchImpl);
+  const entries = extractZipEntries(Buffer.from(zipBytes));
+  const manifest = readManifest(entries, pet.id);
+  const installPath = path.join(codexDirectory, "pets", manifest.id);
+
+  await mkdir(installPath, { recursive: true });
+  for (const fileName of requiredPetFiles) {
+    const bytes = entries.get(fileName);
+    if (!bytes) {
+      throw new Error(`download did not include ${fileName}`);
+    }
+    await writeFile(path.join(installPath, fileName), bytes);
+  }
+
+  return {
+    id: manifest.id,
+    displayName: manifest.displayName,
+    installPath,
+  };
+}
+
+export function normalizePetId(petId) {
+  const normalizedPetId = String(petId || "").trim();
+  if (!petSlugPattern.test(normalizedPetId)) {
+    throw new Error("pet id must be a lowercase slug like tiny-dino");
+  }
+  return normalizedPetId;
+}
+
+export function normalizeCollectionSlug(collectionSlug) {
+  const normalizedCollectionSlug = String(collectionSlug || "").trim();
+  if (!petSlugPattern.test(normalizedCollectionSlug)) {
+    throw new Error("collection slug must be lowercase like cats");
+  }
+  return normalizedCollectionSlug;
+}
+
+export function normalizeApiBase(apiBase) {
+  const trimmedApiBase = String(apiBase || "")
+    .trim()
+    .replace(/\/+$/, "");
+  if (!trimmedApiBase) {
+    throw new Error("API base URL is required");
+  }
+
+  const url = new URL(trimmedApiBase);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("API base URL must use http or https");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+async function fetchPet(apiBase, petId, fetchImpl) {
+  const response = await fetchImpl(`${apiBase}/api/pets/${petId}/share-data`);
+  const body = await readJson(response);
+  if (!response.ok) {
+    throw new Error(
+      body.error || `pet lookup failed with status ${response.status}`,
+    );
+  }
+  if (!body.pet?.id) {
+    throw new Error("pet lookup returned an invalid response");
+  }
+  return body.pet;
+}
+
+async function fetchPetCollection(apiBase, collectionSlug, fetchImpl) {
+  let collection;
+  const pets = [];
+  let page = 1;
+  let totalPages = 1;
+
+  do {
+    const response = await fetchImpl(
+      `${apiBase}/api/collections/${collectionSlug}?page=${page}&pageSize=60`,
+    );
+    const body = await readJson(response);
+    if (!response.ok) {
+      throw new Error(
+        body.error ||
+          `pet collection lookup failed with status ${response.status}`,
+      );
+    }
+    if (!body.collection?.slug || !Array.isArray(body.pets)) {
+      throw new Error("pet collection lookup returned an invalid response");
+    }
+
+    const normalizedSlug = normalizeCollectionSlug(body.collection.slug);
+    if (normalizedSlug !== collectionSlug) {
+      throw new Error("pet collection lookup returned a different collection");
+    }
+
+    collection ||= { ...body.collection, slug: normalizedSlug };
+    pets.push(...body.pets.map(normalizePetSummary));
+    totalPages = normalizeTotalPages(body.totalPages);
+    page += 1;
+  } while (page <= totalPages);
+
+  return { collection, pets };
+}
+
+async function fetchDownload(apiBase, pet, fetchImpl) {
+  const downloadUrl = absoluteUrl(
+    apiBase,
+    pet.downloadUrl || `/api/pets/${pet.id}/download`,
+  );
+  const response = await fetchImpl(downloadUrl);
+  if (!response.ok) {
+    const body = await readJson(response);
+    throw new Error(
+      body.error || `pet download failed with status ${response.status}`,
+    );
+  }
+  return response.arrayBuffer();
+}
+
+function absoluteUrl(apiBase, value) {
+  if (value.startsWith("/")) {
+    return `${apiBase}${value}`;
+  }
+  return new URL(value, `${apiBase}/`).toString();
+}
+
+async function readJson(response) {
+  return response.json().catch(() => ({}));
+}
+
+function readManifest(entries, expectedPetId) {
+  const manifestBytes = entries.get("pet.json");
+  if (!manifestBytes) {
+    throw new Error("download did not include pet.json");
+  }
+
+  const manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+  if (manifest.id !== expectedPetId) {
+    throw new Error("downloaded pet.json id did not match the requested pet");
+  }
+  if (manifest.spritesheetPath !== "spritesheet.webp") {
+    throw new Error("downloaded pet.json has an invalid spritesheetPath");
+  }
+  return manifest;
+}
+
+function normalizePetSummary(pet) {
+  if (!pet?.id) {
+    throw new Error("pet collection lookup returned a pet without an id");
+  }
+  return {
+    ...pet,
+    id: normalizePetId(pet.id),
+  };
+}
+
+function normalizeTotalPages(value) {
+  const totalPages = value === undefined ? 1 : Number(value);
+  if (
+    !Number.isSafeInteger(totalPages) ||
+    totalPages < 1 ||
+    totalPages > 1000
+  ) {
+    throw new Error("pet collection lookup returned invalid pagination");
+  }
+  return totalPages;
+}

package/src/zip.js

@@ -0,0 +1,73 @@
+import { inflateRawSync } from "node:zlib";
+
+const localFileHeaderSignature = 0x04034b50;
+const storeMethod = 0;
+const deflateMethod = 8;
+
+export function extractZipEntries(zipBytes) {
+  const entries = new Map();
+  let offset = 0;
+
+  while (
+    offset + 4 <= zipBytes.length &&
+    zipBytes.readUInt32LE(offset) === localFileHeaderSignature
+  ) {
+    const flags = zipBytes.readUInt16LE(offset + 6);
+    const compressionMethod = zipBytes.readUInt16LE(offset + 8);
+    const compressedSize = zipBytes.readUInt32LE(offset + 18);
+    const uncompressedSize = zipBytes.readUInt32LE(offset + 22);
+    const fileNameLength = zipBytes.readUInt16LE(offset + 26);
+    const extraFieldLength = zipBytes.readUInt16LE(offset + 28);
+    const fileNameStart = offset + 30;
+    const fileNameEnd = fileNameStart + fileNameLength;
+    const dataStart = fileNameEnd + extraFieldLength;
+    const dataEnd = dataStart + compressedSize;
+
+    if ((flags & 0x08) !== 0) {
+      throw new Error("zip files with data descriptors are not supported");
+    }
+    if (dataEnd > zipBytes.length) {
+      throw new Error("zip file is truncated");
+    }
+
+    const fileName = zipBytes.toString("utf8", fileNameStart, fileNameEnd);
+    if (isUnsafeFileName(fileName)) {
+      throw new Error(`zip entry has an unsafe path: ${fileName}`);
+    }
+
+    if (!fileName.endsWith("/")) {
+      const compressedData = zipBytes.subarray(dataStart, dataEnd);
+      const data = inflateEntry(compressedData, compressionMethod);
+      if (data.length !== uncompressedSize) {
+        throw new Error(`zip entry has an invalid size: ${fileName}`);
+      }
+      entries.set(fileName, data);
+    }
+
+    offset = dataEnd;
+  }
+
+  if (!entries.size) {
+    throw new Error("zip file did not contain any files");
+  }
+
+  return entries;
+}
+
+function inflateEntry(compressedData, compressionMethod) {
+  if (compressionMethod === storeMethod) {
+    return Buffer.from(compressedData);
+  }
+  if (compressionMethod === deflateMethod) {
+    return inflateRawSync(compressedData);
+  }
+  throw new Error(`unsupported zip compression method: ${compressionMethod}`);
+}
+
+function isUnsafeFileName(fileName) {
+  return (
+    fileName.startsWith("/") ||
+    fileName.includes("\\") ||
+    fileName.split("/").includes("..")
+  );
+}