@devaccel-labs/comment-service 0.5.1

package/README.md

@@ -0,0 +1,16 @@
+# @devaccel-labs/comment-service
+
+In-page comments for TanStack Start apps on Cloudflare: select any component, comment, reply, @mention teammates, attach files and screenshots. Threads stay attached to the component across redeploys.
+
+```ts
+// vite.config.ts, before tanstackStart()
+import { commentService } from "@devaccel-labs/comment-service/vite"
+
+// src/routes/__root.tsx, before <Scripts />
+import { CommentToolbar } from "@devaccel-labs/comment-service/react"
+
+// src/routes/api/comment-service/session.ts
+import { handleSessionRequest } from "@devaccel-labs/comment-service/server"
+```
+
+The toolbar talks to a DevAccel comment-service Worker. Configure the app with `COMMENT_SERVICE_URL`, `COMMENT_SERVICE_PROJECT`, `COMMENT_SERVICE_ENVIRONMENT` and a server-only `COMMENT_SERVICE_SECRET`; provision them with `npx comment-service provision` and check an install with `npx comment-service doctor`.

package/dist/cli.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+var DEFAULT_API = "https://devaccel-comment-service.devaccel-labs.workers.dev";
+var USER_AGENT = "Mozilla/5.0 (compatible; comment-service-cli/0.1)";
+var KEYS = ["COMMENT_SERVICE_URL", "COMMENT_SERVICE_PROJECT", "COMMENT_SERVICE_ENVIRONMENT", "COMMENT_SERVICE_SECRET"];
+var HELP = `comment-service <command> [options]
+
+Commands
+  provision   Create (or rotate) a project + environment on the comment service.
+  doctor      Check that a running host app is wired correctly.
+
+provision
+  --project <slug>        Project slug, e.g. jebelai-mockups (required)
+  --name <text>           Display name for a new project (default: slug)
+  --env <name>            Environment name: local, staging, production (required)
+  --origin <url>          Allowed browser origin. Repeat for several. Required.
+  --passphrase <text>     Passphrase people type to unlock. Generated if omitted.
+  --rotate                Environment exists: rotate its secret (and passphrase if given).
+  --dev-vars <file>       Write COMMENT_SERVICE_* into this env file (local dev).
+  --wrangler-secret       Pipe the secret into \`wrangler secret put COMMENT_SERVICE_SECRET\` (cwd).
+  --admin-env <file>      File with ADMIN_TOKEN=... (else $COMMENT_SERVICE_ADMIN_TOKEN).
+  --api <url>             Comment service origin (default: ${DEFAULT_API}).
+  --json                  Machine-readable output. Never includes the secret.
+
+doctor
+  --app <url>             Running host app origin, e.g. http://localhost:3400 (required)
+  --page <path>           Page to scan for component stamps (default: /)
+  --dev-vars <file>       Read COMMENT_SERVICE_URL / COMMENT_SERVICE_PASSPHRASE from here.
+  --passphrase <text>     Also prove unlock + list threads with this passphrase.
+  --header "<k>: <v>"     Extra header for app requests. Repeat. Use for Cloudflare Access
+                          service tokens (cf-access-client-id / cf-access-client-secret).
+  --json                  Machine-readable output.
+`;
+function fail(message) {
+  console.error(`comment-service: ${message}`);
+  process.exit(1);
+}
+function readEnvFile(file) {
+  if (!fs.existsSync(file)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+    out[match[1]] = match[2].replace(/^(['"])(.*)\1$/, "$2");
+  }
+  return out;
+}
+function writeEnvFile(file, values) {
+  const lines = fs.existsSync(file) ? fs.readFileSync(file, "utf8").split(/\r?\n/) : [];
+  const pending = new Map(Object.entries(values));
+  const next = lines.map((line) => {
+    const key = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/)?.[1];
+    if (!key || !pending.has(key)) return line;
+    const value = pending.get(key);
+    pending.delete(key);
+    return `${key}=${value}`;
+  });
+  while (next.length && next.at(-1) === "") next.pop();
+  for (const [key, value] of pending) next.push(`${key}=${value}`);
+  fs.writeFileSync(file, `${next.join("\n")}
+`, { mode: 384 });
+}
+function generatePassphrase() {
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  const chars = [...bytes].map((byte) => alphabet[byte % alphabet.length]);
+  return [chars.slice(0, 4), chars.slice(4, 8), chars.slice(8, 12)].map((group) => group.join("")).join("-");
+}
+function normalizeOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    fail(`"${value}" is not an absolute URL.`);
+  }
+}
+var HttpFailure = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+  status;
+  code;
+};
+async function call(url, init = {}) {
+  const response = await fetch(url, { ...init, headers: { "user-agent": USER_AGENT, ...init.headers } });
+  const text = await response.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  if (!response.ok) {
+    const error = body?.error;
+    throw new HttpFailure(response.status, error?.code ?? "http_error", error?.message ?? text.slice(0, 200));
+  }
+  return body;
+}
+function wranglerBin(cwd) {
+  const local = path.join(cwd, "node_modules", ".bin", process.platform === "win32" ? "wrangler.cmd" : "wrangler");
+  return fs.existsSync(local) ? { command: local, args: [] } : { command: "npx", args: ["wrangler"] };
+}
+function putWranglerSecret(secret) {
+  const cwd = process.cwd();
+  const bin = wranglerBin(cwd);
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin.command, [...bin.args, "secret", "put", "COMMENT_SERVICE_SECRET"], {
+      cwd,
+      stdio: ["pipe", "inherit", "inherit"]
+    });
+    child.stdin.write(secret);
+    child.stdin.end();
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`wrangler secret put exited ${code}`)));
+  });
+}
+async function provision(flags) {
+  const project = String(flags.project ?? "");
+  const environment = String(flags.env ?? "");
+  if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(project)) fail("--project must be a lowercase slug (2-41 chars).");
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(environment)) fail("--env must be a lowercase name like local or production.");
+  const origins = (flags.origin ?? []).map(normalizeOrigin);
+  if (!origins.length) fail("pass at least one --origin (the URL people open the app at).");
+  const api = String(flags.api ?? process.env.COMMENT_SERVICE_URL ?? DEFAULT_API).replace(/\/$/, "");
+  const adminFile = flags["admin-env"] ? readEnvFile(String(flags["admin-env"])) : {};
+  const admin = process.env.COMMENT_SERVICE_ADMIN_TOKEN || adminFile.ADMIN_TOKEN;
+  if (!admin) fail("no admin token. Set COMMENT_SERVICE_ADMIN_TOKEN or pass --admin-env <file with ADMIN_TOKEN=>.");
+  const headers = { authorization: `Bearer ${admin}`, "content-type": "application/json" };
+  const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : generatePassphrase();
+  const base = `${api}/v1/admin/projects`;
+  let projectCreated = true;
+  await call(base, { method: "POST", headers, body: JSON.stringify({ name: String(flags.name ?? project), slug: project }) }).catch(
+    (error) => {
+      if (error instanceof HttpFailure && error.status === 409) projectCreated = false;
+      else throw error;
+    }
+  );
+  let secret;
+  let rotated = false;
+  try {
+    const created = await call(`${base}/${project}/environments`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name: environment, passphrase, origins })
+    });
+    secret = created.integrationSecret;
+  } catch (error) {
+    if (!(error instanceof HttpFailure) || error.status !== 409) throw error;
+    if (!flags.rotate) {
+      fail(
+        `environment "${environment}" already exists for "${project}". Re-run with --rotate to issue a new secret (the old one stops working), or reuse the values you already have.`
+      );
+    }
+    await call(`${base}/${project}/environments/${environment}`, {
+      method: "PATCH",
+      headers,
+      body: JSON.stringify({ origins, ...typeof flags.passphrase === "string" ? { passphrase } : {} })
+    });
+    const next = await call(`${base}/${project}/environments/${environment}/rotate-secret`, {
+      method: "POST",
+      headers
+    });
+    secret = next.integrationSecret;
+    rotated = true;
+  }
+  const passphraseChanged = !rotated || typeof flags.passphrase === "string";
+  const values = {
+    COMMENT_SERVICE_URL: api,
+    COMMENT_SERVICE_PROJECT: project,
+    COMMENT_SERVICE_ENVIRONMENT: environment,
+    COMMENT_SERVICE_SECRET: secret
+  };
+  const devVars = typeof flags["dev-vars"] === "string" ? flags["dev-vars"] : null;
+  if (devVars) {
+    writeEnvFile(devVars, passphraseChanged ? { ...values, COMMENT_SERVICE_PASSPHRASE: passphrase } : values);
+  }
+  if (flags["wrangler-secret"]) await putWranglerSecret(secret);
+  const summary = {
+    api,
+    project,
+    projectCreated,
+    environment,
+    rotated,
+    origins,
+    passphrase: passphraseChanged ? passphrase : null,
+    wroteDevVars: devVars,
+    wranglerSecret: Boolean(flags["wrangler-secret"]),
+    vars: { COMMENT_SERVICE_URL: api, COMMENT_SERVICE_PROJECT: project, COMMENT_SERVICE_ENVIRONMENT: environment }
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(`${projectCreated ? "Created" : "Using"} project ${project} on ${api}`);
+  console.log(`${rotated ? "Rotated" : "Created"} environment ${environment} (origins: ${origins.join(", ")})`);
+  if (passphraseChanged) console.log(`Passphrase: ${passphrase}`);
+  if (devVars) console.log(`Wrote ${KEYS.join(", ")}${passphraseChanged ? ", COMMENT_SERVICE_PASSPHRASE" : ""} to ${devVars}`);
+  if (flags["wrangler-secret"]) console.log("Stored COMMENT_SERVICE_SECRET as a Worker secret.");
+  if (!devVars && !flags["wrangler-secret"]) {
+    console.log("\nCOMMENT_SERVICE_SECRET is shown once. Store it as a server-only secret:");
+    console.log(`COMMENT_SERVICE_SECRET=${secret}`);
+  }
+  if (!devVars) {
+    console.log("\nNon-secret vars for wrangler.jsonc `vars`:");
+    console.log(JSON.stringify(summary.vars, null, 2));
+  }
+}
+async function doctor(flags) {
+  if (typeof flags.app !== "string") fail("--app <url> is required, e.g. http://localhost:3400");
+  const app = normalizeOrigin(flags.app);
+  const page = typeof flags.page === "string" ? flags.page : "/";
+  const file = typeof flags["dev-vars"] === "string" ? readEnvFile(flags["dev-vars"]) : {};
+  const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : file.COMMENT_SERVICE_PASSPHRASE;
+  const checks = [];
+  const add = (name, ok2, detail) => checks.push({ name, ok: ok2, detail });
+  const extra = {};
+  for (const raw of flags.header ?? []) {
+    const cut = raw.indexOf(":");
+    if (cut < 1) fail(`--header "${raw}" must look like "name: value".`);
+    extra[raw.slice(0, cut).trim().toLowerCase()] = raw.slice(cut + 1).trim();
+  }
+  const appFetch = async (pathname, accept) => {
+    const response = await fetch(`${app}${pathname}`, {
+      headers: { accept, "user-agent": USER_AGENT, ...extra },
+      redirect: "manual"
+    });
+    const location = response.headers.get("location") ?? "";
+    if (response.status >= 300 && response.status < 400 && location.includes("cloudflareaccess.com")) {
+      throw new Error(
+        "blocked by Cloudflare Access before reaching the app. Verify in a browser signed in to Access, or pass an Access service token with --header 'cf-access-client-id: \u2026' --header 'cf-access-client-secret: \u2026'."
+      );
+    }
+    if (response.status >= 300 && response.status < 400 && location) {
+      return fetch(new URL(location, `${app}${pathname}`), { headers: { accept, "user-agent": USER_AGENT, ...extra } });
+    }
+    return response;
+  };
+  let session = null;
+  try {
+    const response = await appFetch("/api/comment-service/session", "application/json");
+    const text = await response.text();
+    try {
+      session = JSON.parse(text);
+    } catch {
+      add("session route", false, `GET /api/comment-service/session returned ${response.status} non-JSON. Is the server route file in src/routes/api/comment-service/session.ts?`);
+    }
+  } catch (error) {
+    const message = error.message;
+    add("session route", false, message.startsWith("blocked by") ? message : `could not reach ${app}: ${message}. Is the dev server running?`);
+  }
+  if (session) {
+    if (session.enabled && session.hostToken) {
+      add("session route", true, `${session.project} / ${session.environment} via ${session.apiUrl}`);
+    } else if (session.error) {
+      add("session route", false, `service rejected the app (${session.status ?? "?"}): ${session.error} [origin seen: ${session.origin}]`);
+    } else {
+      add("session route", false, "enabled:false. COMMENT_SERVICE_URL/PROJECT/ENVIRONMENT/SECRET are not all visible to the app runtime (.dev.vars locally, vars + secret when deployed).");
+    }
+  }
+  const api = (session?.apiUrl ?? file.COMMENT_SERVICE_URL ?? DEFAULT_API).replace(/\/$/, "");
+  try {
+    const health = await call(`${api}/v1/health`);
+    add("service health", Boolean(health?.ok), api);
+  } catch (error) {
+    add("service health", false, `${api}: ${error.message}`);
+  }
+  try {
+    const response = await appFetch(page, "text/html");
+    const html = await response.text();
+    const stamps = html.match(/data-cs-cmp=/g)?.length ?? 0;
+    add(
+      "component stamps",
+      stamps > 0,
+      stamps > 0 ? `${stamps} data-cs-cmp attributes in SSR HTML of ${page}` : `none in ${page}. Add commentService() from @devaccel-labs/comment-service/vite to vite plugins, before tanstackStart().`
+    );
+  } catch (error) {
+    add("component stamps", false, error.message);
+  }
+  if (session?.hostToken && passphrase) {
+    try {
+      const member = await call(`${api}/v1/auth`, {
+        method: "POST",
+        headers: { "content-type": "application/json", origin: app },
+        body: JSON.stringify({ hostToken: session.hostToken, displayName: "doctor", passphrase })
+      });
+      const listed = await call(`${api}/v1/threads`, {
+        headers: { authorization: `Bearer ${member.token}`, origin: app }
+      });
+      add("unlock + list", true, `passphrase accepted, ${listed.threads?.length ?? 0} threads visible`);
+    } catch (error) {
+      add("unlock + list", false, error.message);
+    }
+  } else if (!passphrase) {
+    add("unlock + list", true, "skipped (no passphrase given)");
+  }
+  const ok = checks.every((check) => check.ok);
+  if (flags.json) console.log(JSON.stringify({ ok, app, checks }, null, 2));
+  else {
+    for (const check of checks) console.log(`${check.ok ? "PASS" : "FAIL"}  ${check.name.padEnd(17)} ${check.detail}`);
+    console.log(ok ? "\nAll checks passed." : "\nSome checks failed.");
+  }
+  if (!ok) process.exit(1);
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(HELP);
+    return;
+  }
+  const { values } = parseArgs({
+    args: rest,
+    allowPositionals: false,
+    options: {
+      project: { type: "string" },
+      name: { type: "string" },
+      env: { type: "string" },
+      origin: { type: "string", multiple: true },
+      passphrase: { type: "string" },
+      rotate: { type: "boolean" },
+      "dev-vars": { type: "string" },
+      "wrangler-secret": { type: "boolean" },
+      "admin-env": { type: "string" },
+      api: { type: "string" },
+      app: { type: "string" },
+      page: { type: "string" },
+      header: { type: "string", multiple: true },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help) {
+    console.log(HELP);
+    return;
+  }
+  if (command === "provision") return provision(values);
+  if (command === "doctor") return doctor(values);
+  fail(`unknown command "${command}".
+
+${HELP}`);
+}
+main().catch((error) => {
+  if (error instanceof HttpFailure) fail(`${error.status} ${error.code}: ${error.message}`);
+  fail(error instanceof Error ? error.message : String(error));
+});

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+export { CommentToolbar } from "./types/react/index.js"
+export type { ToolbarPosition, ToolbarTheme } from "./types/react/index.js"