@promptowl/contextnest-community 0.1.0-alpha.2 → 1.0.0

package/CONFIGURATION.md

@@ -1,118 +1,118 @@
-# Configuration
-
-All server configuration is driven by environment variables. Set them in your shell, in a `.env` file, in a Docker image, or via your process manager — however you deploy the rest of your stack.
-
-## Auth modes
-
-The server supports two authentication modes. You pick one per instance with `AUTH_MODE`.
-
-### `AUTH_MODE=key` (default)
-
-Every request requires an `Authorization: Bearer cnst_...` header. Use this for any multi-user or internet-facing deployment.
-
-- Users register via `POST /auth/register` (email + password) or log in with PromptOwl via `POST /auth/device` → `POST /auth/promptowl`.
-- API keys are per-user (`cnst_<64-hex>`) and can be scoped to a single nest for service-account use.
-- Rate-limited login / register / device-auth endpoints (sliding window, per IP + per email).
-- First PromptOwl-authenticated user becomes the server admin (atomic claim). Admin can invite teammates at `POST /auth/invite`.
-
-Clients include the token on every request:
-
-```bash
-curl -H 'Authorization: Bearer cnst_<your-token>' http://your-server/nests
-```
-
-### `AUTH_MODE=open`
-
-No authentication required. Every request is attributed to the anonymous admin user (`00000000-...`). Everyone effectively owns every anon-created nest.
-
-**Use this only when:**
-- You're running locally for yourself (`bind 127.0.0.1`), or
-- You're on a trusted LAN and don't care about access controls, or
-- You're behind an upstream reverse proxy that already authenticates.
-
-**Don't use this when:**
-- The port is reachable from the public internet
-- Multiple people share the deployment and need isolated data
-- You need audit trails (every write shows up under "anonymous admin")
-
-The server prints a loud warning at startup when `AUTH_MODE=open` is active.
-
----
-
-## Full env var reference
-
-| Var | Default | Purpose |
-|---|---|---|
-| `PORT` | `3838` | HTTP port the server listens on. |
-| `DATA_ROOT` | `./data` (relative to cwd) | Root directory for SQLite DB + nest filesystem vaults. Set to an absolute path in production so it's independent of where you `cd`'d from. |
-| `DATABASE_PATH` | `$DATA_ROOT/community.db` | Override the SQLite file location explicitly. |
-| `AUTH_MODE` | `key` | `key` or `open`. See above. |
-| `PROMPTOWL_API_URL` | `https://app.promptowl.ai` | PromptOwl's API origin — used for device auth, license validation, telemetry. Override for air-gapped or test setups. |
-| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community Server license key (`pk_...`). Unlicensed instances still run but some features may be limited. |
-| `TELEMETRY_ENABLED` | `"true"` (set to `"false"` to disable) | Batched, anonymized usage events sent to PromptOwl. Off disables the loop entirely. |
-| `TELEMETRY_INTERVAL_MS` | `3600000` (1 hour) | How often buffered telemetry is flushed to PromptOwl. |
-| `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
-| `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. |
-
----
-
-## Typical deployments
-
-### Local dev / single user
-
-```bash
-AUTH_MODE=open DATA_ROOT=./my-data pnpm dev
-```
-
-Or the default dev mode if `pnpm dev` already sets `AUTH_MODE=open` in your scripts.
-
-### Team / multi-user behind a reverse proxy
-
-```bash
-AUTH_MODE=key \
-CORS_ORIGINS="https://team.example.com,https://admin.example.com" \
-DATA_ROOT=/var/lib/contextnest \
-PROMPTOWL_KEY=pk_... \
-pnpm start
-```
-
-Terminate TLS at the proxy, forward `X-Forwarded-For` and `X-Real-IP` headers (the rate limiter reads them), and bind the server to `127.0.0.1` so only the proxy can reach it.
-
-### Hosted / commercial SaaS
-
-Same as team, plus:
-- Run N instances behind a load balancer sharing a network-attached `DATA_ROOT` (note: SQLite + shared filesystem is not a great long-term story — migrate to the MongoDB storage adapter when scaling beyond one box).
-- Set `TELEMETRY_ENABLED=true` and a valid `PROMPTOWL_KEY` so usage rolls up to PromptOwl.
-- Rotate keys regularly via `DELETE /auth/keys/:id` + `POST /auth/keys`.
-
----
-
-## access.yaml (optional, open + key mode)
-
-Drop an `access.yaml` at `$DATA_ROOT/access.yaml` to add a server-level ABAC layer — useful even in key mode for super-admins and group-based defaults.
-
-```yaml
-mode: restricted
-allowed_users:
-  - "*.acme.com"                # email wildcard — anyone @acme.com
-  - "partner@vendor.com"         # exact match
-super_admins:
-  - "ceo@acme.com"               # always allowed on every nest
-groups:
-  engineering:
-    default_permission: write
-    members:
-      - "*.eng.acme.com"
-  viewers:
-    default_permission: read
-    members:
-      - "*.contractor.acme.com"
-```
-
-See `STEWARDSHIP.md` for how super-admins and groups interact with per-nest stewardship.
-
----
-
-## Reload
-
-Changing env vars requires a restart — the server reads them at boot. `tsx watch` in dev will pick up code changes automatically but not env changes.
+# Configuration
+
+All server configuration is driven by environment variables. Set them in your shell, in a `.env` file, in a Docker image, or via your process manager — however you deploy the rest of your stack.
+
+## Auth modes
+
+The server supports two authentication modes. You pick one per instance with `AUTH_MODE`.
+
+### `AUTH_MODE=key` (default)
+
+Every request requires an `Authorization: Bearer cnst_...` header. Use this for any multi-user or internet-facing deployment.
+
+- Users register via `POST /auth/register` (email + password) or log in with PromptOwl via `POST /auth/device` → `POST /auth/promptowl`.
+- API keys are per-user (`cnst_<64-hex>`) and can be scoped to a single nest for service-account use.
+- Rate-limited login / register / device-auth endpoints (sliding window, per IP + per email).
+- First PromptOwl-authenticated user becomes the server admin (atomic claim). Admin can invite teammates at `POST /auth/invite`.
+
+Clients include the token on every request:
+
+```bash
+curl -H 'Authorization: Bearer cnst_<your-token>' http://your-server/nests
+```
+
+### `AUTH_MODE=open`
+
+No authentication required. Every request is attributed to the anonymous admin user (`00000000-...`). Everyone effectively owns every anon-created nest.
+
+**Use this only when:**
+- You're running locally for yourself (`bind 127.0.0.1`), or
+- You're on a trusted LAN and don't care about access controls, or
+- You're behind an upstream reverse proxy that already authenticates.
+
+**Don't use this when:**
+- The port is reachable from the public internet
+- Multiple people share the deployment and need isolated data
+- You need audit trails (every write shows up under "anonymous admin")
+
+The server prints a loud warning at startup when `AUTH_MODE=open` is active.
+
+---
+
+## Full env var reference
+
+| Var | Default | Purpose |
+|---|---|---|
+| `PORT` | `3838` | HTTP port the server listens on. |
+| `DATA_ROOT` | `./data` (relative to cwd) | Root directory for SQLite DB + nest filesystem vaults. Set to an absolute path in production so it's independent of where you `cd`'d from. |
+| `DATABASE_PATH` | `$DATA_ROOT/community.db` | Override the SQLite file location explicitly. |
+| `AUTH_MODE` | `key` | `key` or `open`. See above. |
+| `PROMPTOWL_API_URL` | `https://app.promptowl.ai` | PromptOwl's API origin — used for device auth, license validation, telemetry. Override for air-gapped or test setups. |
+| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community Server license key (`pk_...`). Unlicensed instances still run but some features may be limited. |
+| `TELEMETRY_ENABLED` | `"true"` (set to `"false"` to disable) | Batched, anonymized usage events sent to PromptOwl. Off disables the loop entirely. |
+| `TELEMETRY_INTERVAL_MS` | `3600000` (1 hour) | How often buffered telemetry is flushed to PromptOwl. |
+| `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
+| `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. |
+
+---
+
+## Typical deployments
+
+### Local dev / single user
+
+```bash
+AUTH_MODE=open DATA_ROOT=./my-data pnpm dev
+```
+
+Or the default dev mode if `pnpm dev` already sets `AUTH_MODE=open` in your scripts.
+
+### Team / multi-user behind a reverse proxy
+
+```bash
+AUTH_MODE=key \
+CORS_ORIGINS="https://team.example.com,https://admin.example.com" \
+DATA_ROOT=/var/lib/contextnest \
+PROMPTOWL_KEY=pk_... \
+pnpm start
+```
+
+Terminate TLS at the proxy, forward `X-Forwarded-For` and `X-Real-IP` headers (the rate limiter reads them), and bind the server to `127.0.0.1` so only the proxy can reach it.
+
+### Hosted / commercial SaaS
+
+Same as team, plus:
+- Run N instances behind a load balancer sharing a network-attached `DATA_ROOT` (note: SQLite + shared filesystem is not a great long-term story — migrate to the MongoDB storage adapter when scaling beyond one box).
+- Set `TELEMETRY_ENABLED=true` and a valid `PROMPTOWL_KEY` so usage rolls up to PromptOwl.
+- Rotate keys regularly via `DELETE /auth/keys/:id` + `POST /auth/keys`.
+
+---
+
+## access.yaml (optional, open + key mode)
+
+Drop an `access.yaml` at `$DATA_ROOT/access.yaml` to add a server-level ABAC layer — useful even in key mode for super-admins and group-based defaults.
+
+```yaml
+mode: restricted
+allowed_users:
+  - "*.acme.com"                # email wildcard — anyone @acme.com
+  - "partner@vendor.com"         # exact match
+super_admins:
+  - "ceo@acme.com"               # always allowed on every nest
+groups:
+  engineering:
+    default_permission: write
+    members:
+      - "*.eng.acme.com"
+  viewers:
+    default_permission: read
+    members:
+      - "*.contractor.acme.com"
+```
+
+See `STEWARDSHIP.md` for how super-admins and groups interact with per-nest stewardship.
+
+---
+
+## Reload
+
+Changing env vars requires a restart — the server reads them at boot. `tsx watch` in dev will pick up code changes automatically but not env changes.

package/dist/{chunk-Q2DCOS7V.js → chunk-2FXVMVZJ.js}

@@ -1,7 +1,7 @@
 import {
   config,
   getDb
-} from "./chunk-USIDOGVJ.js";
+} from "./chunk-2TW25QEA.js";
 
 // src/governance/stewardship-service.ts
 import { v4 as uuid } from "uuid";
@@ -170,7 +170,34 @@ function listStewards(params) {
   sql += " ORDER BY scope, COALESCE(node_pattern, tag_name, ''), user_email";
   return db.prepare(sql).all(...args).map(rowToSteward);
 }
-function createStewardRecord(params) {
+function rolePermission(role) {
+  return role === "editor" ? "write" : "read";
+}
+async function ensureCollaborator(nestId, email, permission, grantedBy) {
+  const db = getDb();
+  let userRow = db.prepare("SELECT id FROM users WHERE email = ?").get(email);
+  if (!userRow) {
+    const { hashPassword } = await import("./keys-YV33AJK3.js");
+    const newId = uuid();
+    db.prepare(
+      "INSERT INTO users (id, email, name, password_hash, is_invited) VALUES (?, ?, ?, ?, 1)"
+    ).run(newId, email, null, await hashPassword(uuid()));
+    userRow = { id: newId };
+  }
+  const nestRow = db.prepare("SELECT user_id FROM nests WHERE id = ?").get(nestId);
+  if (nestRow && nestRow.user_id === userRow.id) return;
+  const existing = db.prepare(
+    "SELECT id FROM nest_collaborators WHERE nest_id = ? AND user_id = ?"
+  ).get(nestId, userRow.id);
+  if (existing) return;
+  const granterRow = db.prepare("SELECT id FROM users WHERE email = ?").get(grantedBy);
+  const granterId = granterRow?.id ?? nestRow?.user_id;
+  if (!granterId) return;
+  db.prepare(
+    "INSERT INTO nest_collaborators (id, nest_id, user_id, permission, granted_by) VALUES (?, ?, ?, ?, ?)"
+  ).run(uuid(), nestId, userRow.id, permission, granterId);
+}
+async function createStewardRecord(params) {
   if (params.users.length === 0) {
     throw new Error("At least one user is required");
   }
@@ -229,6 +256,12 @@ function createStewardRecord(params) {
       isActive: true
     });
     results.push(created);
+    await ensureCollaborator(
+      params.nestId,
+      email,
+      rolePermission(user.role),
+      params.assignedBy
+    );
   }
   db.prepare(
     "UPDATE nests SET stewardship_enabled = 1 WHERE id = ? AND stewardship_enabled = 0"
@@ -255,7 +288,10 @@ function resolve(nestId, nodeId) {
         WHERE s.nest_id = ? AND s.is_active = 1 AND s.scope = 'folder'
           AND s.node_pattern IS NOT NULL
           AND instr(s.node_pattern, '*') = 0
-          AND ? LIKE s.node_pattern || '/%'
+          AND (
+            ? LIKE s.node_pattern || '/%'
+            OR s.node_pattern = ?
+          )
       UNION ALL
       SELECT s.*, 3 AS priority, ('tag: ' || s.tag_name) AS match_source
         FROM stewards s
@@ -270,7 +306,20 @@ function resolve(nestId, nodeId) {
         WHERE s.nest_id = ? AND s.is_active = 1 AND s.scope = 'nest'
       ORDER BY priority ASC, user_email ASC
       `
-  ).all(nestId, nodeId, nestId, nodeId, nestId, nodeId, nestId);
+  ).all(
+    nestId,
+    nodeId,
+    // document branch
+    nestId,
+    nodeId,
+    nestId,
+    // folder branch (path-prefix OR whole-nest folder)
+    nestId,
+    nodeId,
+    // tag branch
+    nestId
+    // nest branch
+  );
   const resolved = rows.map((row) => ({
     steward: rowToSteward(row),
     priority: row.priority,

package/dist/{chunk-USIDOGVJ.js → chunk-2TW25QEA.js}

@@ -1,5 +1,21 @@
 // src/config.ts
-import { join } from "path";
+import { join, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import dotenv from "dotenv";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var envCandidates = [
+  join(process.cwd(), ".env"),
+  join(__dirname, "..", ".env")
+];
+var envFileLoaded = envCandidates.find((p) => existsSync(p)) || null;
+if (envFileLoaded) {
+  dotenv.config({ path: envFileLoaded, override: true });
+}
+console.log(
+  `[config] dotenv: ${envFileLoaded ? `loaded ${envFileLoaded}` : "no .env file found"}`
+);
 function dataRoot() {
   return process.env.DATA_ROOT || join(process.cwd(), "data");
 }
@@ -19,6 +35,14 @@ var config = {
   get PROMPTOWL_KEY() {
     return process.env.PROMPTOWL_KEY || "";
   },
+  /**
+   * Path to the .env file the server reads its config from. Used by
+   * the license install flow to persist PROMPTOWL_KEY alongside any
+   * existing env vars, instead of a separate sidecar file.
+   */
+  get ENV_FILE_PATH() {
+    return process.env.ENV_FILE_PATH || join(process.cwd(), ".env");
+  },
   get TELEMETRY_ENABLED() {
     return process.env.TELEMETRY_ENABLED !== "false";
   },
@@ -52,7 +76,7 @@ var config = {
 // src/db/client.ts
 import Database from "better-sqlite3";
 import { mkdirSync } from "fs";
-import { dirname } from "path";
+import { dirname as dirname2 } from "path";
 
 // src/db/migrations.ts
 function runMigrations(db2) {
@@ -204,6 +228,9 @@ function runMigrations(db2) {
   if (!userCols.includes("is_admin")) {
     db2.exec("ALTER TABLE users ADD COLUMN is_admin INTEGER NOT NULL DEFAULT 0");
   }
+  if (!userCols.includes("is_invited")) {
+    db2.exec("ALTER TABLE users ADD COLUMN is_invited INTEGER NOT NULL DEFAULT 0");
+  }
   db2.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
       id TEXT PRIMARY KEY,
@@ -326,16 +353,65 @@ function runMigrations(db2) {
       recordMigration("002_steward_parity");
     })();
   }
+  if (!hasMigration("003_sessions_and_single_api_key")) {
+    db2.transaction(() => {
+      db2.exec(`
+        CREATE TABLE IF NOT EXISTS sessions (
+          id TEXT PRIMARY KEY,
+          user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+          expires_at TEXT NOT NULL,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+          user_agent TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_sessions_user ON sessions(user_id);
+        CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
+      `);
+      db2.exec(`
+        DELETE FROM api_keys
+        WHERE id IN (
+          SELECT id FROM (
+            SELECT
+              id,
+              ROW_NUMBER() OVER (
+                PARTITION BY user_id
+                ORDER BY
+                  COALESCE(last_used_at, '') DESC,
+                  created_at DESC,
+                  id DESC
+              ) AS rn
+            FROM api_keys
+          )
+          WHERE rn > 1
+        );
+      `);
+      db2.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_api_keys_user_unique
+          ON api_keys(user_id);
+      `);
+      recordMigration("003_sessions_and_single_api_key");
+    })();
+  }
+  if (!hasMigration("004_license_cache_owner_email")) {
+    db2.transaction(() => {
+      const cols = db2.prepare("PRAGMA table_info(license_cache)").all().map((c) => c.name);
+      if (!cols.includes("owner_email")) {
+        db2.exec("ALTER TABLE license_cache ADD COLUMN owner_email TEXT");
+      }
+      recordMigration("004_license_cache_owner_email");
+    })();
+  }
 }
 
 // src/db/client.ts
 var db = null;
 function getDb() {
   if (!db) {
-    mkdirSync(dirname(config.DATABASE_PATH), { recursive: true });
+    mkdirSync(dirname2(config.DATABASE_PATH), { recursive: true });
     db = new Database(config.DATABASE_PATH);
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
+    db.pragma("busy_timeout = 5000");
     runMigrations(db);
   }
   return db;

package/dist/{chunk-P6NG56CO.js → chunk-BLOPZDPL.js}

@@ -1,6 +1,6 @@
 import {
   getDb
-} from "./chunk-USIDOGVJ.js";
+} from "./chunk-2TW25QEA.js";
 
 // src/governance/version-service.ts
 import { createHash } from "crypto";
@@ -102,6 +102,28 @@ function getNodeTags(nestId, nodeId) {
     return [];
   }
 }
+function getDisplayStatus(nestId, nodeId) {
+  const db = getDb();
+  const pending = db.prepare(
+    "SELECT 1 FROM review_requests WHERE nest_id = ? AND node_id = ? AND status = 'pending' LIMIT 1"
+  ).get(nestId, nodeId);
+  if (pending) return "pending_review";
+  const current = db.prepare(
+    `SELECT version, status FROM node_versions
+       WHERE nest_id = ? AND node_id = ?
+       ORDER BY version DESC LIMIT 1`
+  ).get(nestId, nodeId);
+  if (!current) return "draft";
+  if (current.status === "approved") {
+    const approved = db.prepare(
+      "SELECT approved_version FROM approved_versions WHERE nest_id = ? AND node_id = ?"
+    ).get(nestId, nodeId);
+    if (approved?.approved_version === current.version) return "approved";
+    return "draft";
+  }
+  if (current.status === "rejected") return "rejected";
+  return "draft";
+}
 function rowToVersion(row) {
   return {
     version: row.version,
@@ -123,5 +145,6 @@ export {
   getApprovedVersion,
   setApprovedVersion,
   checkConflict,
-  getNodeTags
+  getNodeTags,
+  getDisplayStatus
 };

package/dist/{chunk-DJFEV4ET.js → chunk-XDCW4HTW.js}

@@ -1,10 +1,10 @@
 import {
   canUserApprove,
   resolveStewardsForNode
-} from "./chunk-Q2DCOS7V.js";
+} from "./chunk-2FXVMVZJ.js";
 import {
   getDb
-} from "./chunk-USIDOGVJ.js";
+} from "./chunk-2TW25QEA.js";
 
 // src/governance/review-service.ts
 import { v4 as uuid } from "uuid";