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

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-DJFEV4ET.js → chunk-5VHKEIAW.js}

@@ -1,13 +1,74 @@
 import {
   canUserApprove,
   resolveStewardsForNode
-} from "./chunk-Q2DCOS7V.js";
+} from "./chunk-K22GWPT4.js";
 import {
+  createVersion,
+  setApprovedVersion
+} from "./chunk-JMZ75ZCD.js";
+import {
+  config,
   getDb
-} from "./chunk-USIDOGVJ.js";
+} from "./chunk-KQCWNHDM.js";
 
 // src/governance/review-service.ts
 import { v4 as uuid } from "uuid";
+
+// src/nodes/engine.ts
+import { join } from "path";
+import {
+  NestStorage,
+  GraphQueryEngine,
+  VersionManager
+} from "@promptowl/contextnest-engine";
+var NestEngineCache = class {
+  cache = /* @__PURE__ */ new Map();
+  get(nestId) {
+    let engine = this.cache.get(nestId);
+    if (!engine) {
+      const nestPath = join(config.DATA_ROOT, "nests", nestId);
+      const storage = new NestStorage(nestPath);
+      const query = new GraphQueryEngine(storage);
+      const versions = new VersionManager(storage);
+      engine = { storage, query, versions };
+      this.cache.set(nestId, engine);
+    }
+    return engine;
+  }
+  evict(nestId) {
+    this.cache.delete(nestId);
+  }
+};
+var engineCache = new NestEngineCache();
+
+// src/governance/safe-publish.ts
+import {
+  publishDocument,
+  serializeDocument
+} from "@promptowl/contextnest-engine";
+async function safePublishDocument(storage, docId, options) {
+  const node = await storage.readDocument(docId);
+  const cleanedFrontmatter = stripUndefinedDeep(node.frontmatter);
+  const cleanedNode = { ...node, frontmatter: cleanedFrontmatter };
+  await storage.writeDocument(docId, serializeDocument(cleanedNode));
+  return publishDocument(storage, docId, options);
+}
+function stripUndefinedDeep(value) {
+  if (Array.isArray(value)) {
+    return value.filter((v) => v !== void 0).map((v) => stripUndefinedDeep(v));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (v === void 0) continue;
+      out[k] = stripUndefinedDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/governance/review-service.ts
 function submitForReview(params) {
   const db = getDb();
   const existing = db.prepare(
@@ -35,7 +96,7 @@ function submitForReview(params) {
   ).run(params.nestId, params.nodeId, params.version);
   return getReviewRequest(id);
 }
-function approve(params) {
+async function approve(params) {
   const db = getDb();
   const pending = db.prepare(
     "SELECT * FROM review_requests WHERE nest_id = ? AND node_id = ? AND status = 'pending' ORDER BY requested_at DESC LIMIT 1"
@@ -65,12 +126,45 @@ function approve(params) {
     pending.id
   );
   db.prepare(
-    "UPDATE node_versions SET status = 'approved' WHERE nest_id = ? AND node_id = ? AND version = ?"
+    "UPDATE node_versions SET status = 'published' WHERE nest_id = ? AND node_id = ? AND version = ?"
   ).run(params.nestId, params.nodeId, params.version);
   db.prepare(
     `INSERT OR REPLACE INTO approved_versions (nest_id, node_id, approved_version, approved_by)
      VALUES (?, ?, ?, ?)`
   ).run(params.nestId, params.nodeId, params.version, params.approvedBy);
+  try {
+    const { storage } = engineCache.get(params.nestId);
+    const result = await safePublishDocument(storage, params.nodeId, {
+      editedBy: params.approvedBy,
+      note: params.note || `Approved review request ${pending.id}`
+    });
+    const engineVersion = result.versionEntry.version;
+    if (engineVersion !== params.version) {
+      const node = result.node;
+      const tags = node.frontmatter.tags || [];
+      createVersion({
+        nestId: params.nestId,
+        nodeId: params.nodeId,
+        version: engineVersion,
+        content: node.body || "",
+        author: params.approvedBy,
+        status: "published",
+        tags,
+        changeNote: params.note || `Approved review request ${pending.id}`
+      });
+      setApprovedVersion(
+        params.nestId,
+        params.nodeId,
+        engineVersion,
+        params.approvedBy
+      );
+    }
+  } catch (err) {
+    console.error(
+      `publishDocument failed for ${params.nestId}/${params.nodeId} on approve:`,
+      err
+    );
+  }
   return getReviewRequest(pending.id);
 }
 function reject(params) {
@@ -189,6 +283,8 @@ function rowToReviewRequest(row) {
 }
 
 export {
+  engineCache,
+  safePublishDocument,
   submitForReview,
   approve,
   reject,

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

@@ -1,12 +1,16 @@
 import {
   getDb
-} from "./chunk-USIDOGVJ.js";
+} from "./chunk-KQCWNHDM.js";
 
 // src/governance/version-service.ts
 import { createHash } from "crypto";
 function hashContent(content) {
   return createHash("sha256").update(content).digest("hex");
 }
+var SYSTEM_AUTHOR_PREFIX = "system:auto-publish:";
+function systemAuthor(email) {
+  return `${SYSTEM_AUTHOR_PREFIX}${email}`;
+}
 function createVersion(params) {
   const db = getDb();
   const contentHash = hashContent(params.content);
@@ -49,8 +53,10 @@ function getVersion(nestId, nodeId, version) {
 function getCurrentVersion(nestId, nodeId) {
   const db = getDb();
   const row = db.prepare(
-    "SELECT MAX(version) as v FROM node_versions WHERE nest_id = ? AND node_id = ?"
-  ).get(nestId, nodeId);
+    `SELECT MAX(version) as v FROM node_versions
+        WHERE nest_id = ? AND node_id = ?
+          AND author NOT LIKE ?`
+  ).get(nestId, nodeId, `${SYSTEM_AUTHOR_PREFIX}%`);
   return row?.v || 0;
 }
 function getApprovedVersion(nestId, nodeId) {
@@ -70,8 +76,13 @@ function setApprovedVersion(nestId, nodeId, version, approvedBy) {
 function checkConflict(nestId, nodeId, baseVersion) {
   const db = getDb();
   const current = db.prepare(
-    "SELECT version, content_hash, author, created_at FROM node_versions WHERE nest_id = ? AND node_id = ? ORDER BY version DESC LIMIT 1"
-  ).get(nestId, nodeId);
+    `SELECT version, content_hash, author, created_at
+         FROM node_versions
+        WHERE nest_id = ? AND node_id = ?
+          AND author NOT LIKE ?
+        ORDER BY version DESC
+        LIMIT 1`
+  ).get(nestId, nodeId, `${SYSTEM_AUTHOR_PREFIX}%`);
   if (!current) {
     return { conflict: false, currentVersion: 0, currentHash: "" };
   }
@@ -102,6 +113,30 @@ 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 === "published" || 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 current.status === "published" ? "published" : "approved";
+    }
+    return "draft";
+  }
+  if (current.status === "rejected") return "rejected";
+  return "draft";
+}
 function rowToVersion(row) {
   return {
     version: row.version,
@@ -116,6 +151,8 @@ function rowToVersion(row) {
 
 export {
   hashContent,
+  SYSTEM_AUTHOR_PREFIX,
+  systemAuthor,
   createVersion,
   getVersions,
   getVersion,
@@ -123,5 +160,6 @@ export {
   getApprovedVersion,
   setApprovedVersion,
   checkConflict,
-  getNodeTags
+  getNodeTags,
+  getDisplayStatus
 };