playcademy 0.24.1-beta.5 → 0.25.0-beta.2

package/dist/bucket.d.ts

@@ -0,0 +1,214 @@
+import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
+import { Miniflare } from 'miniflare';
+
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * Base configuration for TimeBack integration (shared across all courses).
+ * References upstream TimeBack types from @playcademy/timeback.
+ *
+ * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
+ */
+interface TimebackBaseConfig {
+    /** Organization configuration (shared across all courses) */
+    organization?: Partial<OrganizationConfig>;
+    /** Course defaults (can be overridden per-course) */
+    course?: Partial<CourseConfig>;
+    /** Component defaults */
+    component?: Partial<ComponentConfig>;
+    /** Resource defaults */
+    resource?: Partial<ResourceConfig>;
+    /** ComponentResource defaults */
+    componentResource?: Partial<ComponentResourceConfig>;
+}
+/**
+ * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
+ * Used in playcademy.config.* to allow per-course customization.
+ */
+interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+    title?: string;
+    courseCode?: string;
+    level?: string;
+    metadata?: CourseConfig['metadata'];
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+}
+/**
+ * TimeBack integration configuration for Playcademy config file.
+ *
+ * Supports two levels of customization:
+ * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
+ * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
+ *
+ * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
+ */
+interface TimebackIntegrationConfig {
+    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
+    courses: TimebackCourseConfigWithOverrides[];
+    /** Optional base configuration (shared across all courses, can be overridden per-course) */
+    base?: TimebackBaseConfig;
+}
+/**
+ * Custom API routes integration
+ */
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
+}
+/**
+ * Bucket storage integration
+ */
+interface BucketIntegration {
+    /**
+     * Directory whose contents are synced to the bucket by `playcademy bucket
+     * sync` (defaults to 'bucket'). Synced as a single content-addressed tree:
+     * the whole directory is the manifest's source of truth.
+     */
+    directory?: string;
+}
+/**
+ * Database integration
+ */
+interface DatabaseIntegration {
+    /** Database directory (defaults to 'db') */
+    directory?: string;
+    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
+     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
+    strategy?: 'push' | 'migrate';
+}
+interface QueueConfig {
+    maxBatchSize?: number;
+    maxRetries?: number;
+    maxBatchTimeout?: number;
+    maxConcurrency?: number;
+    retryDelay?: number;
+    deadLetterQueue?: string;
+}
+/**
+ * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig | null;
+    /** Custom API routes (optional) */
+    customRoutes?: CustomRoutesIntegration | boolean;
+    /** Database (optional) */
+    database?: DatabaseIntegration | boolean;
+    /** Key-Value storage (optional) */
+    kv?: boolean;
+    /** Bucket storage (optional) */
+    bucket?: BucketIntegration | boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
+    /** Queues (optional) */
+    queues?: Record<string, QueueConfig | boolean>;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'godot';
+    /** Integrations (database, custom routes, external services) */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Local Bucket Access
+ *
+ * One place that knows how to open the local R2 bucket (a Miniflare instance
+ * persisted under the workspace). Every `bucket` command that touches local
+ * storage goes through {@link withLocalBucket} so the Miniflare config lives in
+ * a single spot and the instance is always disposed.
+ */
+
+/** The local R2 binding handed back by Miniflare's `getR2Bucket`. */
+type LocalBucket = Awaited<ReturnType<Miniflare['getR2Bucket']>>;
+/** A persistent local bucket handle the caller is responsible for disposing. */
+interface LocalBucketSession {
+    bucket: LocalBucket;
+    dispose: () => Promise<void>;
+}
+
+/**
+ * Local Asset Dev Support
+ *
+ * Helpers the Vite plugin uses to give `asset()` a working local-dev story.
+ * In production the edge worker injects the asset manifest into the page and
+ * serves `/api/assets/*` from R2; in `vite dev` there is no edge worker, so the
+ * plugin reproduces both against the local Miniflare bucket that `bucket sync`
+ * writes to. Keeping this here means the Miniflare lifecycle and the `_assets/`
+ * layout live in one place — the plugin never touches Miniflare directly.
+ */
+
+/** The serving base the manifest is injected with (matches the edge worker). */
+declare const ASSET_DEV_ROUTE_PREFIX = "/api/assets/";
+/**
+ * Whether the game defines a custom route that owns `/api/assets/*`.
+ *
+ * In production a game's `server/api/assets` route supersedes the built-in
+ * content-addressed asset route (Hono first-match-wins). Dev must honor the
+ * same precedence: when this returns true, the Vite plugin should NOT register
+ * its `/api/assets/*` middleware, letting requests proxy to the backend where
+ * the custom route runs — matching deployed behavior.
+ *
+ * A route owning that path lives at `<customRoutesDir>/assets.ts` or
+ * `<customRoutesDir>/assets/...` (e.g. `assets/index.ts`, `assets/[...path].ts`),
+ * so the presence of an `assets` file or directory there is sufficient.
+ */
+declare function hasCustomAssetsRoute(projectRoot: string, config?: PlaycademyConfig | null): boolean;
+/**
+ * Open a persistent local bucket for asset dev serving.
+ *
+ * The Vite plugin opens one of these for the dev server's lifetime and reads
+ * the manifest and assets from it, rather than spinning up a Miniflare instance
+ * per request. The handle stays fresh across `bucket sync` runs (see
+ * {@link openLocalBucket}); the caller disposes it when the dev server stops.
+ */
+declare function openLocalAssetBucket(): Promise<LocalBucketSession>;
+/**
+ * Build the `<script>` that exposes the asset manifest on
+ * `self.__PLAYCADEMY_ASSET_MANIFEST`, read from the given local bucket.
+ *
+ * Byte-for-byte the same shape the edge worker injects in production (the
+ * stored manifest holds bare content keys; `base` is spliced in here), so
+ * `asset()` resolves identically in dev and on the platform. Returns `null`
+ * when the local bucket has no manifest yet (no `bucket sync` has run).
+ */
+declare function readLocalManifestScript(bucket: LocalBucket): Promise<string | null>;
+/** Bytes + content type for a served asset. */
+interface LocalAsset {
+    body: Uint8Array;
+    contentType: string;
+}
+/**
+ * Read an asset's bytes from the given local bucket by its serving path — the
+ * part after `/api/assets/` (e.g. `sprites/hero.a1b2c3d4.svg`). Mirrors the edge
+ * asset route: the request path maps to `${ASSET_PREFIX}${servingKey}` in R2.
+ * Returns `null` when the object isn't present.
+ */
+declare function readLocalAsset(bucket: LocalBucket, servingKey: string): Promise<LocalAsset | null>;
+
+export { ASSET_DEV_ROUTE_PREFIX, hasCustomAssetsRoute, openLocalAssetBucket, readLocalAsset, readLocalManifestScript };
+export type { LocalAsset, LocalBucket, LocalBucketSession };

package/dist/bucket.js

@@ -0,0 +1,341 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// ../utils/src/package-json.ts
+var init_package_json = __esm({
+  "../utils/src/package-json.ts"() {
+    "use strict";
+  }
+});
+
+// ../utils/src/file-loader.ts
+var init_file_loader = __esm({
+  "../utils/src/file-loader.ts"() {
+    "use strict";
+    init_package_json();
+  }
+});
+
+// src/lib/bucket/dev.ts
+import { existsSync } from "fs";
+import { join as join8 } from "path";
+
+// ../constants/src/timeback.ts
+var TIMEBACK_ROUTES = {
+  END_ACTIVITY: "/integrations/timeback/end-activity",
+  GET_XP: "/integrations/timeback/xp",
+  GET_MASTERY: "/integrations/timeback/mastery",
+  GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
+  HEARTBEAT: "/integrations/timeback/heartbeat",
+  ADVANCE_COURSE: "/integrations/timeback/advance-course",
+  UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
+};
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+};
+
+// ../constants/src/cloudflare.ts
+var CLOUDFLARE_COMPATIBILITY_DATE = "2025-10-11";
+
+// ../edge-play/src/constants.ts
+var ASSET_PREFIX = "_assets/";
+var MANIFEST_KEY = "_manifest.json";
+var ASSET_ROUTE_PREFIX = "/api/assets/";
+var ROUTES = {
+  /** Route index (lists available routes) */
+  INDEX: "/api",
+  /** Health check endpoint */
+  HEALTH: "/api/health",
+  /**
+   * Built-in content-addressable asset serving.
+   *
+   * Serves files from the game's BUCKET (R2) binding under their
+   * content-hashed keys, with immutable caching. Registered in the
+   * terminal tier so a game's own `server/api/assets/[...path].ts`
+   * route supersedes it.
+   */
+  ASSETS: `${ASSET_ROUTE_PREFIX}*`,
+  /** TimeBack integration routes */
+  TIMEBACK: {
+    END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
+    GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
+    GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
+    GET_HIGHEST_GRADE_MASTERED: `/api${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}`,
+    HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
+    ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`,
+    UNENROLL_COURSE: `/api${TIMEBACK_ROUTES.UNENROLL_COURSE}`
+  }
+};
+
+// src/lib/bundle/backend.ts
+import { join as join6 } from "node:path";
+
+// src/constants/api.ts
+import { join as join2 } from "node:path";
+
+// src/constants/server.ts
+import { join } from "node:path";
+var SERVER_ROOT_DIRECTORY = "server";
+var SERVER_LIB_DIRECTORY = join(SERVER_ROOT_DIRECTORY, "lib");
+
+// src/constants/api.ts
+var DEFAULT_API_ROUTES_DIRECTORY = join2(SERVER_ROOT_DIRECTORY, "api");
+
+// ../better-auth/package.json
+var package_default = {
+  name: "@playcademy/better-auth",
+  version: "0.0.17-beta.6",
+  type: "module",
+  exports: {
+    "./server": {
+      types: "./dist/server.d.ts",
+      import: "./dist/server.js",
+      require: "./dist/server.js"
+    },
+    "./client": {
+      types: "./dist/client.d.ts",
+      import: "./dist/client.js",
+      require: "./dist/client.js"
+    }
+  },
+  main: "dist/index.js",
+  module: "dist/index.js",
+  files: [
+    "dist"
+  ],
+  scripts: {
+    build: "bun build.ts"
+  },
+  dependencies: {
+    "@better-auth/utils": "^0.3.0",
+    "@better-fetch/fetch": "^1.1.18",
+    "@playcademy/sdk": "workspace:*",
+    "better-auth": "1.3.33",
+    "better-call": "^1.0.19"
+  },
+  devDependencies: {
+    "@inquirer/prompts": "^7.9.0",
+    "@playcademy/utils": "workspace:*",
+    "@types/bun": "1.3.5",
+    typescript: "^5.7.2"
+  },
+  peerDependencies: {
+    typescript: "^5"
+  }
+};
+
+// 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
+var CLOUDFLARE_BINDINGS = {
+  /** R2 bucket binding name */
+  BUCKET: "BUCKET",
+  /** KV namespace binding name */
+  KV: "KV",
+  /** D1 database binding name */
+  DB: "DB"
+};
+
+// src/constants/database.ts
+import { join as join3 } from "path";
+var DEFAULT_DATABASE_DIRECTORY = join3("server", "db");
+
+// src/constants/godot.ts
+import { join as join4 } from "node:path";
+var GODOT_BUILD_DIRECTORIES = {
+  /** Root build directory (cleared before each export) */
+  ROOT: "build",
+  /** Web export subdirectory */
+  WEB: join4("build", "web")
+};
+var GODOT_BUILD_OUTPUTS = {
+  /** Exported web build entry point */
+  INDEX_HTML: join4("build", "web", "index.html"),
+  /** Packaged zip file (created by Godot export) */
+  ZIP: join4("build", "web_playcademy.zip")
+};
+
+// src/constants/paths.ts
+import { homedir } from "node:os";
+import { join as join5 } 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")
+};
+var PLAYCADEMY_HOME = join5(homedir(), ".playcademy");
+var CLI_USER_DIRECTORIES = {
+  CONFIG: PLAYCADEMY_HOME,
+  BIN: join5(PLAYCADEMY_HOME, "bin"),
+  CACHE: join5(PLAYCADEMY_HOME, "cache")
+};
+var CLI_DEFAULT_OUTPUTS = {
+  WORKER_BUNDLE: join5(WORKSPACE_NAME, "worker-bundle.js")
+};
+
+// src/lib/core/client.ts
+import { PlaycademyClient } from "@playcademy/sdk/internal";
+
+// src/lib/core/context.ts
+var context = {};
+function getWorkspace() {
+  return context.workspace || process.cwd();
+}
+
+// src/lib/core/logger.ts
+import {
+  blue,
+  blueBright,
+  bold as bold2,
+  cyan,
+  dim as dim2,
+  gray,
+  green,
+  greenBright,
+  red,
+  underline,
+  yellow,
+  yellowBright
+} from "colorette";
+import { colorize } from "json-colorizer";
+
+// src/lib/core/error.ts
+import { bold, dim, redBright } from "colorette";
+import { ApiError, extractApiErrorInfo } from "@playcademy/sdk/internal";
+
+// src/lib/core/errors.ts
+import { ApiError as ApiError2 } from "@playcademy/sdk/internal";
+
+// ../utils/src/ansi.ts
+var isInteractive = typeof process !== "undefined" && process.stdout?.isTTY && !process.env.CI && process.env.TERM !== "dumb";
+
+// ../utils/src/spinner.ts
+var SPINNER_FRAMES = [
+  10251,
+  10265,
+  10297,
+  10296,
+  10300,
+  10292,
+  10278,
+  10279,
+  10247,
+  10255
+].map((code) => String.fromCodePoint(code));
+var CHECK_MARK = String.fromCodePoint(10004);
+var CROSS_MARK = String.fromCodePoint(10006);
+var CANCEL_MARK = String.fromCodePoint(9675);
+
+// ../utils/src/pure/index.ts
+init_package_json();
+
+// src/lib/secrets/env.ts
+init_file_loader();
+
+// src/lib/config/loader.ts
+init_file_loader();
+
+// ../utils/src/timeback.ts
+var TIMEBACK_DISCREPANCY_QUEUE_WINDOWS = [
+  "today",
+  "yesterday",
+  "this-week",
+  "last-week",
+  "all",
+  "custom"
+];
+var TIMEBACK_DISCREPANCY_QUEUE_METRICS = ["xp", "mastery", "time", "score"];
+var TIMEBACK_DISCREPANCY_QUEUE_WINDOW_VALUES = new Set(TIMEBACK_DISCREPANCY_QUEUE_WINDOWS);
+var TIMEBACK_DISCREPANCY_QUEUE_METRIC_VALUES = new Set(TIMEBACK_DISCREPANCY_QUEUE_METRICS);
+
+// src/lib/core/import.ts
+import * as esbuild from "esbuild";
+
+// src/lib/core/transpile.ts
+import * as esbuild2 from "esbuild";
+
+// src/lib/bundle/backend.ts
+function getCustomRoutesDirectory(projectPath, config) {
+  const customRoutes = config?.integrations?.customRoutes;
+  const customRoutesDir = typeof customRoutes === "object" && customRoutes.directory || DEFAULT_API_ROUTES_DIRECTORY;
+  return join6(projectPath, customRoutesDir);
+}
+
+// src/lib/bucket/local.ts
+import { join as join7 } from "path";
+import { Miniflare } from "miniflare";
+async function openLocalBucket() {
+  const bucketDir = join7(getWorkspace(), CLI_DIRECTORIES.BUCKET);
+  const mf = new Miniflare({
+    modules: [{ type: "ESModule", path: "index.mjs", contents: "" }],
+    r2Buckets: [CLOUDFLARE_BINDINGS.BUCKET],
+    r2Persist: bucketDir,
+    compatibilityDate: CLOUDFLARE_COMPATIBILITY_DATE
+  });
+  return {
+    bucket: await mf.getR2Bucket(CLOUDFLARE_BINDINGS.BUCKET),
+    dispose: () => mf.dispose()
+  };
+}
+
+// src/lib/bucket/dev.ts
+var ASSET_DEV_ROUTE_PREFIX = ASSET_ROUTE_PREFIX;
+function hasCustomAssetsRoute(projectRoot, config) {
+  const routesDir = getCustomRoutesDirectory(projectRoot, config);
+  return existsSync(join8(routesDir, "assets")) || existsSync(join8(routesDir, "assets.ts"));
+}
+function openLocalAssetBucket() {
+  return openLocalBucket();
+}
+async function readLocalManifestScript(bucket) {
+  const object = await bucket.get(`${ASSET_PREFIX}${MANIFEST_KEY}`);
+  if (!object) {
+    return null;
+  }
+  const manifest = await object.text();
+  const payload = `Object.assign({base:${JSON.stringify(ASSET_ROUTE_PREFIX)}},${manifest})`;
+  return `<script>self.__PLAYCADEMY_ASSET_MANIFEST=${payload}</script>`;
+}
+async function readLocalAsset(bucket, servingKey) {
+  const object = await bucket.get(`${ASSET_PREFIX}${servingKey}`);
+  if (!object) {
+    return null;
+  }
+  const body = new Uint8Array(await object.arrayBuffer());
+  const contentType = object.httpMetadata?.contentType ?? "application/octet-stream";
+  return { body, contentType };
+}
+export {
+  ASSET_DEV_ROUTE_PREFIX,
+  hasCustomAssetsRoute,
+  openLocalAssetBucket,
+  readLocalAsset,
+  readLocalManifestScript
+};