tracelines 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# tracelines (CLI)
+
+A tiny, **zero-dependency** command-line client for
+[tracelines](https://github.com/Prekzursil/tracelines) — find the nearest **official** Street View
+car coverage (never a photosphere), list historical captures, and extract coverage to GeoJSON, all
+through the hosted proxy. No Python needed.
+
+```bash
+npx tracelines nearest 44.435072 26.050430
+# → Ui8V1HlfwJBw8pnmoShJfw  launch  2024-07  65.1m  (third-party: false)
+#   https://www.google.com/maps/@?api=1&map_action=pano&pano=Ui8V1HlfwJBw8pnmoShJfw
+```
+
+## Commands
+
+```
+tracelines nearest <lat> <lon> [--trekker]
+tracelines historical <lat> <lon>
+tracelines extract (--bbox W,S,E,N | --area NAME) [--sources google,mapillary] [--precision] [--out file.geojson]
+tracelines probe --bbox W,S,E,N [--sources google]
+tracelines health
+```
+
+Options: `--proxy <url>` (or env `TRACELINES_PROXY`; defaults to the hosted demo) · `--json` ·
+`-h/--help` · `-v/--version`. Requires **Node ≥ 18** (uses the built-in `fetch`).
+
+## The default proxy is a shared demo
+
+The default endpoint is the hosted demo proxy — **hardened and rate-limited**, it may sleep or cap
+the bbox size, and it extracts Google from a shared IP (a ToS gray area). For real work, run your
+own and point at it:
+
+```bash
+TRACELINES_PROXY=https://your-proxy npx tracelines extract --bbox 26.09,44.45,26.11,44.46 --out out.geojson
+```
+
+See **[Deploy your own proxy (free)](https://github.com/Prekzursil/tracelines#deploy-your-own-proxy-free)**.
+
+The **HARD RULE** holds everywhere: output is only genuine official car coverage — never a
+photosphere/photopet. Prefer pure, reproducible extraction? Use the
+[Python package](https://pypi.org/project/tracelines/) (`pip install tracelines`), which runs the
+engine locally instead of via a proxy.
+
+## License
+
+AGPL-3.0-or-later.

package/bin/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// tracelines — a tiny CLI over the hosted tracelines proxy.
+// Nearest OFFICIAL Street View car coverage (never a photosphere), historical stacks,
+// area extraction to GeoJSON, and density probes. Zero dependencies (Node >=18 global fetch).
+import { writeFileSync } from "node:fs";
+
+const VERSION = "0.2.0";
+const DEFAULT_PROXY =
+  process.env.TRACELINES_PROXY || "https://tracelines-proxy-ttfjfqlcwq-ew.a.run.app";
+
+const HELP = `tracelines ${VERSION} — nearest OFFICIAL Street View coverage (never photospheres)
+
+Usage:
+  tracelines nearest <lat> <lon> [--trekker]
+  tracelines historical <lat> <lon>
+  tracelines extract (--bbox W,S,E,N | --area NAME) [--sources google,mapillary] [--precision] [--out file.geojson]
+  tracelines probe --bbox W,S,E,N [--sources google]
+  tracelines health
+
+Options:
+  --proxy <url>   Proxy base URL (env TRACELINES_PROXY; default: the hosted demo)
+  --json          Print raw JSON
+  -h, --help      Show this help
+  -v, --version   Show version
+
+The default hosted proxy is hardened & rate-limited and may sleep or cap bbox size.
+Run your own for real work: https://github.com/Prekzursil/tracelines#deploy-your-own-proxy-free`;
+
+const BOOL_FLAGS = new Set(["trekker", "precision", "json", "help", "version"]);
+
+function parseArgs(argv) {
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h") flags.help = true;
+    else if (a === "-v") flags.version = true;
+    else if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (BOOL_FLAGS.has(key)) flags[key] = true;
+      else flags[key] = argv[++i];
+    } else pos.push(a);
+  }
+  return { flags, pos };
+}
+
+function die(msg, code = 1) {
+  console.error(`tracelines: ${msg}`);
+  process.exit(code);
+}
+
+function num(x, name) {
+  const n = Number(x);
+  if (x === undefined || !Number.isFinite(n)) die(`${name} must be a number (got ${JSON.stringify(x)})`);
+  return n;
+}
+
+async function req(base, path, { method = "GET", body } = {}) {
+  const url = base.replace(/\/$/, "") + path;
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: body ? { "content-type": "application/json" } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    return die(`could not reach the proxy at ${base} (${e.message}). Is it running / awake?`);
+  }
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = text;
+  }
+  if (!res.ok) {
+    const detail = data && data.detail ? data.detail : String(text).slice(0, 200);
+    return die(`proxy ${res.status}: ${detail}`);
+  }
+  return data;
+}
+
+async function main() {
+  const { flags, pos } = parseArgs(process.argv.slice(2));
+  if (flags.version) return console.log(VERSION);
+  const cmd = pos[0];
+  if (!cmd || flags.help) return console.log(HELP);
+  const base = flags.proxy || DEFAULT_PROXY;
+  const raw = Boolean(flags.json);
+
+  if (cmd === "nearest") {
+    const lat = num(pos[1], "lat");
+    const lon = num(pos[2], "lon");
+    const q = new URLSearchParams({ lat, lon, include_trekker: Boolean(flags.trekker) });
+    const d = await req(base, `/nearest?${q}`);
+    if (raw) return console.log(JSON.stringify(d, null, 2));
+    if (!d.id) return console.log("No official coverage nearby.");
+    console.log(`${d.id}  ${d.sv_source}  ${d.date || "?"}  ${d.distance_m}m  (third-party: ${d.is_third_party})`);
+    console.log(d.streetview_url);
+  } else if (cmd === "historical") {
+    const lat = num(pos[1], "lat");
+    const lon = num(pos[2], "lon");
+    const d = await req(base, `/historical?lat=${lat}&lon=${lon}`);
+    if (raw) return console.log(JSON.stringify(d, null, 2));
+    console.log(`${d.count} capture(s):`);
+    for (const p of d.panos) console.log(`  ${p.date || "?"}  ${p.sv_source || ""}  ${p.id}`);
+  } else if (cmd === "extract") {
+    if (!flags.bbox && !flags.area) die("extract needs --bbox W,S,E,N or --area NAME");
+    const body = {
+      bbox: flags.bbox || null,
+      area: flags.area || null,
+      sources: (flags.sources || "google").split(",").map((s) => s.trim()).filter(Boolean),
+      precision: Boolean(flags.precision),
+      include_trekker: Boolean(flags.trekker),
+    };
+    if (flags["min-run"]) body.min_run = num(flags["min-run"], "--min-run");
+    const fc = await req(base, "/extract", { method: "POST", body });
+    if (flags.out) {
+      writeFileSync(flags.out, JSON.stringify(fc));
+      const km = fc.properties?.stats?.total_km;
+      console.log(`Wrote ${fc.features?.length ?? 0} features to ${flags.out}${km ? ` (${km} km)` : ""}`);
+    } else {
+      console.log(JSON.stringify(fc, null, raw ? 2 : 0));
+    }
+  } else if (cmd === "probe") {
+    if (!flags.bbox) die("probe needs --bbox W,S,E,N");
+    const q = new URLSearchParams({ bbox: flags.bbox, sources: flags.sources || "google" });
+    const d = await req(base, `/probe?${q}`);
+    console.log(JSON.stringify(d, null, 2));
+  } else if (cmd === "health") {
+    const d = await req(base, "/health");
+    console.log(JSON.stringify(d, null, 2));
+  } else {
+    die(`unknown command ${JSON.stringify(cmd)}. Run: tracelines --help`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tracelines",
+  "version": "0.2.0",
+  "description": "CLI for tracelines — nearest OFFICIAL Street View car coverage (never photospheres), historical stacks, and GeoJSON extraction via the hosted proxy.",
+  "type": "module",
+  "bin": {
+    "tracelines": "bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "street-view",
+    "streetlevel",
+    "mapillary",
+    "kartaview",
+    "coverage",
+    "geojson",
+    "gis",
+    "panorama",
+    "cli"
+  ],
+  "homepage": "https://prekzursil.github.io/tracelines/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prekzursil/tracelines.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/Prekzursil/tracelines/issues"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Prekzursil"
+}