@uptimizr/collector-server 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,169 @@
+# @uptimizr/collector-server
+
+The public-facing **ingestion + query API** (Fastify) for the OSS data-collector.
+All client input is untrusted and validated against [`@uptimizr/schema`](../../packages/schema)
+at the boundary. Route handlers stay thin; storage logic lives in
+[`@uptimizr/db`](../../packages/db) behind a swappable `CollectorStore`.
+
+## Self-host (npm)
+
+Run the collector straight from npm — no repo clone, no Docker, no external
+database (the OSS default store is a single DuckDB file). The store is
+created and migrated automatically.
+
+```bash
+# 1. One-time setup: generates a visitor-hash secret, creates the DuckDB store,
+#    mints a first project + API key, and writes a local .env.
+npx -p @uptimizr/collector-server uptimizr init "My Project"
+
+# 2. Start the ingestion + query API (reads the generated .env; 0.0.0.0:4318).
+npx -p @uptimizr/collector-server uptimizr serve
+```
+
+`init` prints a **`projectId`** and a one-time **API key**. Give the `projectId`
+and this server's URL (the **`endpoint`**) to your client SDK (e.g.
+`@uptimizr/babylon`); use the **API key** (`x-api-key`) for the query routes /
+dashboard. Mint more projects later with
+`npx -p @uptimizr/collector-server uptimizr new-project "<name>"`.
+
+### All-in-one: serve the dashboard too
+
+The collector can also serve a pre-built static dashboard from its own origin, so
+a single process handles ingestion, queries, **and** the UI:
+
+```bash
+# Build the dashboard as a static bundle (emits oss/apps/dashboard/out).
+pnpm --filter @uptimizr/dashboard build:static
+
+# Point the collector at it and start (relative paths are resolved from CWD).
+export COLLECTOR_DASHBOARD_DIR="./oss/apps/dashboard/out"
+npx -p @uptimizr/collector-server uptimizr serve
+```
+
+The dashboard then loads at the collector's URL (e.g. `http://localhost:4318`) and
+defaults its collector target to that same origin — no build-time URL to bake.
+Deep links (`/projects/:id/...`) are served the SPA entry so refresh / shared
+links resolve. Leave `COLLECTOR_DASHBOARD_DIR` unset to keep the collector
+headless.
+
+### Manual setup (without the CLI)
+
+Prefer to wire it yourself? The CLI is optional — set the environment directly:
+
+```bash
+# A daily-rotating secret for the cookieless visitor hash is REQUIRED.
+export VISITOR_HASH_SECRET="$(openssl rand -hex 32)"
+# Browser origins allowed to call the collector (your 3D app + any tools):
+export COLLECTOR_CORS_ORIGINS="https://your-app.example.com"
+# Where the DuckDB file lives (created if missing):
+export DUCKDB_PATH="./uptimizr.duckdb"
+
+# Mint a project + API key (prints PROJECT_ID and a utk_… key once).
+npx -p @uptimizr/db uptimizr-db-new-project "My Project"
+
+# Start the ingestion + query API (defaults to 0.0.0.0:4318).
+npx -p @uptimizr/collector-server uptimizr-collector
+```
+
+Full configuration is in [Configuration](#configuration) below. For a production
+deployment, run a single instance behind your own TLS / reverse proxy and persist
+the DuckDB file on a volume (DuckDB is single-writer — one collector process per
+file; back up by copying the file).
+
+> Installing as a dependency instead of via `npx`? `npm install @uptimizr/collector-server`
+> exposes the `uptimizr` CLI (`init` / `serve` / `new-project` / `migrate`) plus
+> the legacy `uptimizr-collector` bin; `@uptimizr/db` exposes
+> `uptimizr-db-new-project` / `uptimizr-db-migrate`.
+
+## Endpoints
+
+### Ingestion
+
+- `POST /api/v1/collect` — accepts a batched `collectRequest`. Validates → enriches
+  (server-set cookieless `visitorId = hash(ip + ua + dailySalt)`, raw IP never stored)
+  → inserts into the configured `CollectorStore` (DuckDB by default).
+
+### Query (require `x-api-key`)
+
+Aggregations are computed **at query time** (v1) — including the heatmap/perf
+aggregates, which run directly in the OSS DuckDB store. Every route is scoped to
+the project the API key resolves to.
+
+- `GET /api/v1/sessions`
+- `GET /api/v1/heatmaps/pointer`
+- `GET /api/v1/heatmaps/camera`
+- `GET /api/v1/meshes/top`
+- `GET /api/v1/perf`
+- `GET /api/v1/sessions/:id/events` — ordered replay timeline, **gated by**
+  `ENABLE_RAW_SESSION_RETENTION` (returns `403` when disabled).
+
+Shared query params: `since`, `until` (epoch ms), `bins`, `limit`.
+
+- `GET /health` — liveness probe.
+
+## Security
+
+`@fastify/helmet`, `@fastify/cors` (restricted to `COLLECTOR_CORS_ORIGINS`), and
+`@fastify/rate-limit`. Secrets and raw IPs are never logged. The server fails fast
+if `VISITOR_HASH_SECRET` is missing.
+
+### Authentication: which endpoints need a key
+
+| Endpoint group                 | Auth               | Why                                                                                                                                                     |
+| ------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /api/v1/collect`         | **None (keyless)** | Runs in untrusted browsers; a key shipped to the client is not a secret. Ingestion is open by design and protected by validation + rate limits instead. |
+| All query routes (`/api/v1/*`) | `x-api-key`        | Read access is scoped to the project the key resolves to.                                                                                               |
+| `GET /health`                  | None               | Liveness probe.                                                                                                                                         |
+
+### Threat model for keyless ingestion
+
+Because `POST /api/v1/collect` accepts unauthenticated input, every request is treated as hostile:
+
+- **Validated at the boundary.** Bodies are parsed against [`@uptimizr/schema`](../../packages/schema);
+  invalid batches are rejected with `400`. The raw IP is used only to derive the cookieless
+  visitor hash and is never stored.
+- **Bounded payloads.** The schema caps batch size and every free-text / collection field (see
+  the [_Ingestion payload bounds_](../../packages/schema/README.md#ingestion-payload-bounds)
+  table). An oversized field rejects the batch, so a single request can't smuggle a huge blob or
+  exhaust memory/storage. Connectors truncate locally before sending.
+- **Rate limited.** `@fastify/rate-limit` (`COLLECTOR_RATE_LIMIT_MAX` /
+  `COLLECTOR_RATE_LIMIT_WINDOW_MS`) caps requests per client.
+- **Residual risk.** A keyless endpoint can still receive spoofed or spammy events scoped to a
+  known `projectId`. This is an accepted trade-off for cookieless, client-side capture; deployers
+  who need stronger guarantees can front the collector with their own auth/WAF and tighten the
+  CORS allowlist.
+
+## Configuration
+
+Environment-driven (see [`.env.example`](../../../.env.example)): `COLLECTOR_HOST`,
+`COLLECTOR_PORT`, `COLLECTOR_CORS_ORIGINS`, `VISITOR_HASH_SECRET`,
+`ENABLE_RAW_SESSION_RETENTION`, `COLLECTOR_DASHBOARD_DIR` (optional; serve a
+static dashboard all-in-one — see [above](#all-in-one-serve-the-dashboard-too)).
+
+The storage backend is chosen with `COLLECTOR_STORE`:
+
+- `duckdb` **(default)** — the OSS single-file store (events **and** metadata in one
+  DuckDB file at `DUCKDB_PATH`, default `./data/uptimizr.duckdb`). No
+  external database service to run. DuckDB is single-writer, so run one collector
+  instance per file; back up by copying the file.
+- `memory` — a dependency-free in-memory store for local dev / E2E only (seed its
+  project/key via `COLLECTOR_MEMORY_PROJECT_ID` / `COLLECTOR_MEMORY_API_KEY`).
+
+The two-store ClickHouse + Postgres path is an optional scale tier and is not required to self-host the OSS collector.
+
+## Develop
+
+```bash
+pnpm --filter @uptimizr/collector-server dev    # tsx watch
+pnpm --filter @uptimizr/collector-server test   # vitest (inject + fake store)
+pnpm --filter @uptimizr/collector-server build
+```
+
+The data layer is abstracted by `CollectorStore`, so tests run against a fake store
+with `app.inject()` — no live database required. Local end-to-end runs use the
+default DuckDB store (a single file, no service to start); the ClickHouse + Postgres
+stack in `infra/docker` backs the optional scale tier only.
+
+## License
+
+[Apache-2.0](./LICENSE) © Uptimizr.

package/dist/app.d.ts

@@ -0,0 +1,22 @@
+import { type FastifyInstance } from "fastify";
+import type { CollectorConfig } from "./config.js";
+import type { CollectorStore } from "./store.js";
+import { type LiveBus } from "./liveBus.js";
+export interface BuildAppDeps {
+    store: CollectorStore;
+    config: CollectorConfig;
+    /**
+     * In-process live event bus (ADR 0032). Injectable for tests; a default
+     * in-process bus is created from `config.liveWindowMs` when omitted.
+     */
+    liveBus?: LiveBus;
+    /** Pass `true` (or Fastify logger options) to enable request logging. */
+    logger?: boolean;
+}
+/**
+ * Build the collector Fastify instance. Pure factory — takes its dependencies so
+ * it can be exercised with `app.inject()` and a fake store in tests, and so the
+ * store/DB stays swappable.
+ */
+export declare function buildApp(deps: BuildAppDeps): Promise<FastifyInstance>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAIA,OAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAMxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAM3D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0BD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CA8D3E"}

package/dist/app.js

@@ -0,0 +1,96 @@
+import cors from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import rateLimit from "@fastify/rate-limit";
+import fastifyStatic from "@fastify/static";
+import Fastify, {} from "fastify";
+import { serializerCompiler, validatorCompiler, } from "fastify-type-provider-zod";
+import { createLiveBus } from "./liveBus.js";
+import { buildDashboardCsp } from "./csp.js";
+import { collectRoutes } from "./routes/collect.js";
+import { liveRoutes } from "./routes/live.js";
+import { queryRoutes } from "./routes/query.js";
+/**
+ * Strip the live-SSE `?token=` from a logged URL. The token is a short-lived
+ * bearer credential; it must never land in access logs (or proxy logs).
+ */
+function redactToken(url) {
+    return url.replace(/([?&]token=)[^&]*/gi, "$1[redacted]");
+}
+/**
+ * Request logger options that (a) never log the raw client IP / remote address
+ * (privacy model — ADR 0003) and (b) redact the live-SSE token from URLs. Used
+ * when `logger: true`; explicit logger options are passed through untouched.
+ */
+function loggerOptions(logger) {
+    if (logger !== true)
+        return logger ?? false;
+    return {
+        serializers: {
+            req(request) {
+                return { method: request.method, url: redactToken(request.url) };
+            },
+        },
+    };
+}
+/**
+ * Build the collector Fastify instance. Pure factory — takes its dependencies so
+ * it can be exercised with `app.inject()` and a fake store in tests, and so the
+ * store/DB stays swappable.
+ */
+export async function buildApp(deps) {
+    const { store, config } = deps;
+    const liveBus = deps.liveBus ?? createLiveBus({ windowMs: config.liveWindowMs });
+    const app = Fastify({
+        logger: loggerOptions(deps.logger),
+        // Honor `X-Forwarded-*` only when explicitly configured, so the visitor hash
+        // and rate-limit bucket key on the real client IP behind a TLS proxy.
+        trustProxy: config.trustProxy,
+        // Cap request bodies; ingestion batches are small JSON documents.
+        bodyLimit: config.bodyLimit,
+    }).withTypeProvider();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    // When serving the bundled static dashboard, apply a Content-Security-Policy
+    // tuned for a Next.js static export: inline bootstrap scripts are pinned by
+    // SHA-256 hash (a static export cannot mint per-request nonces), and the rest
+    // is locked down. `COLLECTOR_CSP=off` reverts to no policy as an escape hatch.
+    const contentSecurityPolicy = config.dashboardDir && config.cspMode === "strict"
+        ? buildDashboardCsp(config.dashboardDir, config.corsOrigins)
+        : false;
+    await app.register(helmet, config.dashboardDir ? { contentSecurityPolicy } : {});
+    await app.register(cors, {
+        origin: config.corsOrigins.length > 0 ? config.corsOrigins : false,
+        // @fastify/cors defaults `methods` to GET,HEAD,POST — which omits PUT and so
+        // breaks the browser preflight for scene-proxy registration
+        // (PUT /api/v1/scenes/:id/representation). List the verbs the HTTP API uses.
+        methods: ["GET", "HEAD", "POST", "PUT"],
+    });
+    await app.register(rateLimit, {
+        max: config.rateLimitMax,
+        timeWindow: config.rateLimitWindowMs,
+    });
+    app.get("/health", async () => ({ status: "ok" }));
+    await app.register(collectRoutes, { store, config, liveBus });
+    await app.register(liveRoutes, { store, config, liveBus });
+    await app.register(queryRoutes, { store, config });
+    // All-in-one: serve a pre-built static dashboard from `dashboardDir`. The API
+    // routes above (`/health`, `/api/v1/*`) are matched first; everything else
+    // falls through to the static files. Unmatched GET navigations (the SPA deep
+    // links `/projects/:id`...) are served `index.html` so refresh/shared links
+    // resolve client-side.
+    if (config.dashboardDir) {
+        await app.register(fastifyStatic, {
+            root: config.dashboardDir,
+            prefix: "/",
+            wildcard: false,
+        });
+        app.setNotFoundHandler((req, reply) => {
+            if (req.method === "GET" && !req.url.startsWith("/api/v1/") && req.url !== "/health") {
+                return reply.type("text/html").sendFile("index.html");
+            }
+            return reply.code(404).send({ error: "Not Found" });
+        });
+    }
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createDuckdbClient, duckdbCreateApiKey, duckdbCreateProject, migrateDuckdb, readDbSettings, } from "@uptimizr/db";
+/**
+ * Unified `uptimizr` CLI (ADR 0029) — collapses the multi-step npm self-host
+ * (`export VISITOR_HASH_SECRET` → `uptimizr-db-new-project` → `uptimizr-collector`)
+ * into `uptimizr init && uptimizr serve`.
+ *
+ * Subcommands:
+ * - `init`               — generate a visitor-hash secret, create the DuckDB
+ *                          store, mint a first project + API key, and write `.env`.
+ * - `serve` (default)    — run the ingestion + query API (see {@link serve}).
+ * - `new-project <name>` — mint an additional project + API key.
+ * - `migrate`            — apply DuckDB store migrations.
+ *
+ * The OSS store is DuckDB — no Docker, no external database (ADR 0020).
+ */
+const ENV_FILE = resolve(process.cwd(), ".env");
+/** Load a local `.env` (Node 22 built-in) so `serve`/`migrate` see config without a wrapper. */
+function loadLocalEnv() {
+    if (existsSync(ENV_FILE)) {
+        process.loadEnvFile(ENV_FILE);
+    }
+}
+/** Join positional args into a project name, dropping a stray `--` separator. */
+function nameArg(args) {
+    return args
+        .filter((a) => a !== "--")
+        .join(" ")
+        .trim();
+}
+function renderEnv(secret) {
+    return `${[
+        "# Uptimizr collector configuration (generated by 'uptimizr init').",
+        "# OSS default store is DuckDB — no Docker, no external database.",
+        "",
+        `VISITOR_HASH_SECRET=${secret}`,
+        "COLLECTOR_STORE=duckdb",
+        "DUCKDB_PATH=./data/uptimizr.duckdb",
+        "COLLECTOR_PORT=4318",
+    ].join("\n")}\n`;
+}
+/** Persist a generated secret so `serve` works on the next run. */
+function ensureSecretPersisted(secret, generated) {
+    if (!existsSync(ENV_FILE)) {
+        writeFileSync(ENV_FILE, renderEnv(secret));
+        console.error(`✓ wrote ${ENV_FILE}`);
+        return;
+    }
+    if (!generated)
+        return;
+    const content = readFileSync(ENV_FILE, "utf8");
+    if (/^VISITOR_HASH_SECRET=/m.test(content))
+        return;
+    const sep = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+    writeFileSync(ENV_FILE, `${content}${sep}VISITOR_HASH_SECRET=${secret}\n`);
+    console.error(`✓ added VISITOR_HASH_SECRET to ${ENV_FILE}`);
+}
+async function cmdInit(name) {
+    loadLocalEnv();
+    let secret = process.env.VISITOR_HASH_SECRET;
+    const generated = !secret;
+    if (!secret) {
+        secret = randomBytes(32).toString("hex");
+        process.env.VISITOR_HASH_SECRET = secret;
+    }
+    const db = await createDuckdbClient(readDbSettings().duckdb.path);
+    await migrateDuckdb(db);
+    const project = await duckdbCreateProject(db, name);
+    const { key } = await duckdbCreateApiKey(db, project.id);
+    await db.close();
+    ensureSecretPersisted(secret, generated);
+    const port = Number(process.env.COLLECTOR_PORT ?? 4318);
+    console.error("\n✓ Uptimizr is ready.");
+    console.error(`  Project:  ${project.id} (${project.name})`);
+    console.error(`  API key:  ${key}  (shown once — put it in your app config)`);
+    console.error(`  Endpoint: http://localhost:${port}/api/v1`);
+    console.error("\nNext: uptimizr serve");
+}
+async function cmdNewProject(name) {
+    loadLocalEnv();
+    const db = await createDuckdbClient(readDbSettings().duckdb.path);
+    await migrateDuckdb(db);
+    const project = await duckdbCreateProject(db, name);
+    const { key } = await duckdbCreateApiKey(db, project.id);
+    await db.close();
+    console.error(`✓ project created: ${project.id} (${project.name})`);
+    console.error(`  API key (shown once): ${key}`);
+    process.stdout.write(`${JSON.stringify({ projectId: project.id, name: project.name, apiKey: key })}\n`);
+}
+async function cmdMigrate() {
+    loadLocalEnv();
+    const db = await createDuckdbClient(readDbSettings().duckdb.path);
+    await migrateDuckdb(db);
+    await db.close();
+    console.error("✓ migrations applied");
+}
+function printUsage() {
+    console.error([
+        "uptimizr — self-host the OSS 3D-analytics collector (DuckDB, no Docker).",
+        "",
+        "Usage:",
+        "  uptimizr init [name]          generate a secret, create the store, mint a project + key, write .env",
+        "  uptimizr serve                run the ingestion + query API (default)",
+        "  uptimizr new-project <name>   mint an additional project + API key",
+        "  uptimizr migrate              apply store migrations",
+        "  uptimizr help                 show this help",
+        "",
+        "Quick start:  uptimizr init  &&  uptimizr serve",
+    ].join("\n"));
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case undefined:
+        case "serve": {
+            loadLocalEnv();
+            const { serve } = await import("./serve.js");
+            await serve();
+            return;
+        }
+        case "init":
+            await cmdInit(nameArg(rest) || "Default Project");
+            return;
+        case "new-project":
+            await cmdNewProject(nameArg(rest) || "Project");
+            return;
+        case "migrate":
+            await cmdMigrate();
+            return;
+        case "help":
+        case "--help":
+        case "-h":
+            printUsage();
+            return;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            printUsage();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map