siteward 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# siteward
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add, list and remove [Siteward](https://github.com/sholajegede/siteward) monitors from the terminal. How many monitors you can have follows your plan.
+
+## Install
+
+```bash
+npm install -g siteward
+```
+
+You need Node.js 20 or later. To run it once without installing, use `npx siteward`.
+
+## Start
+
+This tool talks to a Siteward server. You deploy that server yourself, from the [repository](https://github.com/sholajegede/siteward), or use the address of one that you have an account on.
+
+```bash
+siteward login --url https://<your-siteward-server>
+siteward add https://example.com "Example"
+siteward list
+```
+
+`login` opens your browser and signs you in through Kinde. The tool never sees your password.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `siteward login [org_code] --url <address>` | Sign in through the browser. Pass an organization code to choose one. |
+| `siteward logout` | Delete the stored token. |
+| `siteward whoami` | Show the organization, the server and when the sign-in ends. |
+| `siteward list` | Show monitors, their state and your plan limit. |
+| `siteward add <url> [name]` | Add a monitor. A plan at its limit answers with an error. |
+| `siteward remove <id>` | Remove a monitor. |
+
+The address of the server is saved after `login`, so later commands need no `--url`.
+
+## Monitor states
+
+| State | Meaning |
+| --- | --- |
+| `active` | The monitor runs. |
+| `paused_plan` | Your plan allows fewer monitors than you have. The newest monitors pause first, and they resume when the limit rises. |
+| `paused_user` | You paused it. A plan change does not resume it. |
+
+## Sign-in and storage
+
+- The tool signs in with OAuth 2.0 and PKCE. It listens on `http://localhost:8976/callback` for the answer, so that address must be an allowed callback URL in your Kinde application.
+- The access token is saved in `~/.config/siteward/credentials.json` (or under `$XDG_CONFIG_HOME`), readable only by you.
+- A token lasts 24 hours. After that, run `siteward login` again. `siteward logout` deletes the file at once.
+
+## Use it in scripts
+
+Set two variables and skip `login`:
+
+```bash
+export SITEWARD_URL=https://<your-siteward-server>
+export SITEWARD_TOKEN=<Kinde access token>
+siteward list
+```
+
+## Errors
+
+| Message | What to do |
+| --- | --- |
+| `Your plan allows N monitors.` | Remove a monitor or upgrade the plan. |
+| `Sign in again.` | The token expired. Run `siteward login`. |
+| `Pass the address of your Siteward` | Add `--url https://<your-siteward-server>` to `login`. |
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { createHash, randomBytes } from "node:crypto";
+import { exec } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+const PORT = 8976;
+const REDIRECT = `http://localhost:${PORT}/callback`;
+const dir = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "siteward");
+const file = join(dir, "credentials.json");
+const b64 = (buf) => buf.toString("base64url");
+const claims = (token) => JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
+async function load() {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function openBrowser(url) {
+    const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? 'start ""' : "xdg-open";
+    exec(`${cmd} "${url}"`, () => undefined);
+}
+/** Signs in through the browser with the same Kinde flow as the dashboard. The tool never sees a password. */
+async function login(args) {
+    const flag = args.indexOf("--url");
+    const url = (flag >= 0 ? args[flag + 1] : process.env.SITEWARD_URL ?? (await load())?.url ?? "").replace(/\/$/, "");
+    if (!url)
+        throw new Error("Pass the address of your Siteward: siteward login --url https://your-siteward.example");
+    const org = args.find((a, i) => a.startsWith("org_") && args[i - 1] !== "--url");
+    const cfgRes = await fetch(`${url}/cli/config`);
+    if (!cfgRes.ok)
+        throw new Error(`Could not read the sign-in settings from ${url} (${cfgRes.status}).`);
+    const { domain, clientId } = (await cfgRes.json());
+    const verifier = b64(randomBytes(32));
+    const state = b64(randomBytes(16));
+    const challenge = b64(createHash("sha256").update(verifier).digest());
+    const auth = new URL(`${domain}/oauth2/auth`);
+    auth.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId,
+        redirect_uri: REDIRECT,
+        scope: "openid profile email",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state,
+        prompt: "login",
+        ...(org ? { org_code: org } : {}),
+    }).toString();
+    const code = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const u = new URL(req.url ?? "/", REDIRECT);
+            if (u.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const ok = u.searchParams.get("state") === state && u.searchParams.get("code");
+            res.writeHead(ok ? 200 : 400, { "content-type": "text/plain" }).end(ok ? "Signed in. You can close this tab." : "Sign-in failed. Run siteward login again.");
+            server.close();
+            ok ? resolve(u.searchParams.get("code")) : reject(new Error(u.searchParams.get("error_description") ?? "The sign-in could not be checked."));
+        });
+        server.on("error", (e) => reject(new Error(`Could not listen on port ${PORT}: ${e.message}`)));
+        server.listen(PORT, "127.0.0.1", () => {
+            console.log("Opening your browser to sign in. If it does not open, go to:\n" + auth.toString());
+            openBrowser(auth.toString());
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error("Timed out after 5 minutes."));
+        }, 300_000).unref();
+    });
+    const tokenRes = await fetch(`${domain}/oauth2/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ grant_type: "authorization_code", client_id: clientId, code, code_verifier: verifier, redirect_uri: REDIRECT }),
+    });
+    if (!tokenRes.ok)
+        throw new Error("Kinde did not accept the sign-in.");
+    const body = (await tokenRes.json());
+    const exp = claims(body.access_token).exp ?? 0;
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, JSON.stringify({ url, token: body.access_token, expires_at: exp * 1000 }), { mode: 0o600 });
+    console.log(`Signed in to ${claims(body.access_token).org_code ?? "your organization"}.`);
+}
+async function session() {
+    const saved = await load();
+    const url = (process.env.SITEWARD_URL ?? saved?.url ?? "").replace(/\/$/, "");
+    const token = process.env.SITEWARD_TOKEN ?? saved?.token ?? "";
+    if (!url || !token)
+        throw new Error("You are not signed in. Run: siteward login --url https://your-siteward.example");
+    if (!process.env.SITEWARD_TOKEN && saved && saved.expires_at < Date.now())
+        throw new Error("Your sign-in has expired. Run: siteward login");
+    return { url, token };
+}
+async function call(method, path, body) {
+    const { url, token } = await session();
+    const res = await fetch(`${url}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, ...(body ? { "content-type": "application/json" } : {}) },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : null;
+    if (res.status === 401)
+        throw new Error("Your sign-in is not valid any more. Run: siteward login");
+    if (!res.ok)
+        throw new Error(data?.error ?? `request failed: ${res.status}`);
+    return data;
+}
+const [command, ...args] = process.argv.slice(2);
+try {
+    if (command === "login") {
+        await login(args);
+    }
+    else if (command === "logout") {
+        await rm(file, { force: true });
+        console.log("Signed out.");
+    }
+    else if (command === "whoami") {
+        const { token, url } = await session();
+        const c = claims(token);
+        console.log(`${c.org_code ?? "no organization"} at ${url}, signed in until ${new Date((c.exp ?? 0) * 1000).toISOString()}`);
+    }
+    else if (command === "list") {
+        const { limits, monitors } = await call("GET", "/api/monitors");
+        console.log(`${monitors.length} of ${limits?.monitors ?? "unlimited"} monitors`);
+        for (const m of monitors)
+            console.log(`${m.status.padEnd(12)} ${m.name.padEnd(24)} ${m.url}  ${m.id}`);
+    }
+    else if (command === "add" && args[0]) {
+        const m = await call("POST", "/api/monitors", { url: args[0], name: args[1] });
+        console.log(`added ${m.name}`);
+    }
+    else if (command === "remove" && args[0]) {
+        await call("DELETE", `/api/monitors/${args[0]}`);
+        console.log("removed");
+    }
+    else {
+        console.log("Usage: siteward login [org_code] --url <address> | logout | whoami | list | add <url> [name] | remove <id>");
+        process.exitCode = command ? 1 : 0;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "siteward",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Add, list and remove Siteward monitors from the terminal",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "siteward": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sholajegede/siteward.git"
+  },
+  "keywords": [
+    "uptime",
+    "monitoring",
+    "cli",
+    "kinde",
+    "cloudflare"
+  ],
+  "homepage": "https://github.com/sholajegede/siteward#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}