@campfiire/spark-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import prompts from "prompts";
+import ora from "ora";
+import kleur from "kleur";
+function findTemplatesDir() {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  let dir = currentDir;
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+      if (pkg.name === "@campfiire/spark-cli") {
+        return path.join(dir, "templates", "default");
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error("Could not locate spark-cli templates directory");
+}
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function slugify(text) {
+  return text.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function initCommand(nameArg) {
+  const TEMPLATES_DIR = findTemplatesDir();
+  console.log(kleur.bold().cyan("\n\u{1F525} Campfire Spark \u2014 init\n"));
+  const responses = await prompts([
+    {
+      type: "text",
+      name: "name",
+      message: "Spark name",
+      initial: nameArg ?? "my-spark",
+      validate: (v) => v.length >= 3 || "Name must be at least 3 characters"
+    },
+    {
+      type: "text",
+      name: "description",
+      message: "Short description",
+      initial: "A custom spark for Campfire"
+    },
+    {
+      type: "text",
+      name: "author",
+      message: "Author (email or username)"
+    },
+    {
+      type: "text",
+      name: "icon",
+      message: "Icon name (Tabler icon, e.g. IconFlame)",
+      initial: "IconSparkles"
+    }
+  ]);
+  if (!responses.name) {
+    console.log(kleur.yellow("Aborted."));
+    return;
+  }
+  const projectDir = path.resolve(process.cwd(), slugify(responses.name));
+  if (fs.existsSync(projectDir)) {
+    console.error(kleur.red(`Directory already exists: ${projectDir}`));
+    process.exit(1);
+  }
+  const spinner = ora("Creating spark project...").start();
+  try {
+    copyDir(TEMPLATES_DIR, projectDir);
+    const manifestPath = path.join(projectDir, "manifest.json");
+    const manifestContent = fs.readFileSync(manifestPath, "utf-8");
+    const manifest = JSON.parse(manifestContent);
+    manifest.slug = slugify(responses.name);
+    manifest.name = responses.name;
+    manifest.description = responses.description;
+    manifest.author = responses.author;
+    manifest.icon = responses.icon;
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    const pkgPath = path.join(projectDir, "package.json");
+    const pkgContent = fs.readFileSync(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+    pkg.name = slugify(responses.name);
+    pkg.description = responses.description;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+    spinner.succeed(`Created ${kleur.cyan(projectDir)}`);
+    console.log(kleur.bold("\nNext steps:"));
+    console.log(`  ${kleur.cyan(`cd ${path.basename(projectDir)}`)}`);
+    console.log(`  ${kleur.cyan("npm install")}  ${kleur.dim("# or yarn / pnpm")}`);
+    console.log(`  ${kleur.cyan("campfire-spark dev")}  ${kleur.dim("# start local dev server")}`);
+    console.log();
+  } catch (err) {
+    spinner.fail(`Failed to create project: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/commands/build.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import { build } from "vite";
+import react from "@vitejs/plugin-react";
+import ora2 from "ora";
+import kleur2 from "kleur";
+
+// src/lib/manifest.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { customSparkManifestSchema } from "@campfiire/shared";
+function readManifest(projectDir = process.cwd()) {
+  const manifestPath = path2.join(projectDir, "manifest.json");
+  if (!fs2.existsSync(manifestPath)) {
+    throw new Error(`manifest.json not found in ${projectDir}`);
+  }
+  const content = fs2.readFileSync(manifestPath, "utf-8");
+  const parsed = JSON.parse(content);
+  return customSparkManifestSchema.parse(parsed);
+}
+
+// src/commands/build.ts
+import { getSparkTier, SPARK_BUNDLE_TIERS } from "@campfiire/shared";
+async function buildCommand() {
+  const spinner = ora2("Reading manifest...").start();
+  try {
+    const manifest = readManifest();
+    spinner.text = `Building ${kleur2.cyan(manifest.name)} v${manifest.version}...`;
+    const projectDir = process.cwd();
+    const distDir = path3.join(projectDir, "dist");
+    if (fs3.existsSync(distDir)) {
+      fs3.rmSync(distDir, { recursive: true, force: true });
+    }
+    await build({
+      root: projectDir,
+      plugins: [react()],
+      build: {
+        outDir: "dist",
+        emptyOutDir: true,
+        lib: {
+          entry: path3.resolve(projectDir, "src/index.tsx"),
+          formats: ["iife"],
+          name: "CampfireSpark",
+          fileName: () => "bundle.js"
+        },
+        rollupOptions: {
+          external: ["react", "react-dom", "framer-motion", "@react-spring/web", "@campfiire/spark-sdk"],
+          output: {
+            globals: {
+              react: "CampfireRuntime.React",
+              "react-dom": "CampfireRuntime.ReactDOM",
+              "framer-motion": "CampfireRuntime.FramerMotion",
+              "@react-spring/web": "CampfireRuntime.ReactSpring",
+              "@campfiire/spark-sdk": "CampfireRuntime.SparkSDK"
+            }
+          }
+        },
+        minify: "esbuild",
+        sourcemap: false
+      },
+      logLevel: "warn"
+    });
+    fs3.writeFileSync(
+      path3.join(distDir, "manifest.json"),
+      JSON.stringify(manifest, null, 2)
+    );
+    const bundlePath = path3.join(distDir, "bundle.js");
+    const stats = fs3.statSync(bundlePath);
+    const tier = getSparkTier(stats.size);
+    if (!tier) {
+      spinner.fail(
+        `Bundle too large: ${(stats.size / 1024).toFixed(1)}KB (max ${SPARK_BUNDLE_TIERS.heavy.maxSize / 1024}KB)`
+      );
+      process.exit(1);
+    }
+    const tierInfo = SPARK_BUNDLE_TIERS[tier];
+    spinner.succeed(
+      `Built ${kleur2.cyan(manifest.name)} (${(stats.size / 1024).toFixed(1)}KB, ${kleur2.green(tierInfo.label)} tier)`
+    );
+    console.log(kleur2.bold("\nOutput:"));
+    console.log(`  ${kleur2.cyan("dist/bundle.js")}       ${kleur2.dim(`(${(stats.size / 1024).toFixed(1)}KB)`)}`);
+    console.log(`  ${kleur2.cyan("dist/manifest.json")}`);
+    console.log(kleur2.bold("\nNext step:"));
+    console.log(`  ${kleur2.cyan("campfire-spark submit")}  ${kleur2.dim("# upload for review")}`);
+    console.log();
+  } catch (err) {
+    spinner.fail(`Build failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/commands/dev.ts
+import * as path4 from "path";
+import { createServer } from "vite";
+import react2 from "@vitejs/plugin-react";
+import kleur3 from "kleur";
+async function devCommand(options) {
+  try {
+    const manifest = readManifest();
+    const port = parseInt(options.port ?? "4321", 10);
+    const projectDir = process.cwd();
+    console.log(kleur3.bold().cyan(`
+\u{1F525} Campfire Spark \u2014 dev
+`));
+    console.log(`  Spark: ${kleur3.cyan(manifest.name)} v${manifest.version}`);
+    console.log(`  Port:  ${kleur3.cyan(String(port))}
+`);
+    const server = await createServer({
+      root: projectDir,
+      plugins: [react2()],
+      server: {
+        port,
+        open: true
+      },
+      resolve: {
+        alias: {
+          "@campfiire/spark-sdk/mock": path4.resolve(
+            new URL(".", import.meta.url).pathname,
+            "../lib/mock-sdk.ts"
+          )
+        }
+      },
+      define: {
+        __SPARK_MANIFEST__: JSON.stringify(manifest)
+      }
+    });
+    await server.listen();
+    server.printUrls();
+  } catch (err) {
+    console.error(kleur3.red(`Dev server failed: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// src/commands/login.ts
+import * as http from "http";
+import open from "open";
+import ora3 from "ora";
+import kleur4 from "kleur";
+
+// src/lib/config.ts
+import * as fs4 from "fs";
+import * as path5 from "path";
+import * as os from "os";
+var CONFIG_DIR = path5.join(os.homedir(), ".campfire");
+var CREDENTIALS_FILE = path5.join(CONFIG_DIR, "credentials.json");
+function readCredentials() {
+  try {
+    if (!fs4.existsSync(CREDENTIALS_FILE)) return null;
+    const content = fs4.readFileSync(CREDENTIALS_FILE, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function writeCredentials(credentials) {
+  if (!fs4.existsSync(CONFIG_DIR)) {
+    fs4.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  }
+  fs4.writeFileSync(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2), { mode: 384 });
+}
+function requireAuth() {
+  const creds = readCredentials();
+  if (!creds) {
+    console.error("Not logged in. Run 'campfire-spark login' first.");
+    process.exit(1);
+  }
+  return creds;
+}
+
+// src/commands/login.ts
+async function loginCommand(options) {
+  const apiUrl = options.apiUrl ?? "http://localhost:3000";
+  console.log(kleur4.bold().cyan("\n\u{1F525} Campfire Spark \u2014 login\n"));
+  const callbackPort = 4320 + Math.floor(Math.random() * 100);
+  const callbackUrl = `http://localhost:${callbackPort}/callback`;
+  const spinner = ora3("Initiating authorization...").start();
+  try {
+    const initRes = await fetch(`${apiUrl}/api/cli-auth/initiate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ callbackUrl })
+    });
+    if (!initRes.ok) {
+      const body = await initRes.json().catch(() => ({}));
+      spinner.fail(`Failed to initiate: ${body.error ?? initRes.statusText}`);
+      process.exit(1);
+    }
+    const { authorizeUrl } = await initRes.json();
+    spinner.text = `Opening browser... (callback port: ${callbackPort})`;
+    const tokenPromise = new Promise(
+      (resolve4, reject) => {
+        const server = http.createServer((req, res) => {
+          if (req.url?.startsWith("/callback")) {
+            const url = new URL(req.url, `http://localhost:${callbackPort}`);
+            const token2 = url.searchParams.get("token");
+            const userId2 = url.searchParams.get("userId");
+            const email2 = url.searchParams.get("email");
+            if (!token2 || !userId2 || !email2) {
+              res.writeHead(400);
+              res.end("Missing parameters");
+              reject(new Error("Missing token, userId, or email in callback"));
+              return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<!DOCTYPE html>
+<html>
+  <head>
+    <title>Logged in!</title>
+    <style>
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+        background: #0a0a0a;
+        color: #fff;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100vh;
+        margin: 0;
+      }
+      .card {
+        text-align: center;
+        padding: 48px;
+        border-radius: 12px;
+        background: #18181b;
+        border: 1px solid #27272a;
+      }
+      h1 { margin: 0 0 8px; }
+      p { margin: 0; color: #a1a1aa; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>\u2705 Logged in!</h1>
+      <p>You can close this window and return to your terminal.</p>
+    </div>
+  </body>
+</html>`);
+            server.close();
+            resolve4({ token: token2, userId: userId2, email: email2 });
+          }
+        });
+        server.listen(callbackPort, () => {
+          open(authorizeUrl).catch(() => {
+            console.log(`
+Open this URL manually: ${kleur4.cyan(authorizeUrl)}`);
+          });
+        });
+        setTimeout(() => {
+          server.close();
+          reject(new Error("Login timed out after 10 minutes"));
+        }, 10 * 60 * 1e3);
+      }
+    );
+    const { token, userId, email } = await tokenPromise;
+    writeCredentials({ token, userId, email, apiUrl });
+    spinner.succeed(`Logged in as ${kleur4.cyan(email)}`);
+    console.log(kleur4.dim("\n  Token stored in ~/.campfire/credentials.json"));
+    console.log();
+  } catch (err) {
+    spinner.fail(`Login failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/commands/submit.ts
+import * as fs5 from "fs";
+import * as path6 from "path";
+import ora4 from "ora";
+import kleur5 from "kleur";
+async function submitCommand() {
+  const creds = requireAuth();
+  console.log(kleur5.bold().cyan("\n\u{1F525} Campfire Spark \u2014 submit\n"));
+  const projectDir = process.cwd();
+  const distDir = path6.join(projectDir, "dist");
+  const bundlePath = path6.join(distDir, "bundle.js");
+  const manifestPath = path6.join(distDir, "manifest.json");
+  if (!fs5.existsSync(bundlePath) || !fs5.existsSync(manifestPath)) {
+    console.error(kleur5.red("No build found. Run 'campfire-spark build' first."));
+    process.exit(1);
+  }
+  const spinner = ora4("Uploading spark...").start();
+  try {
+    const bundleBuffer = fs5.readFileSync(bundlePath);
+    const manifestBuffer = fs5.readFileSync(manifestPath);
+    const formData = new FormData();
+    formData.append("bundle", new Blob([new Uint8Array(bundleBuffer)], { type: "application/javascript" }), "bundle.js");
+    formData.append("manifest", new Blob([new Uint8Array(manifestBuffer)], { type: "application/json" }), "manifest.json");
+    const res = await fetch(`${creds.apiUrl}/api/custom-sparks/submit`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${creds.token}`
+      },
+      body: formData
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      spinner.fail(`Submit failed: ${body.error ?? res.statusText}`);
+      if (body.issues) {
+        console.error(kleur5.red("\nValidation issues:"));
+        console.error(JSON.stringify(body.issues, null, 2));
+      }
+      process.exit(1);
+    }
+    const spark = await res.json();
+    spinner.succeed(`Submitted ${kleur5.cyan(spark.name)} v${spark.version}`);
+    console.log(`
+  Status: ${kleur5.yellow(spark.status)}`);
+    console.log(`  ID: ${kleur5.dim(spark.id)}`);
+    console.log(kleur5.bold("\nNext step:"));
+    console.log(`  ${kleur5.cyan("campfire-spark status")}  ${kleur5.dim("# check review status")}`);
+    console.log();
+  } catch (err) {
+    spinner.fail(`Submit failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/commands/status.ts
+import ora5 from "ora";
+import kleur6 from "kleur";
+async function statusCommand(sparkId, _options) {
+  const creds = requireAuth();
+  console.log(kleur6.bold().cyan("\n\u{1F525} Campfire Spark \u2014 status\n"));
+  const spinner = ora5("Fetching submissions...").start();
+  try {
+    const url = sparkId ? `${creds.apiUrl}/api/custom-sparks/${sparkId}` : `${creds.apiUrl}/api/custom-sparks/registry/custom?author=me`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${creds.token}` }
+    });
+    if (!res.ok) {
+      spinner.fail("Failed to fetch status");
+      process.exit(1);
+    }
+    const data = await res.json();
+    spinner.stop();
+    const sparks = Array.isArray(data) ? data : [data];
+    if (sparks.length === 0) {
+      console.log(kleur6.yellow("No submissions yet."));
+      return;
+    }
+    for (const spark of sparks) {
+      const statusColor = spark.status === "approved" ? kleur6.green : spark.status === "rejected" ? kleur6.red : spark.status === "deprecated" ? kleur6.gray : kleur6.yellow;
+      console.log(`  ${kleur6.bold(spark.name)} v${spark.version}`);
+      console.log(`    Status: ${statusColor(spark.status)}`);
+      console.log(`    ID: ${kleur6.dim(spark.id)}`);
+      if (spark.rejectionReason) {
+        console.log(`    ${kleur6.red("Reason:")} ${spark.rejectionReason}`);
+      }
+      console.log();
+    }
+  } catch (err) {
+    spinner.fail(`Failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/commands/request-domain.ts
+import prompts2 from "prompts";
+import ora6 from "ora";
+import kleur7 from "kleur";
+async function requestDomainCommand(domain) {
+  const creds = requireAuth();
+  console.log(kleur7.bold().cyan("\n\u{1F525} Campfire Spark \u2014 request domain\n"));
+  console.log(`  Domain: ${kleur7.cyan(domain)}
+`);
+  const response = await prompts2({
+    type: "text",
+    name: "reason",
+    message: "Why do you need this domain?",
+    validate: (v) => v.length >= 10 || "Please provide at least 10 characters"
+  });
+  if (!response.reason) {
+    console.log(kleur7.yellow("Aborted."));
+    return;
+  }
+  const spinner = ora6("Submitting request...").start();
+  try {
+    const res = await fetch(`${creds.apiUrl}/api/domains/request`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${creds.token}`
+      },
+      body: JSON.stringify({ domain, reason: response.reason })
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      spinner.fail(`Request failed: ${body.error ?? res.statusText}`);
+      process.exit(1);
+    }
+    spinner.succeed(`Domain request submitted for review`);
+    console.log(kleur7.dim("\nYou will be notified when the domain is approved."));
+  } catch (err) {
+    spinner.fail(`Request failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("campfire-spark").description("CLI for developing custom Campfire sparks").version("0.1.0");
+program.command("init").description("Scaffold a new spark project").argument("[name]", "Project name").action(initCommand);
+program.command("dev").description("Start local development server with mock SDK").option("-p, --port <number>", "Dev server port", "4321").action(devCommand);
+program.command("build").description("Build the spark bundle for production").action(buildCommand);
+program.command("login").description("Authenticate with the Campfire platform").option("--api-url <url>", "API URL", "http://localhost:3000").action(loginCommand);
+program.command("submit").description("Submit the built spark for review").option("--api-url <url>", "API URL", "http://localhost:3000").action(submitCommand);
+program.command("status").description("Check the status of your spark submissions").argument("[sparkId]", "Specific spark ID").option("--api-url <url>", "API URL", "http://localhost:3000").action(statusCommand);
+program.command("request-domain").description("Request a domain to be added to the HTTP connector whitelist").argument("<domain>", "Domain to request").option("--api-url <url>", "API URL", "http://localhost:3000").action(requestDomainCommand);
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@campfiire/spark-cli",
+  "version": "0.1.0",
+  "description": "CLI for developing custom Campfire sparks",
+  "type": "module",
+  "bin": {
+    "campfire-spark": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "start": "tsx src/index.ts",
+    "prepublishOnly": "yarn build"
+  },
+  "dependencies": {
+    "@campfiire/shared": "0.1.0",
+    "@campfiire/spark-sdk": "0.1.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5",
+    "open": "^10.1.0",
+    "ora": "^8.1.1",
+    "prompts": "^2.4.2",
+    "vite": "^8.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.0",
+    "typescript": "^6.0.2"
+  },
+  "keywords": [
+    "campfire",
+    "spark",
+    "cli",
+    "plugin",
+    "sdk"
+  ]
+}

package/templates/default/README.md

@@ -0,0 +1,40 @@
+# My Spark
+
+A custom spark for Campfire.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start local dev server with mock SDK
+npm run dev
+
+# Build for production
+npm run build
+
+# Submit for review
+npm run submit
+```
+
+## SDK
+
+This spark uses `@campfiire/spark-sdk` to access platform data:
+
+- `sdk.getCampfire()` — campfire info (name, member count)
+- `sdk.getMembers()` — list of members
+- `sdk.getChannels()` — list of channels
+- `sdk.getMessages(channelId)` — messages in a channel
+- `sdk.getCurrentUser()` — currently logged-in user
+- `sdk.getTheme()` — current theme
+- `sdk.storage` — persistent key-value storage
+
+## Configuration
+
+Your spark's config is validated against the Zod schema in `src/index.tsx`. Campfire admins can edit the config in the layout editor.
+
+## Learn More
+
+- [Spark SDK Docs](https://docs.campfire.app/sparks)
+- [SDK Reference](https://docs.campfire.app/sparks/sdk)

package/templates/default/index.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Spark Dev</title>
+    <style>
+      * { box-sizing: border-box; }
+      html, body {
+        margin: 0;
+        padding: 0;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        background: #f5f5f5;
+        color: #0a0a0a;
+      }
+      :root {
+        --primary: #0ea5e9;
+        --background: #ffffff;
+        --foreground: #0a0a0a;
+        --border: #e5e5e5;
+        --muted-foreground: #737373;
+      }
+      #dev-container {
+        max-width: 600px;
+        margin: 2rem auto;
+        padding: 1rem;
+      }
+      #dev-header {
+        background: white;
+        border: 1px solid #e5e5e5;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1rem;
+        font-size: 14px;
+      }
+      #dev-header h1 { margin: 0 0 0.5rem; font-size: 1rem; }
+      #dev-header p { margin: 0; color: #737373; font-size: 12px; }
+      #spark-root {
+        background: white;
+        border: 1px solid #e5e5e5;
+        border-radius: 0.5rem;
+        padding: 1rem;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="dev-container">
+      <div id="dev-header">
+        <h1>🔥 Campfire Spark — Dev Mode</h1>
+        <p>This is your spark running with mock SDK data. Edit <code>src/index.tsx</code> to see changes.</p>
+      </div>
+      <div id="spark-root"></div>
+    </div>
+    <script type="module" src="/src/dev-entry.tsx"></script>
+  </body>
+</html>

package/templates/default/manifest.json

@@ -0,0 +1,15 @@
+{
+  "slug": "my-spark",
+  "name": "My Spark",
+  "version": "1.0.0",
+  "description": "A custom spark for Campfire",
+  "author": "",
+  "icon": "IconSparkles",
+  "permissions": [],
+  "connectors": [],
+  "defaultConfig": {
+    "greeting": "Hello"
+  },
+  "defaultWidth": 1,
+  "minPlatformVersion": "1.0.0"
+}

package/templates/default/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "my-spark",
+  "version": "1.0.0",
+  "description": "A custom spark for Campfire",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "campfire-spark dev",
+    "build": "campfire-spark build",
+    "submit": "campfire-spark submit"
+  },
+  "dependencies": {
+    "@campfiire/spark-sdk": "^0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/default/src/dev-entry.tsx

@@ -0,0 +1,217 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import spark from "./index";
+
+// ── Mock SDK setup for local dev ───────────────────
+// In production, the SDK communicates via postMessage with the Campfire host.
+// In dev, we construct a mock SDK that returns fake data and pass it directly
+// to the spark's render component as a prop (bypassing the postMessage bridge).
+
+import type {
+  SparkSDK,
+  SparkSDKCampfire,
+  SparkSDKMember,
+  SparkSDKChannel,
+  SparkSDKMessage,
+  SparkSDKUser,
+  SparkSDKTheme,
+  GetMembersOptions,
+  GetMessagesOptions,
+} from "@campfiire/spark-sdk";
+
+class MockSDK implements SparkSDK {
+  public storage: SparkSDK["storage"];
+  public connectors: SparkSDK["connectors"];
+  private store = new Map<string, unknown>();
+
+  constructor() {
+    this.storage = {
+      get: async <T = unknown>(key: string) => (this.store.get(key) as T) ?? null,
+      set: async (key: string, value: unknown) => {
+        this.store.set(key, value);
+      },
+      delete: async (key: string) => {
+        this.store.delete(key);
+      },
+      keys: async () => Array.from(this.store.keys()),
+    };
+
+    // Mock connectors — return realistic fake data for common connectors
+    // (twitch, github, weather, crypto, rss, youtube, spotify, http).
+    this.connectors = new Proxy({} as SparkSDK["connectors"], {
+      get: (_target, connectorId: string) => {
+        return new Proxy({} as Record<string, (params: unknown) => Promise<unknown>>, {
+          get: (_t, method: string) => {
+            return async (params: unknown): Promise<unknown> => {
+              console.log(`[MockSDK] connectors.${connectorId}.${method}`, params);
+              return getMockConnectorResponse(connectorId, method);
+            };
+          },
+        });
+      },
+    });
+  }
+
+  async getCampfire(): Promise<SparkSDKCampfire> {
+    return {
+      id: "mock-campfire",
+      name: "Test Campfire",
+      slug: "test",
+      description: "A mock campfire for dev",
+      memberCount: 42,
+      channelCount: 5,
+    };
+  }
+
+  async getMembers(options?: GetMembersOptions): Promise<SparkSDKMember[]> {
+    const members: SparkSDKMember[] = [
+      { id: "u1", name: "Alice", image: null, isOnline: true, joinedAt: new Date().toISOString() },
+      { id: "u2", name: "Bob", image: null, isOnline: false, joinedAt: new Date().toISOString() },
+      { id: "u3", name: "Charlie", image: null, isOnline: true, joinedAt: new Date().toISOString() },
+      { id: "u4", name: "Diana", image: null, isOnline: false, joinedAt: new Date().toISOString() },
+      { id: "u5", name: "Eve", image: null, isOnline: true, joinedAt: new Date().toISOString() },
+    ];
+    return members.slice(0, options?.limit ?? 50);
+  }
+
+  async getChannels(): Promise<SparkSDKChannel[]> {
+    return [
+      { id: "c1", name: "general", description: "General chat", isDefault: true },
+      { id: "c2", name: "random", description: null, isDefault: false },
+    ];
+  }
+
+  async getMessages(channelId: string, options?: GetMessagesOptions): Promise<SparkSDKMessage[]> {
+    return [
+      {
+        id: "m1",
+        content: "Hello world!",
+        authorId: "u1",
+        author: { id: "u1", name: "Alice", image: null },
+        channelId,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      },
+    ].slice(0, options?.limit ?? 20);
+  }
+
+  async getCurrentUser(): Promise<SparkSDKUser> {
+    return { id: "u1", name: "Alice (you)", image: null };
+  }
+
+  async getTheme(): Promise<SparkSDKTheme> {
+    return {
+      colors: {
+        primary: "#0ea5e9",
+        background: "#ffffff",
+        foreground: "#0a0a0a",
+      },
+      isDark: false,
+      borderRadius: "md",
+    };
+  }
+}
+
+function getMockConnectorResponse(connectorId: string, method: string): unknown {
+  const mocks: Record<string, Record<string, unknown>> = {
+    twitch: {
+      getStream: {
+        isLive: true,
+        title: "Just chatting with the community!",
+        viewerCount: 45000,
+        gameName: "Just Chatting",
+        startedAt: new Date(Date.now() - 3600000).toISOString(),
+        thumbnailUrl: "https://via.placeholder.com/320x180",
+      },
+      getChannel: {
+        id: "mock-channel-id",
+        displayName: "MockStreamer",
+        description: "A mock Twitch channel for development",
+        profileImageUrl: "https://via.placeholder.com/100",
+      },
+    },
+    github: {
+      getRepo: {
+        name: "mock-repo",
+        fullName: "mock-user/mock-repo",
+        description: "A mock GitHub repository",
+        stars: 1234,
+        forks: 56,
+        openIssues: 7,
+        language: "TypeScript",
+        url: "https://github.com/mock-user/mock-repo",
+      },
+      getContributors: [
+        { login: "alice", avatarUrl: "https://via.placeholder.com/40", contributions: 42, url: "#" },
+        { login: "bob", avatarUrl: "https://via.placeholder.com/40", contributions: 15, url: "#" },
+      ],
+    },
+    weather: {
+      getCurrent: {
+        city: "Paris",
+        country: "FR",
+        temperature: 18.5,
+        feelsLike: 17.2,
+        description: "partly cloudy",
+        icon: "02d",
+        humidity: 65,
+        windSpeed: 3.4,
+      },
+    },
+    crypto: {
+      getPrice: {
+        coin: "bitcoin",
+        price: 43250,
+        currency: "usd",
+      },
+    },
+    rss: {
+      fetchFeed: [
+        { title: "Mock Article 1", link: "https://example.com/1", description: "Lorem ipsum...", pubDate: new Date().toISOString() },
+        { title: "Mock Article 2", link: "https://example.com/2", description: "Dolor sit amet...", pubDate: new Date().toISOString() },
+      ],
+    },
+    youtube: {
+      getChannel: {
+        id: "UC_mock",
+        title: "Mock Channel",
+        description: "A mock YouTube channel",
+        subscribers: 1000000,
+        videoCount: 250,
+        viewCount: 50000000,
+        thumbnailUrl: "https://via.placeholder.com/88",
+      },
+    },
+    spotify: {
+      getPlaylist: {
+        name: "Mock Playlist",
+        description: "A mock Spotify playlist",
+        owner: "mock-user",
+        trackCount: 50,
+        followers: 1234,
+        imageUrl: "https://via.placeholder.com/300",
+      },
+    },
+    http: {
+      get: {
+        status: 200,
+        body: { mock: true, message: "This is mock HTTP connector data" },
+      },
+    },
+  };
+
+  return mocks[connectorId]?.[method] ?? { mock: true, connectorId, method };
+}
+
+// Render the spark's component directly with the mock SDK as a prop.
+// This bypasses the postMessage bridge used in production.
+const mockSdk = new MockSDK();
+const SparkComponent = spark.render;
+const rootEl = document.getElementById("spark-root");
+if (rootEl) {
+  ReactDOM.createRoot(rootEl).render(
+    <React.StrictMode>
+      <SparkComponent config={spark.defaultConfig} sdk={mockSdk} />
+    </React.StrictMode>
+  );
+}

package/templates/default/src/index.tsx

@@ -0,0 +1,77 @@
+import { defineSpark } from "@campfiire/spark-sdk";
+import { useEffect, useState } from "react";
+import type { SparkSDKCampfire, SparkSDKMember } from "@campfiire/spark-sdk";
+import { z } from "zod";
+
+/**
+ * My Spark — example custom spark for Campfire.
+ *
+ * This is where you define your spark. It receives a `config` (validated against
+ * `configSchema`) and a `sdk` object to access platform data.
+ */
+export default defineSpark({
+  name: "My Spark",
+  version: "1.0.0",
+  description: "A custom spark for Campfire",
+  icon: "IconSparkles",
+
+  // Define the config schema — this creates a Zod type and is used for
+  // validation in the campfire settings UI.
+  configSchema: z.object({
+    greeting: z.string().max(100),
+  }),
+
+  defaultConfig: {
+    greeting: "Hello",
+  },
+
+  render: ({ config, sdk }) => {
+    const [campfire, setCampfire] = useState<SparkSDKCampfire | null>(null);
+    const [members, setMembers] = useState<SparkSDKMember[]>([]);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+      Promise.all([sdk.getCampfire(), sdk.getMembers({ limit: 5 })])
+        .then(([c, m]) => {
+          setCampfire(c);
+          setMembers(m);
+          setLoading(false);
+        })
+        .catch(() => setLoading(false));
+    }, [sdk]);
+
+    if (loading) {
+      return <p style={{ color: "var(--muted-foreground)" }}>Loading...</p>;
+    }
+
+    return (
+      <div style={{ padding: "0.5rem" }}>
+        <h2 style={{ margin: "0 0 0.5rem", fontSize: "1.25rem" }}>
+          {config.greeting}, {campfire?.name}! 🔥
+        </h2>
+        <p style={{ margin: "0 0 1rem", color: "var(--muted-foreground)", fontSize: "0.875rem" }}>
+          This campfire has {campfire?.memberCount} members.
+        </p>
+        <div>
+          <h3 style={{ margin: "0 0 0.5rem", fontSize: "0.875rem", fontWeight: 600 }}>
+            Recent members:
+          </h3>
+          <ul style={{ margin: 0, padding: 0, listStyle: "none" }}>
+            {members.map((m) => (
+              <li
+                key={m.id}
+                style={{
+                  padding: "0.375rem 0",
+                  fontSize: "0.875rem",
+                  borderTop: "1px solid var(--border)",
+                }}
+              >
+                {m.name} {m.isOnline && <span style={{ color: "#22c55e" }}>●</span>}
+              </li>
+            ))}
+          </ul>
+        </div>
+      </div>
+    );
+  },
+});

package/templates/default/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/default/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import * as path from "node:path";
+
+/**
+ * This config is used by `campfire-spark dev` for local development.
+ * Production builds use a different config (applied by `campfire-spark build`).
+ */
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});