create-planet 1.0.0

package/template/schema.sql

@@ -0,0 +1,22 @@
+-- Travel Plans Table: Tracks all journeys (active and historical)
+CREATE TABLE IF NOT EXISTS travel_plans (
+    id TEXT PRIMARY KEY,
+    ship_id TEXT NOT NULL,
+    origin_url TEXT NOT NULL,
+    destination_url TEXT NOT NULL,
+    start_timestamp INTEGER NOT NULL,
+    end_timestamp INTEGER NOT NULL,
+    status TEXT CHECK(status IN ('PREPARING', 'PLAN_ACCEPTED')) NOT NULL DEFAULT 'PREPARING',
+    signatures TEXT NOT NULL -- JSON array of cryptographic signatures
+);
+
+-- Index for fast retrieval of active plans (not yet arrived)
+CREATE INDEX IF NOT EXISTS idx_travel_plans_active ON travel_plans (end_timestamp, origin_url, destination_url);
+
+-- Traffic Controllers Cache: Known neighbors with space ports
+CREATE TABLE IF NOT EXISTS traffic_controllers (
+    planet_url TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    space_port_url TEXT NOT NULL,
+    last_manifest_fetch INTEGER NOT NULL
+);

package/template/scripts/inject-do-exports.js

@@ -0,0 +1,61 @@
+/**
+ * Post-build script that patches dist/server/entry.mjs to export Durable Object
+ * classes required by Cloudflare Workers. Astro's build doesn't re-export these
+ * from the entrypoint, causing "Worker depends on Durable Objects not exported
+ * in entrypoint" errors.
+ */
+import { readFileSync, writeFileSync, readdirSync } from "fs";
+import { join } from "path";
+
+const serverDir = "dist/server";
+const chunksDir = join(serverDir, "chunks");
+const entryFile = join(serverDir, "entry.mjs");
+
+// Map of DO class names to search for in chunks
+const durableObjects = ["TrafficControl"];
+
+for (const className of durableObjects) {
+  // Find the chunk containing this DO class
+  const chunks = readdirSync(chunksDir);
+  let targetChunk = null;
+
+  for (const chunk of chunks) {
+    if (!chunk.endsWith(".mjs")) continue;
+    const content = readFileSync(join(chunksDir, chunk), "utf-8");
+    if (content.includes(`class ${className} extends DurableObject`)) {
+      targetChunk = chunk;
+      break;
+    }
+  }
+
+  if (!targetChunk) {
+    console.error(
+      `[inject-do-exports] Could not find ${className} in any chunk`,
+    );
+    process.exit(1);
+  }
+
+  // Add named export to the chunk file
+  const chunkPath = join(chunksDir, targetChunk);
+  let chunkContent = readFileSync(chunkPath, "utf-8");
+  if (!chunkContent.includes(`export { ${className}`)) {
+    chunkContent = chunkContent.replace(
+      /export \{\s*page\s*\};/,
+      `export {\n  page,\n  ${className}\n};`,
+    );
+    writeFileSync(chunkPath, chunkContent);
+    console.log(
+      `[inject-do-exports] Exported ${className} from chunks/${targetChunk}`,
+    );
+  }
+
+  // Re-export from entry.mjs
+  let entryContent = readFileSync(entryFile, "utf-8");
+  if (!entryContent.includes(className)) {
+    entryContent += `export { ${className} } from './chunks/${targetChunk}';\n`;
+    writeFileSync(entryFile, entryContent);
+    console.log(`[inject-do-exports] Re-exported ${className} in entry.mjs`);
+  }
+}
+
+console.log("[inject-do-exports] Done");

package/template/scripts/simulate-universe.js

@@ -0,0 +1,158 @@
+import { spawn, execSync } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const NUM_PLANETS = 10;
+const BASE_PORT = 3000;
+const BASE_INSPECTOR_PORT = 19229;
+const OPEN_BROWSER = process.argv.includes("--open");
+
+const allPlanets = Array.from({ length: NUM_PLANETS }, (_, i) => ({
+  name: `Towel ${i + 1}`,
+  url: `http://towel-${i + 1}.localhost:${BASE_PORT + i}`,
+  port: BASE_PORT + i,
+  id: i + 1,
+}));
+
+const processes = [];
+
+const cleanup = () => {
+  console.log("Cleaning up existing processes...");
+  processes.forEach((p) => {
+    try {
+      p.kill();
+    } catch (e) {}
+  });
+  try {
+    execSync("pkill -f 'wrangler dev' || true");
+  } catch (e) {}
+};
+
+const startPlanet = (planet) => {
+  const { id, name, url, port } = planet;
+  const inspectorPort = BASE_INSPECTOR_PORT + id;
+
+  // Initialize Database first
+  console.log(`[${name}] Initializing database...`);
+  execSync(
+    `npx wrangler d1 execute planet_db --file=schema.sql -c wrangler.dev.jsonc --local --persist-to=.wrangler/state/planet-${id}`,
+    {
+      cwd: path.join(__dirname, ".."),
+      stdio: "inherit",
+    },
+  );
+
+  const env = {
+    ...process.env,
+    PUBLIC_SIM_PLANET_NAME: name,
+    PUBLIC_SIM_LANDING_SITE: url,
+    PUBLIC_SIM_WARP_LINKS: JSON.stringify(
+      allPlanets
+        .filter((p) => p.url !== url)
+        .sort(() => 0.5 - Math.random())
+        .slice(0, 5)
+        .map((n) => ({ name: n.name, url: n.url })),
+    ),
+  };
+
+  const child = spawn(
+    "npx",
+    [
+      "wrangler",
+      "dev",
+      "--port",
+      port,
+      "--ip",
+      "0.0.0.0",
+      "--inspector-port",
+      inspectorPort,
+      "-c",
+      "wrangler.dev.jsonc",
+      "--persist-to",
+      `.wrangler/state/planet-${id}`,
+      "--var",
+      `PUBLIC_SIM_PLANET_NAME:"${name}"`,
+      "--var",
+      `PUBLIC_SIM_LANDING_SITE:"${url}"`,
+      "--var",
+      `PUBLIC_SIM_WARP_LINKS:'${env.PUBLIC_SIM_WARP_LINKS}'`,
+    ],
+    {
+      cwd: path.join(__dirname, ".."),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+    },
+  );
+
+  processes.push(child);
+
+  return new Promise((resolve, reject) => {
+    let isReady = false;
+    const timeout = setTimeout(() => {
+      if (!isReady)
+        reject(new Error(`[${name}] Timed out waiting for readiness`));
+    }, 30000);
+
+    const handleData = (data) => {
+      const str = data.toString();
+      process.stdout.write(`[${name}] ${str}`);
+      if (str.includes("Ready on")) {
+        isReady = true;
+        clearTimeout(timeout);
+        resolve();
+      }
+    };
+
+    child.stdout.on("data", handleData);
+    child.stderr.on("data", handleData);
+    child.on("error", reject);
+  });
+};
+
+const run = async () => {
+  try {
+    cleanup();
+    console.log("Building project for wrangler...");
+    execSync("npm run build", {
+      cwd: path.join(__dirname, ".."),
+      stdio: "inherit",
+    });
+
+    console.log(
+      `--- SIMULATING FEDERATED UNIVERSE (${NUM_PLANETS} PLANETS) ---`,
+    );
+
+    // Start planets sequentially to avoid overwhelming the system, but wait for readiness
+    for (const planet of allPlanets) {
+      await startPlanet(planet);
+    }
+
+    if (OPEN_BROWSER) {
+      console.log("All planets are ready! Opening browser windows...");
+      const urlsToOpen = [
+        allPlanets[0].url, // First planet landing site
+        ...allPlanets.map((p) => `${p.url}/control`), // All planets control centers
+      ];
+      const urls = urlsToOpen.join(" ");
+      // On macOS, 'open' with multiple URLs opens them in tabs
+      execSync(`open ${urls}`);
+    } else {
+      console.log(`All planets are ready! (pass --open to launch browser)`);
+      allPlanets.forEach((p) => console.log(`  ${p.name}: ${p.url}`));
+    }
+
+    console.log("Simulation running. Press Ctrl+C to stop.");
+  } catch (e) {
+    console.error("Simulation failed to start:", e.message);
+    cleanup();
+    process.exit(1);
+  }
+};
+
+process.on("SIGINT", cleanup);
+process.on("SIGTERM", cleanup);
+
+run();

package/template/src/env.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="astro/client" />
+
+interface ImportMetaEnv {
+  readonly KV: import("@cloudflare/workers-types").KVNamespace;
+  readonly DB: import("@cloudflare/workers-types").D1Database;
+  readonly TRAFFIC_CONTROL: import("@cloudflare/workers-types").DurableObjectNamespace;
+  readonly PUBLIC_SIM_PLANET_NAME?: string;
+  readonly PUBLIC_SIM_PLANET_DESCRIPTION?: string;
+  readonly PUBLIC_SIM_LANDING_SITE?: string;
+  readonly PUBLIC_SIM_WARP_LINKS?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+type Runtime = import("@astrojs/cloudflare").Runtime<ImportMetaEnv>;
+
+declare namespace App {
+  interface Locals extends Runtime {}
+}

package/template/src/lib/config.ts

@@ -0,0 +1,52 @@
+// Baked in at scaffold time by `npm create planet`
+export const PLANET_NAME = "Towel 42 Space Outpost";
+export const PLANET_DESCRIPTION =
+  "A remote outpost in the Federated Planets. A quiet spot for deep-space weary travelers. Don't panic, but bring a towel.";
+
+export const DEFAULT_WARP_LINKS = [
+  {
+    name: "Federation Prime",
+    url: "https://prime.federatedplanets.com/",
+  },
+  { name: "Waystation Meridian", url: "https://waystation.federatedplanets.com/" },
+  { name: "The Interchange", url: "https://interchange.federatedplanets.com/" },
+  { name: "Port Cassini", url: "https://port-cassini.federatedplanets.com/" },
+  { name: "Terminus Reach", url: "https://terminus.federatedplanets.com/" },
+  { name: "Driftyard Seven", url: "https://driftyard.federatedplanets.com/" },
+  { name: "Towel 42 Space Outpost", url: "https://towel-42.federatedplanets.com/" },
+  { name: "Explorers Outpost", url: "https://www.nasa.gov/" },
+];
+
+import { env as cloudflareEnv } from "cloudflare:workers";
+
+// Robust helper to get simulation variables from any available environment source
+const getSimVar = (name: string): string | undefined => {
+  // 1. Check Cloudflare env object (for wrangler dev --var)
+  const env = cloudflareEnv as any;
+  if (env && env[name]) return env[name];
+
+  // 2. Check process.env (traditional node/dev env)
+  if (typeof process !== "undefined" && process.env && process.env[name])
+    return process.env[name];
+
+  // 3. Check import.meta.env (build-time or astro-provided)
+  if (import.meta.env && import.meta.env[name]) return import.meta.env[name];
+
+  return undefined;
+};
+
+export const getWarpLinks = () => {
+  const landingSite = getSimVar("PUBLIC_SIM_LANDING_SITE")?.replace(/\/$/, "");
+  try {
+    const simLinks = getSimVar("PUBLIC_SIM_WARP_LINKS");
+    if (simLinks) {
+      return JSON.parse(simLinks);
+    }
+  } catch (e) {}
+  if (!landingSite) return DEFAULT_WARP_LINKS;
+  return DEFAULT_WARP_LINKS.filter(
+    (l) => l.url.replace(/\/$/, "") !== landingSite,
+  );
+};
+
+export const WARP_LINKS = getWarpLinks();

package/template/src/lib/consensus.ts

@@ -0,0 +1,127 @@
+import { CryptoCore } from "./crypto";
+import type { PlanetManifest } from "./travel";
+import { env as cloudflareEnv } from "cloudflare:workers";
+import { PLANET_NAME } from "./config";
+
+// Robust helper to get simulation variables from any available environment source
+const getSimVar = (name: string): string | undefined => {
+  // 1. Check Cloudflare env object (for wrangler dev --var)
+  const env = cloudflareEnv as any;
+  if (env && env[name]) return env[name];
+
+  // 2. Check process.env (traditional node/dev env)
+  if (
+    typeof process !== "undefined" &&
+    process.env &&
+    (process.env as any)[name]
+  )
+    return (process.env as any)[name];
+
+  // 3. Check import.meta.env (build-time or astro-provided)
+  if (import.meta.env && (import.meta.env as any)[name])
+    return (import.meta.env as any)[name];
+
+  return undefined;
+};
+
+export interface TravelPlan {
+  id: string;
+  ship_id: string;
+  origin_url: string;
+  destination_url: string;
+  start_timestamp: number;
+  end_timestamp: number;
+  status: "PREPARING" | "PLAN_ACCEPTED";
+  traffic_controllers: string[]; // List of landing site URLs elected
+  signatures: Record<string, string>; // planet_url -> signature
+}
+
+export class ConsensusEngine {
+  /**
+   * Broadcasts a message to all elected Traffic Controllers
+   */
+  static async broadcast(
+    plan: TravelPlan,
+    action: "prepare" | "commit",
+    controllers: PlanetManifest[],
+  ) {
+    const localName = getSimVar("PUBLIC_SIM_PLANET_NAME") || PLANET_NAME;
+    console.log(
+      `[${localName}] Broadcasting ${action} for plan ${plan.id} to ${controllers.length} controllers`,
+    );
+
+    const promises = controllers.map(async (tc) => {
+      if (!tc.space_port) {
+        console.warn(
+          `[${localName}] Skipping broadcast to ${tc.landing_site}: No space_port found in manifest`,
+        );
+        return;
+      }
+      try {
+        const localUrl =
+          getSimVar("PUBLIC_SIM_LANDING_SITE") || "http://unknown";
+        console.log(`[${localName}] Sending ${action} to ${tc.space_port}...`);
+        const res = await fetch(`${tc.space_port}?action=${action}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Planet-Origin": localUrl,
+          },
+          body: JSON.stringify(plan),
+        });
+        if (!res.ok) {
+          console.error(
+            `[${localName}] Broadcast ${action} to ${tc.landing_site} failed: ${res.status} ${await res.text()}`,
+          );
+        } else {
+          console.log(
+            `[${localName}] Broadcast ${action} to ${tc.landing_site} succeeded`,
+          );
+        }
+      } catch (e: any) {
+        console.error(
+          `[${localName}] Failed to broadcast ${action} to ${tc.landing_site}:`,
+          e.message,
+        );
+      }
+    });
+    return Promise.all(promises);
+  }
+
+  /**
+   * Checks if we have enough signatures for consensus
+   * N = 3f + 1, we need 2f + 1 signatures
+   */
+  static hasQuorum(plan: TravelPlan): boolean {
+    const localName = getSimVar("PUBLIC_SIM_PLANET_NAME") || PLANET_NAME;
+    const n = plan.traffic_controllers.length;
+    const f = Math.floor((n - 1) / 3);
+    const required = 2 * f + 1;
+    const current = Object.keys(plan.signatures).length;
+
+    console.log(
+      `[${localName}] Quorum check for plan ${plan.id}: ${current}/${required} signatures (N=${n}, f=${f})`,
+    );
+    return current >= required;
+  }
+
+  /**
+   * Saves plan state to KV for active consensus tracking
+   */
+  static async savePlanState(KV: KVNamespace, plan: TravelPlan) {
+    await KV.put(`consensus_plan_${plan.id}`, JSON.stringify(plan), {
+      expirationTtl: 3600,
+    });
+  }
+
+  /**
+   * Retrieves plan state from KV
+   */
+  static async getPlanState(
+    KV: KVNamespace,
+    planId: string,
+  ): Promise<TravelPlan | null> {
+    const data = await KV.get(`consensus_plan_${planId}`);
+    return data ? JSON.parse(data) : null;
+  }
+}

package/template/src/lib/crypto.ts

@@ -0,0 +1,89 @@
+/**
+ * Cryptography Utility for Space Travel Protocol
+ * Uses Web Crypto API (Ed25519) for signing and verification.
+ */
+
+export class CryptoCore {
+  private static KEY_ALGO = {
+    name: "Ed25519",
+  };
+
+  /**
+   * Generates a new Ed25519 KeyPair
+   */
+  static async generateKeyPair(): Promise<CryptoKeyPair> {
+    return (await crypto.subtle.generateKey(this.KEY_ALGO, true, [
+      "sign",
+      "verify",
+    ])) as CryptoKeyPair;
+  }
+
+  /**
+   * Exports a key to Base64 format
+   */
+  static async exportKey(key: CryptoKey): Promise<string> {
+    const exported = await crypto.subtle.exportKey(
+      key.type === "public" ? "spki" : "pkcs8",
+      key,
+    );
+    return btoa(String.fromCharCode(...new Uint8Array(exported)));
+  }
+
+  /**
+   * Imports a key from Base64 format
+   */
+  static async importKey(
+    base64Key: string,
+    type: "public" | "private",
+  ): Promise<CryptoKey> {
+    const binary = atob(base64Key);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+
+    return await crypto.subtle.importKey(
+      type === "public" ? "spki" : "pkcs8",
+      bytes,
+      this.KEY_ALGO,
+      true,
+      type === "public" ? ["verify"] : ["sign"],
+    );
+  }
+
+  /**
+   * Signs data string using a private key
+   */
+  static async sign(data: string, privateKey: CryptoKey): Promise<string> {
+    const encoder = new TextEncoder();
+    const signature = await crypto.subtle.sign(
+      this.KEY_ALGO,
+      privateKey,
+      encoder.encode(data),
+    );
+    return btoa(String.fromCharCode(...new Uint8Array(signature)));
+  }
+
+  /**
+   * Verifies signature for data string using a public key
+   */
+  static async verify(
+    data: string,
+    signatureBase64: string,
+    publicKey: CryptoKey,
+  ): Promise<boolean> {
+    const encoder = new TextEncoder();
+    const signatureBinary = atob(signatureBase64);
+    const signatureBytes = new Uint8Array(signatureBinary.length);
+    for (let i = 0; i < signatureBinary.length; i++) {
+      signatureBytes[i] = signatureBinary.charCodeAt(i);
+    }
+
+    return await crypto.subtle.verify(
+      this.KEY_ALGO,
+      publicKey,
+      signatureBytes,
+      encoder.encode(data),
+    );
+  }
+}

package/template/src/lib/identity.ts

@@ -0,0 +1,35 @@
+import { CryptoCore } from "./crypto";
+
+export class PlanetIdentity {
+  /**
+   * Retrieves or generates the planet's Ed25519 identity keys from KV.
+   */
+  static async getIdentity(KV: KVNamespace): Promise<{
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+    publicKeyBase64: string;
+  }> {
+    const existingPublic = await KV.get("identity_public");
+    const existingPrivate = await KV.get("identity_private");
+
+    if (existingPublic && existingPrivate) {
+      const publicKey = await CryptoCore.importKey(existingPublic, "public");
+      const privateKey = await CryptoCore.importKey(existingPrivate, "private");
+      return { publicKey, privateKey, publicKeyBase64: existingPublic };
+    }
+
+    // Generate new if not found
+    const keyPair = await CryptoCore.generateKeyPair();
+    const publicB64 = await CryptoCore.exportKey(keyPair.publicKey);
+    const privateB64 = await CryptoCore.exportKey(keyPair.privateKey);
+
+    await KV.put("identity_public", publicB64);
+    await KV.put("identity_private", privateB64);
+
+    return {
+      publicKey: keyPair.publicKey,
+      privateKey: keyPair.privateKey,
+      publicKeyBase64: publicB64,
+    };
+  }
+}

package/template/src/lib/travel.ts

@@ -0,0 +1,75 @@
+/**
+ * Travel Logic for Federated Planets
+ * Handles distance, time, and controller election.
+ */
+import md5 from "md5";
+
+export interface Coordinates {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface PlanetManifest {
+  name: string;
+  landing_site: string;
+  space_port?: string;
+}
+
+export class TravelCalculator {
+  /**
+   * Calculates 3D coordinates from a URL deterministically
+   */
+  static calculateCoordinates(url: string): Coordinates {
+    const domain = new URL(url).hostname.toLowerCase();
+    const hash = md5(domain);
+
+    const xHex = hash.slice(0, 6);
+    const yHex = hash.slice(6, 12);
+    const zHex = hash.slice(12, 18);
+
+    const x = (parseInt(xHex, 16) % 100000) / 100;
+    const y = (parseInt(yHex, 16) % 100000) / 100;
+    const z = (parseInt(zHex, 16) % 100000) / 100;
+
+    return { x, y, z };
+  }
+
+  /**
+   * Calculates 3D Euclidean distance between two points
+   */
+  static calculateDistance(p1: Coordinates, p2: Coordinates): number {
+    return Math.sqrt(
+      Math.pow(p2.x - p1.x, 2) +
+        Math.pow(p2.y - p1.y, 2) +
+        Math.pow(p2.z - p1.z, 2),
+    );
+  }
+
+  /**
+   * Calculates travel time in Earth hours (Flight-Years)
+   * 1 FY per 100 sparsecs.
+   */
+  static calculateTravelTime(distance: number): number {
+    return distance / 100;
+  }
+
+  /**
+   * Elects Traffic Controllers based on proximity sortition
+   */
+  static electControllers(
+    seed: string,
+    eligibleNeighbors: PlanetManifest[],
+    n: number = 4, // Default 3f + 1 where f=1
+  ): PlanetManifest[] {
+    const scored = eligibleNeighbors.map((neighbor) => {
+      const score = md5(seed + neighbor.landing_site);
+      return { neighbor, score };
+    });
+
+    // Deterministic sort by score
+    scored.sort((a, b) => a.score.localeCompare(b.score));
+
+    return scored.slice(0, n).map((s) => s.neighbor);
+  }
+}

package/template/src/pages/api/v1/control-ws.ts

@@ -0,0 +1,22 @@
+import type { APIRoute } from "astro";
+import { env } from "cloudflare:workers";
+import TrafficControl from "../../../traffic-control";
+export { TrafficControl };
+
+export const GET: APIRoute = async ({ request }) => {
+  const { TRAFFIC_CONTROL } = env as any;
+
+  if (!TRAFFIC_CONTROL) {
+    return new Response("Durable Object binding not found", { status: 500 });
+  }
+
+  const isWebSocket = request.headers.get("Upgrade") === "websocket";
+  const id = TRAFFIC_CONTROL.idFromName("global");
+  const obj = TRAFFIC_CONTROL.get(id);
+
+  try {
+    return await obj.fetch(request);
+  } catch (e: any) {
+    return new Response(`DO fetch error: ${e.message}`, { status: 500 });
+  }
+};