playcademy 0.28.1-beta.9 → 0.29.0

package/README.md

@@ -1,6 +1,11 @@
 # playcademy
 
-The official command-line interface for Playcademy - deploy and share your educational games with ease.
+**The official command-line interface for deploying and managing Playcademy games.**
+
+## Overview
+
+The `playcademy` CLI authenticates developers, configures games, deploys frontend and backend
+resources, and manages integrations such as TimeBack.
 
 ## Installation
 
@@ -186,7 +191,7 @@ my-game/
 
 Backend routes are automatically deployed with hosted games.
 
-## Authentication
+### Credential Storage
 
 Credentials are stored in `~/.playcademy/auth.json`:
 
@@ -277,7 +282,22 @@ playcademy timeback assessments import --env production
 Fixtures are written to `.playcademy/timeback/assessment-fixtures.json`. The local dev host serves
 them through the normal game SDK assessment methods and resets local attempts when it restarts.
 
-## Environment Variables
+#### `timeback assessments assets upload`
+
+Upload one public assessment image to immutable, content-addressed CDN storage. Production is the
+default for this command; pass `--env staging` explicitly when testing the upload flow.
+
+```bash
+playcademy timeback assessments assets upload ./diagram.png
+playcademy timeback assessments assets upload ./diagram.png --env staging
+playcademy timeback assessments assets upload ./diagram.png --json
+```
+
+Uploads accept PNG, JPEG, single-frame GIF, single-frame WebP, and uncompressed BMP files up to
+4 MiB and 25 megapixels. Re-uploading identical bytes returns the existing URL without creating
+another object.
+
+### Environment Variables
 
 - `CI` - Set to `1` or `true` to disable interactive prompts
 - `PLAYCADEMY_API_TOKEN` - API token for non-interactive authentication
@@ -300,7 +320,7 @@ PLAYCADEMY_PROFILE=work playcademy deploy
 PLAYCADEMY_BASE_URL=http://localhost:5174 playcademy deploy
 ```
 
-## CI/CD
+### CI/CD
 
 Use `CI=1`, `PLAYCADEMY_API_TOKEN`, and an explicit environment for pipeline deploys:
 
@@ -361,7 +381,7 @@ jobs:
                   PLAYCADEMY_API_TOKEN: ${{ secrets.PLAYCADEMY_API_TOKEN }}
 ```
 
-## Configuration Files
+### Configuration Files
 
 The CLI supports multiple configuration formats:
 
@@ -371,7 +391,18 @@ The CLI supports multiple configuration formats:
 
 Priority: CLI flags > config file > interactive prompts
 
-## Architecture
+## Development
+
+From the repository root, install dependencies and run the CLI directly from source:
+
+```bash
+bun install
+bun packages/cli/src/main.ts --help
+```
+
+Run `bun run check` and the relevant targeted tests before submitting changes.
+
+## Dependencies
 
 Built with:
 
@@ -380,6 +411,25 @@ Built with:
 - **Colorette** - Terminal styling
 - **esbuild** - Bundling (for encoding compatibility)
 
+## Examples
+
+```bash
+# Inspect the authenticated account
+playcademy me
+
+# Validate a staging deployment without publishing it
+playcademy deploy --env staging --dry-run
+
+# Upload an immutable assessment image to staging
+playcademy timeback assessments assets upload ./diagram.png --env staging
+```
+
+## Related Packages
+
+- [`@playcademy/sdk`](../sdk) - Runtime and server APIs used by Playcademy games
+- [`@playcademy/vite-plugin`](../vite-plugin) - Vite integration for Playcademy projects
+- [`@playcademy/timeback`](../timeback) - Shared TimeBack integration utilities
+
 ## Contributing
 
 See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

package/dist/bin.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire as __pcCreateRequire } from 'node:module'; const require = __pcCreateRequire(import.meta.url);
 
 // src/bin.ts
 import { spawnSync } from "node:child_process";

package/dist/bucket.d.ts

@@ -138,6 +138,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -170,6 +183,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**

package/dist/bucket.js

@@ -1,3 +1,4 @@
+import { createRequire as __pcCreateRequire } from 'node:module'; const require = __pcCreateRequire(import.meta.url);
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -20,7 +21,7 @@ var init_file_loader = __esm({
 
 // src/lib/bucket/dev.ts
 import { existsSync } from "fs";
-import { join as join8 } from "path";
+import { join as join7 } from "path";
 
 // ../edge-play/src/lib/constants.ts
 var ASSET_PREFIX = "_assets/";
@@ -28,10 +29,7 @@ var MANIFEST_KEY = "_manifest.json";
 var ASSET_ROUTE_PREFIX = "/api/assets/";
 
 // src/lib/bundle/game-backend.ts
-import { join as join6 } from "node:path";
-
-// src/constants/api.ts
-import { join as join2 } from "node:path";
+import { join as join5 } from "node:path";
 
 // src/constants/server.ts
 import { join } from "node:path";
@@ -39,12 +37,12 @@ var GAME_SERVER_ROOT_DIRECTORY = "server";
 var GAME_SERVER_LIB_DIRECTORY = join(GAME_SERVER_ROOT_DIRECTORY, "lib");
 
 // src/constants/api.ts
-var GAME_API_ROUTES_DIRECTORY = join2(GAME_SERVER_ROOT_DIRECTORY, "api");
+var GAME_API_ROUTES_DIRECTORY = `${GAME_SERVER_ROOT_DIRECTORY}/api`;
 
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.21-beta.9",
+  version: "0.0.21",
   type: "module",
   exports: {
     "./server": {
@@ -87,18 +85,7 @@ var package_default = {
 // src/constants/auth.ts
 var BETTER_AUTH_VERSION = package_default.dependencies["better-auth"];
 
-// src/constants/config.ts
-var ENV_FILES = [
-  ".env",
-  // Loaded first
-  ".env.development",
-  // Overrides .env
-  ".env.local"
-  // Overrides all (highest priority)
-];
-
 // src/constants/bucket.ts
-var BUCKET_ALWAYS_SKIP = [".git", ".DS_Store", ".gitignore", ...ENV_FILES];
 var PRESIGNED_UPLOAD_THRESHOLD = 4 * 1024 * 1024;
 
 // src/constants/cloudflare.ts
@@ -112,45 +99,48 @@ var CLOUDFLARE_BINDINGS = {
 };
 
 // src/constants/database.ts
-import { join as join3 } from "path";
-var DEFAULT_DATABASE_DIRECTORY = join3("server", "db");
+import { join as join2 } from "path";
+var DEFAULT_DATABASE_DIRECTORY = join2("server", "db");
 
 // src/constants/godot.ts
-import { join as join4 } from "node:path";
+import { join as join3 } from "node:path";
 var GODOT_BUILD_DIRECTORIES = {
   /** Root build directory (cleared before each export) */
   ROOT: "build",
   /** Web export subdirectory */
-  WEB: join4("build", "web")
+  WEB: join3("build", "web")
 };
 var GODOT_BUILD_OUTPUTS = {
   /** Exported web build entry point */
-  INDEX_HTML: join4("build", "web", "index.html"),
+  INDEX_HTML: join3("build", "web", "index.html"),
   /** Packaged zip file (created by Godot export) */
-  ZIP: join4("build", "web_playcademy.zip")
+  ZIP: join3("build", "web_playcademy.zip")
 };
 
 // src/constants/paths.ts
 import { homedir } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join4 } from "node:path";
 var WORKSPACE_NAME = ".playcademy";
 var CLI_DIRECTORIES = {
   WORKSPACE: WORKSPACE_NAME,
-  DATABASE: join5(WORKSPACE_NAME, "db"),
-  KV: join5(WORKSPACE_NAME, "kv"),
-  BUCKET: join5(WORKSPACE_NAME, "bucket"),
-  TIMEBACK: join5(WORKSPACE_NAME, "timeback")
+  DATABASE: join4(WORKSPACE_NAME, "db"),
+  KV: join4(WORKSPACE_NAME, "kv"),
+  BUCKET: join4(WORKSPACE_NAME, "bucket"),
+  TIMEBACK: join4(WORKSPACE_NAME, "timeback")
 };
-var PLAYCADEMY_HOME = join5(homedir(), ".playcademy");
+var PLAYCADEMY_HOME = join4(homedir(), ".playcademy");
 var CLI_USER_DIRECTORIES = {
   CONFIG: PLAYCADEMY_HOME,
-  BIN: join5(PLAYCADEMY_HOME, "bin"),
-  CACHE: join5(PLAYCADEMY_HOME, "cache")
+  BIN: join4(PLAYCADEMY_HOME, "bin"),
+  CACHE: join4(PLAYCADEMY_HOME, "cache")
 };
 var CLI_DEFAULT_OUTPUTS = {
-  WORKER_BUNDLE: join5(WORKSPACE_NAME, "worker-bundle.js")
+  WORKER_BUNDLE: join4(WORKSPACE_NAME, "worker-bundle.js")
 };
 
+// ../constants/src/platform.ts
+var ASSESSMENT_ASSET_MAX_BYTES = 4 * 1024 * 1024;
+
 // ../constants/src/timeback.ts
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
@@ -344,14 +334,14 @@ function resolveGameRoutesDir(config) {
   return typeof customRoutes === "object" && customRoutes.directory || GAME_API_ROUTES_DIRECTORY;
 }
 function getGameRoutesDirectory(projectPath, config) {
-  return join6(projectPath, resolveGameRoutesDir(config));
+  return join5(projectPath, resolveGameRoutesDir(config));
 }
 
 // src/lib/bucket/local.ts
-import { join as join7 } from "path";
+import { join as join6 } from "path";
 import { Miniflare } from "miniflare";
 async function openLocalBucket() {
-  const bucketDir = join7(getWorkspace(), CLI_DIRECTORIES.BUCKET);
+  const bucketDir = join6(getWorkspace(), CLI_DIRECTORIES.BUCKET);
   const mf = new Miniflare({
     modules: [{ type: "ESModule", path: "index.mjs", contents: "" }],
     r2Buckets: [CLOUDFLARE_BINDINGS.BUCKET],
@@ -368,7 +358,7 @@ async function openLocalBucket() {
 var ASSET_DEV_ROUTE_PREFIX = ASSET_ROUTE_PREFIX;
 function hasCustomAssetsRoute(projectRoot, config) {
   const routesDir = getGameRoutesDirectory(projectRoot, config);
-  return existsSync(join8(routesDir, "assets")) || existsSync(join8(routesDir, "assets.ts"));
+  return existsSync(join7(routesDir, "assets")) || existsSync(join7(routesDir, "assets.ts"));
 }
 function openLocalAssetBucket() {
   return openLocalBucket();