@scadable/wizard 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @scadable/wizard
+
+A one-time setup wizard that wires your published SCADABLE privacy policy into your
+codebase. Publish your policy in the SCADABLE app, copy the install command from
+Settings, and run it in your repo:
+
+```bash
+npx @scadable/wizard@latest --token <TEMP_TOKEN>
+```
+
+The wizard verifies your token, detects your web framework, asks the SCADABLE API for a
+tailored plan, then installs [`@scadable/privacy`](../next) and creates your privacy
+page. After this, your page always renders the version you last published, with no
+redeploy when you update it.
+
+## What it sends
+
+Your code stays private. The wizard reads only `./package.json` (dependency names) and a
+shallow yes/no listing of a few known folders (`app`, `src/app`, `pages`, ...). It never
+reads or transmits your source, and never touches `.env*` files. The one exception is
+opt-in `--patch <file>` mode, which reads exactly that one file, and refuses to upload it
+if it looks like it contains secrets.
+
+## Options
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--token <token>` | required | Install token from the SCADABLE app. |
+| `--api <url>` | `https://api.scadable.com` | API base. |
+| `--dry-run` | off | Show the plan, write nothing. |
+| `--yes`, `-y` | off | Skip confirmation prompts (non-interactive). |
+| `--patch <file>` | off | Patch an existing file instead of creating a new page. |
+| `--help`, `-h` | | Show usage. |
+
+The package manager is detected from your lockfile (`pnpm-lock.yaml` -> pnpm,
+`yarn.lock` -> yarn, otherwise npm).
+
+## Notes
+
+- This package only talks to the public SCADABLE API. It stores no secrets.
+- It is meant to be run once, via `npx`, to connect a repo.

package/dist/cli.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { resolve } from "path";
+import { cancel, confirm, intro, isCancel, log, note, outro, spinner } from "@clack/prompts";
+import pc from "picocolors";
+
+// src/api.ts
+var DEFAULT_API = "https://api.scadable.com";
+var WizardApiError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "WizardApiError";
+    this.status = status;
+  }
+};
+var WizardNetworkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WizardNetworkError";
+  }
+};
+function endpoint(api, path) {
+  return `${api.replace(/\/$/, "")}${path}`;
+}
+async function request(api, path, token, init = { method: "GET" }) {
+  const url = endpoint(api, path);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: init.method,
+      headers: {
+        "X-Wizard-Token": token,
+        ...init.body ? { "Content-Type": "application/json" } : {}
+      },
+      body: init.body ? JSON.stringify(init.body) : void 0
+    });
+  } catch (err) {
+    const reason2 = err instanceof Error ? err.message : String(err);
+    throw new WizardNetworkError(`could not reach ${url}: ${reason2}`);
+  }
+  if (!res.ok) {
+    throw new WizardApiError(await detail(res, path), res.status);
+  }
+  return await res.json();
+}
+async function detail(res, path) {
+  let extra = "";
+  try {
+    const data = await res.json();
+    if (typeof data?.detail === "string") extra = `: ${data.detail}`;
+  } catch {
+  }
+  return `${path} returned ${res.status}${extra}`;
+}
+function getSession(api, token) {
+  return request(api, "/wizard/session", token);
+}
+function postPlan(api, token, body) {
+  return request(api, "/wizard/plan", token, { method: "POST", body });
+}
+function postComplete(api, token) {
+  return request(api, "/wizard/complete", token, { method: "POST" });
+}
+
+// src/apply.ts
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+var INSTALL_VERB = {
+  pnpm: "add",
+  yarn: "add",
+  npm: "install"
+};
+function resolvePackages(install) {
+  const noise = /^(?:npm|yarn|pnpm|install|add|i|--save|-S|-D|--save-dev|--dev)$/;
+  const specs = install.flatMap((line) => line.split(/\s+/)).map((token) => token.trim()).filter((token) => token && !noise.test(token));
+  return [.../* @__PURE__ */ new Set(["@scadable/privacy", ...specs])];
+}
+function formatInstall(pm, packages) {
+  return `${pm} ${INSTALL_VERB[pm]} ${packages.join(" ")}`;
+}
+function runInstall(cwd, pm, packages) {
+  execFileSync(pm, [INSTALL_VERB[pm], ...packages], {
+    cwd,
+    stdio: "inherit",
+    // Windows resolves npm/yarn/pnpm through the shell.
+    shell: process.platform === "win32"
+  });
+}
+function writeEdit(cwd, edit) {
+  const abs = join(cwd, edit.path);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, edit.contents, "utf8");
+}
+
+// src/detect.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { join as join2 } from "path";
+var KNOWN_PATHS = ["app", "src/app", "pages", "src/pages", "src", "app/layout.tsx"];
+function detectRepo(cwd) {
+  const pkgPath = join2(cwd, "package.json");
+  if (!existsSync2(pkgPath)) {
+    throw new Error(
+      "No package.json found here. Run this inside your web app, next to its package.json."
+    );
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    throw new Error("Could not parse package.json. Is it valid JSON?");
+  }
+  const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+  const has = (rel) => existsSync2(join2(cwd, rel));
+  const paths = KNOWN_PATHS.filter(has);
+  const hasNext = deps.includes("next");
+  const hasReact = deps.includes("react");
+  let framework;
+  let warning;
+  if (hasNext) {
+    if (has("app") || has("src/app")) framework = "next-app";
+    else if (has("pages") || has("src/pages")) framework = "next-pages";
+    else framework = "next-app";
+  } else if (hasReact) {
+    framework = "react";
+  } else {
+    framework = "react";
+    warning = 'No "next" or "react" dependency found; assuming a generic React app.';
+  }
+  return { framework, deps, paths, warning };
+}
+var SECRET_PATTERNS = [
+  /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/,
+  /\bapi[_-]?key\s*[:=]/i,
+  /\b(?:access|secret)[_-]?key\s*[:=]/i,
+  /\bsecret\b/i,
+  /\bpassword\s*[:=]/i,
+  /\b(?:auth|access|bearer)[_-]?token\s*[:=]/i,
+  /\bAKIA[0-9A-Z]{16}\b/
+];
+function looksLikeSecret(contents) {
+  return SECRET_PATTERNS.some((re) => re.test(contents));
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const args = { api: DEFAULT_API, dryRun: false, yes: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--token") args.token = argv[++i];
+    else if (a === "--api") args.api = argv[++i];
+    else if (a === "--patch") args.patch = argv[++i];
+    else if (a === "--dry-run") args.dryRun = true;
+    else if (a === "--yes" || a === "-y") args.yes = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a.startsWith("--token=")) args.token = a.slice("--token=".length);
+    else if (a.startsWith("--api=")) args.api = a.slice("--api=".length);
+    else if (a.startsWith("--patch=")) args.patch = a.slice("--patch=".length);
+    else console.error(pc.yellow(`Ignoring unknown option: ${a}`));
+  }
+  return args;
+}
+var HELP = `
+${pc.bold("@scadable/wizard")} - wire your SCADABLE privacy policy into this repo.
+
+${pc.bold("Usage")}
+  npx @scadable/wizard@latest --token <TEMP_TOKEN> [options]
+
+${pc.bold("Options")}
+  --token <token>   Install token from the SCADABLE app (required).
+  --api <url>       API base. Default ${DEFAULT_API}.
+  --dry-run         Show the plan, write nothing.
+  --yes, -y         Skip confirmation prompts (non-interactive).
+  --patch <file>    Patch an existing file instead of creating a new page.
+  --help, -h        Show this help.
+`;
+function fail(message) {
+  log.error(message);
+  process.exit(1);
+}
+function reason(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function previewContents(contents, maxLines = 12) {
+  const lines = contents.split("\n");
+  const shown = lines.slice(0, maxLines).map((l) => pc.dim("  " + l));
+  if (lines.length > maxLines) {
+    shown.push(pc.dim(`  ... (${lines.length - maxLines} more lines)`));
+  }
+  return shown.join("\n");
+}
+function showPlan(installCmd, edits, deterministic) {
+  const blocks = [`${pc.bold("Install")}
+  ${pc.cyan(installCmd)}`];
+  for (const edit of edits) {
+    const verb = edit.action === "patch" ? "Patch" : "Create";
+    blocks.push(`${pc.bold(`${verb} ${edit.path}`)}
+${previewContents(edit.contents)}`);
+  }
+  const source = deterministic ? pc.dim("Plan is deterministic (template-based).") : pc.dim("Plan was generated for your repo.");
+  note(blocks.join("\n\n") + "\n\n" + source, "Plan");
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(HELP);
+    return;
+  }
+  intro(pc.bgCyan(pc.black(" SCADABLE privacy wizard ")));
+  if (!args.token) {
+    fail("Missing --token. Open Settings in the SCADABLE app and copy the install command.");
+  }
+  const token = args.token;
+  const api = args.api.replace(/\/$/, "");
+  const cwd = process.cwd();
+  const spin = spinner();
+  spin.start("Verifying your install token");
+  let session;
+  try {
+    session = await getSession(api, token);
+  } catch (err) {
+    spin.stop("Token check failed");
+    if (err instanceof WizardApiError && err.status === 401) {
+      fail(
+        "Your install token expired. Reopen Settings in the SCADABLE app and copy a fresh command."
+      );
+    }
+    if (err instanceof WizardNetworkError) {
+      fail(`Could not reach the SCADABLE API at ${api}. ${reason(err)}`);
+    }
+    fail(`Could not verify your token: ${reason(err)}`);
+  }
+  spin.stop(`Connected to ${pc.bold(session.scope_name)} (${session.domain})`);
+  let ctx;
+  try {
+    ctx = detectRepo(cwd);
+  } catch (err) {
+    fail(reason(err));
+  }
+  if (ctx.warning) log.warn(ctx.warning);
+  let mode = "create";
+  let target;
+  if (args.patch) {
+    const abs = resolve(cwd, args.patch);
+    if (!existsSync3(abs)) {
+      fail(`--patch file not found: ${args.patch}`);
+    }
+    const contents = readFileSync2(abs, "utf8");
+    if (looksLikeSecret(contents)) {
+      fail(
+        `Refusing to upload ${args.patch}: it looks like it contains secrets. Drop --patch to create a fresh privacy page instead.`
+      );
+    }
+    mode = "patch";
+    target = { path: args.patch, contents };
+  }
+  log.info(`Detected ${pc.bold(ctx.framework)} (mode: ${mode})`);
+  spin.start("Building your install plan");
+  let plan;
+  try {
+    plan = await postPlan(api, token, {
+      framework: ctx.framework,
+      mode,
+      deps: ctx.deps,
+      paths: ctx.paths,
+      target
+    });
+  } catch (err) {
+    spin.stop("Could not build a plan");
+    if (err instanceof WizardApiError && err.status === 503) {
+      fail("SCADABLE could not generate a plan right now (model unavailable). Try again shortly.");
+    }
+    if (err instanceof WizardNetworkError) {
+      fail(`Could not reach the SCADABLE API at ${api}. ${reason(err)}`);
+    }
+    fail(`Could not build a plan: ${reason(err)}`);
+  }
+  spin.stop("Plan ready");
+  const pm = detectPackageManager(cwd);
+  const packages = resolvePackages(plan.install);
+  const installCmd = formatInstall(pm, packages);
+  showPlan(installCmd, plan.edits, plan.deterministic);
+  if (args.dryRun) {
+    outro(pc.dim("Dry run complete. Nothing was written."));
+    return;
+  }
+  if (!args.yes) {
+    const ok = await confirm({ message: "Apply this plan?" });
+    if (isCancel(ok) || !ok) {
+      cancel("No changes made.");
+      process.exit(0);
+    }
+  }
+  spin.start(`Installing with ${pm}`);
+  try {
+    runInstall(cwd, pm, packages);
+    spin.stop("Dependency installed");
+  } catch (err) {
+    spin.stop("Install failed");
+    fail(`Could not run "${installCmd}": ${reason(err)}`);
+  }
+  for (const edit of plan.edits) {
+    const abs = resolve(cwd, edit.path);
+    if (edit.action === "create" && existsSync3(abs) && !args.yes) {
+      const overwrite = await confirm({ message: `${edit.path} already exists. Overwrite it?` });
+      if (isCancel(overwrite) || !overwrite) {
+        log.warn(`Skipped ${edit.path}`);
+        continue;
+      }
+    }
+    writeEdit(cwd, edit);
+    log.success(`${edit.action === "patch" ? "Patched" : "Wrote"} ${edit.path}`);
+  }
+  spin.start("Finishing setup");
+  try {
+    await postComplete(api, token);
+    spin.stop("Marked connected");
+  } catch (err) {
+    spin.stop("Setup written, but could not notify SCADABLE");
+    log.warn(`The files are in place, but marking the connection failed: ${reason(err)}`);
+  }
+  outro(
+    `${pc.green("Done.")} ${plan.route_hint}
+  ${pc.dim("Public id:")} ${plan.public_id}`
+  );
+}
+main().catch((err) => {
+  log.error(reason(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@scadable/wizard",
+  "version": "0.1.0",
+  "description": "The SCADABLE setup wizard. Wires SCADABLE into your codebase (privacy policy now, more to come).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "scadable-wizard": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "scadable",
+    "privacy",
+    "privacy-policy",
+    "compliance",
+    "wizard",
+    "cli",
+    "setup"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scadable/sdk.git",
+    "directory": "wizard"
+  }
+}