speculos-toolkit 1.0.0

package/src/client.js

@@ -0,0 +1,55 @@
+// HTTP client to the Speculos orchestrator (management API). Holds no platform
+// secrets. The orchestrator runs self-hosted behind the Cloudflare forwarding
+// deploy-orch-38hd4.speculos.ai; it drives Daytona backends and pushes frontends
+// to the EC2 host that serves them at user-deployed.speculos.ai.
+const DEFAULT_API = process.env.SPECULOS_API || "https://deploy-orch-38hd4.speculos.ai";
+
+function base(opts) { return (opts.api || DEFAULT_API).replace(/\/$/, ""); }
+
+async function post(url, body, token) {
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers["Authorization"] = "Bearer " + token;
+  const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) { const e = new Error(data.error || `HTTP ${res.status}`); e.code = data.code; e.status = res.status; throw e; }
+  return data;
+}
+async function get(url, token) {
+  const headers = {};
+  if (token) headers["Authorization"] = "Bearer " + token;
+  const res = await fetch(url, { headers });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) { const e = new Error(data.error || `HTTP ${res.status}`); e.code = data.code; e.status = res.status; throw e; }
+  return data;
+}
+
+// establish identity (mint on first call) + allocate the slug's stable uuid.
+// opts.token (CLI account token) links this machine to the account.
+async function allocate(payload, opts = {}) { return post(base(opts) + "/api/allocate", payload, opts.token); }
+// start a per-app backend sandbox (account token authorizes via entitlement)
+async function startBackend(payload, opts = {}) { return post(base(opts) + "/api/backend", payload, opts.token); }
+// ---- account device-link ----
+async function linkStart(opts = {}) { return post(base(opts) + "/api/cli/link/start", {}); }
+async function linkPoll(code, opts = {}) { return post(base(opts) + "/api/cli/link/poll", { code }); }
+// verify a pasted account token (login --token) and get its account/org
+async function whoami(token, opts = {}) { return get(base(opts) + "/api/account/whoami", token); }
+async function linkMachine(token, payload, opts = {}) { return post(base(opts) + "/api/account/link", payload, token); }
+async function logout(token, opts = {}) { return post(base(opts) + "/api/account/logout", {}, token); }
+// poll a backend job (owner-authenticated)
+async function backendStatus(jobId, creds = {}, opts = {}) {
+  const qs = new URLSearchParams({ userId: creds.userId || "", userKey: creds.userKey || "" });
+  return get(base(opts) + "/api/backend/" + encodeURIComponent(jobId) + "?" + qs.toString());
+}
+// upload built/static frontend
+async function putFrontend(payload, opts = {}) { return post(base(opts) + "/api/frontend", payload); }
+// remove a deployment
+async function teardown(payload, opts = {}) { return post(base(opts) + "/api/teardown", payload); }
+// ---- connectors (data sources linked in the dashboard) ----
+async function connectorsList(token, opts = {}) {
+  return get(base(opts) + "/api/connectors" + (opts.noTools ? "?tools=0" : ""), token);
+}
+async function connectorsExec(token, payload, opts = {}) {
+  return post(base(opts) + "/api/connectors/execute", payload, token);
+}
+
+module.exports = { allocate, startBackend, backendStatus, putFrontend, teardown, linkStart, linkPoll, linkMachine, whoami, logout, connectorsList, connectorsExec, base, DEFAULT_API };

package/src/creds.js

@@ -0,0 +1,83 @@
+// Local credentials.
+//   ~/.speculos/identity.json  -> { userId, userKey }   (machine-global; groups
+//                                  all of this machine's deploys under one userId)
+//   <project>/.speculos.json   -> { slug, slugUuid }     (per-project, gitignored)
+// userKey is a secret; both files are kept out of git.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+// ---- machine-global identity --------------------------------------------
+
+function identityDir() { return path.join(os.homedir(), ".speculos"); }
+function identityFile() { return path.join(identityDir(), "identity.json"); }
+
+function loadIdentity() {
+  const f = identityFile();
+  let raw;
+  try { raw = fs.readFileSync(f, "utf8"); } catch { return null; } // no file yet
+  try { return JSON.parse(raw); }
+  catch {
+    // The file EXISTS but is corrupt/truncated. Don't silently treat it as
+    // "missing" — that would mint a fresh identity and overwrite it, orphaning
+    // the URLs it owned. Preserve it under .corrupt for recovery and warn.
+    try { fs.renameSync(f, f + ".corrupt"); process.stderr.write(`! ${f} was unreadable — backed up to ${f}.corrupt; minting a fresh identity.\n`); } catch { /* ignore */ }
+    return null;
+  }
+}
+// Merge-write so we never drop a field the other writer set (e.g. accountToken).
+// Atomic (tmp + rename) so a crash/full-disk mid-write can't truncate the file.
+function writeIdentity(obj) {
+  try {
+    fs.mkdirSync(identityDir(), { recursive: true });
+    const tmp = identityFile() + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, identityFile());
+  } catch { /* best effort */ }
+}
+function saveIdentity({ userId, userKey }) {
+  const cur = loadIdentity() || {};
+  writeIdentity({ ...cur, userId, userKey });
+}
+// The CLI account token from `speculos-toolkit login` (links this machine to an
+// account; unlocks backend hosting). Stored alongside the machine identity.
+function saveAccountToken(accountToken) {
+  const cur = loadIdentity() || {};
+  writeIdentity({ ...cur, accountToken });
+}
+function clearAccountToken() {
+  const cur = loadIdentity();
+  if (!cur) return;
+  delete cur.accountToken;
+  writeIdentity(cur);
+}
+
+// ---- per-project slug record --------------------------------------------
+
+function file(root) { return path.join(root, ".speculos.json"); }
+
+function load(root) {
+  try { return JSON.parse(fs.readFileSync(file(root), "utf8")); } catch { return null; }
+}
+function save(root, data) {
+  fs.writeFileSync(file(root), JSON.stringify(data, null, 2) + "\n");
+  ensureGitignored(root);
+}
+function remove(root) {
+  try { fs.unlinkSync(file(root)); } catch { /* ignore */ }
+}
+
+function ensureGitignored(root) {
+  const gi = path.join(root, ".gitignore");
+  try {
+    let txt = "";
+    try { txt = fs.readFileSync(gi, "utf8"); } catch { /* no .gitignore yet */ }
+    const has = txt.split(/\r?\n/).some((l) => l.trim() === ".speculos.json");
+    if (!has) {
+      const prefix = txt && !txt.endsWith("\n") ? txt + "\n" : txt;
+      fs.writeFileSync(gi, prefix + ".speculos.json\n");
+    }
+  } catch { /* best effort */ }
+}
+
+module.exports = { loadIdentity, saveIdentity, saveAccountToken, clearAccountToken, load, save, remove, file };

package/src/detect.js

@@ -0,0 +1,129 @@
+// Auto-detect frontend + backend dirs and how to build/run them.
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const FRONTEND_DIRS = ["frontend", "web", "client", "site", "www", "ui", "app"];
+const BACKEND_DIRS = ["backend", "api", "server", "svc", "service"];
+
+function exists(p) { try { fs.accessSync(p); return true; } catch { return false; } }
+function readJSON(p) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; } }
+
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 34) || "app";
+}
+
+function defaultSlug(root) {
+  const base = slugify(path.basename(path.resolve(root)));
+  const h = crypto.createHash("sha1").update(path.resolve(root)).digest("hex").slice(0, 4);
+  return `${base}-${h}`;
+}
+
+// ---- frontend -----------------------------------------------------------
+
+function classifyFrontend(dir, opts = {}) {
+  const pkg = readJSON(path.join(dir, "package.json"));
+  // --static / --no-build: serve the dir as-is even if it has a build script
+  // (e.g. a plain static site whose package.json only runs Tailwind/a linter).
+  const hasBuild = !opts.noBuild && pkg && pkg.scripts && pkg.scripts.build;
+  if (hasBuild) {
+    const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+    let outputDir = null, framework = "other";
+    if (deps.next) { outputDir = "out"; framework = "next"; }            // next export; SSR not covered by a static host
+    else if (deps.vite || deps["@vitejs/plugin-react"]) { outputDir = "dist"; framework = "vite"; }
+    else if (deps["react-scripts"]) { outputDir = "build"; framework = "cra"; }
+    else if (deps["@angular/core"]) { outputDir = "dist"; framework = "angular"; }
+    else if (deps.svelte || deps["@sveltejs/kit"]) { outputDir = "build"; framework = "svelte"; }
+    return { dir, kind: "build", buildCmd: "npm run build", outputDir, framework };
+  }
+  // static: a directory of files we serve as-is (plain HTML or a prebuilt dist)
+  return { dir, kind: "static", buildCmd: null, outputDir: null, framework: "static" };
+}
+
+function findFrontend(root, explicit, opts = {}) {
+  if (explicit) return classifyFrontend(explicit, opts);
+  for (const name of FRONTEND_DIRS) {
+    const p = path.join(root, name);
+    if (exists(p) && fs.statSync(p).isDirectory()) {
+      const c = classifyFrontend(p, opts);
+      // a named dir counts as the frontend if it builds with a known framework
+      // or is a plain static dir (has an index.html)
+      if (c.framework !== "static" || exists(path.join(p, "index.html"))) return c;
+    }
+  }
+  // root itself: a plain static site (index.html), or a RECOGNIZED build framework
+  // at the root (Next/Vite/CRA/Angular/Svelte). An unknown-framework root build
+  // ("other" — e.g. a bare `tsc` project) is NOT auto-taken as a frontend: that
+  // would misdetect a backend-only repo and publish its compiled source. Such a
+  // root app can still be deployed explicitly with `--frontend .`.
+  if (exists(path.join(root, "index.html"))) return classifyFrontend(root, opts);
+  const rootC = classifyFrontend(root, opts);
+  if (rootC.kind === "build" && rootC.framework !== "other") return rootC;
+  return null;
+}
+
+// ---- backend ------------------------------------------------------------
+
+function classifyBackend(dir) {
+  const pkg = readJSON(path.join(dir, "package.json"));
+  if (pkg) {
+    // bun signal: a bun lockfile, bunfig, or packageManager/engines naming bun.
+    const isBun = exists(path.join(dir, "bun.lockb")) || exists(path.join(dir, "bun.lock")) ||
+      exists(path.join(dir, "bunfig.toml")) ||
+      (typeof pkg.packageManager === "string" && pkg.packageManager.startsWith("bun")) ||
+      !!(pkg.engines && pkg.engines.bun);
+    const runtime = isBun ? "bun" : "node";
+    let startCmd;
+    if (pkg.scripts && pkg.scripts.start) startCmd = isBun ? "bun run start" : "npm start";
+    else if (isBun) {
+      const entry = ["index.ts", "server.ts", "src/index.ts", "src/server.ts", "index.js", "server.js", "app.ts", "main.ts"]
+        .find((f) => exists(path.join(dir, f)));
+      startCmd = entry ? `bun ${entry}` : "bun index.ts";
+    } else {
+      const entry = ["index.js", "server.js", "app.js", "main.js", "src/index.js", "src/server.js"]
+        .find((f) => exists(path.join(dir, f)));
+      startCmd = entry ? `node ${entry}` : "node index.js";
+    }
+    return { dir, runtime, startCmd };
+  }
+  if (exists(path.join(dir, "requirements.txt")) || exists(path.join(dir, "pyproject.toml")) ||
+      exists(path.join(dir, "app.py")) || exists(path.join(dir, "main.py"))) {
+    const procfile = readProcfile(dir);
+    let startCmd = procfile;
+    if (!startCmd) {
+      const entry = ["app.py", "main.py", "server.py", "wsgi.py"].find((f) => exists(path.join(dir, f)));
+      startCmd = entry ? `python3 ${entry}` : "python3 app.py";
+    }
+    return { dir, runtime: "python", startCmd };
+  }
+  return null;
+}
+
+function readProcfile(dir) {
+  try {
+    const txt = fs.readFileSync(path.join(dir, "Procfile"), "utf8");
+    const m = txt.match(/^web:\s*(.+)$/m);
+    return m ? m[1].trim() : null;
+  } catch { return null; }
+}
+
+function findBackend(root, explicit) {
+  if (explicit) return classifyBackend(explicit);
+  for (const name of BACKEND_DIRS) {
+    const p = path.join(root, name);
+    if (exists(p) && fs.statSync(p).isDirectory()) { const c = classifyBackend(p); if (c) return c; }
+  }
+  return null;
+}
+
+function detect(root, opts = {}) {
+  const frontend = opts.noFrontend ? null : findFrontend(root, opts.frontend, { noBuild: opts.static });
+  const backend = opts.noBackend ? null : findBackend(root, opts.backend);
+  if (frontend && opts.build) frontend.kind = "build";
+  if (frontend && opts.output) frontend.outputDir = opts.output;
+  if (backend && opts.start) backend.startCmd = opts.start;
+  if (backend && opts.runtime) backend.runtime = opts.runtime;
+  return { slug: opts.slug || defaultSlug(root), frontend, backend };
+}
+
+module.exports = { detect, slugify, defaultSlug, classifyFrontend, classifyBackend };