@omgbase/astro 0.1.0 → 0.3.0

package/README.md

@@ -5,9 +5,10 @@ Use an [omgbase](https://github.com/omgbase/omgbase) repository as the CMS for a
 The package provides:
 
 - **`omgLoader`** — an Astro Content Layer loader driven by an **OQX** query
+- **`omgLiveLoader`** — an Astro **live collection** loader for SSR: query and hydrate omg at request time, no build-time data store
 - **Local transport** — embedded `@omgbase/core`
 - **Remote transport** — Streamable HTTP MCP (`query` + `docs_get_many`), same as `omg … --server <url>`
-- **Dev live-reload** — in `astro dev`, local vaults use Vite's FS watcher; remote polls MCP `changes_since`. Both update Astro's content data store so the normal HMR path fires — no custom integration required
+- **Dev live-reload** — in `astro dev`, local vaults use Vite's FS watcher; remote polls MCP `changes_since` and reconnects on its own when the server restarts. Both update Astro's content data store so the normal HMR path fires — no custom integration required
 - **`createMcpHttpServer`** — optional local Streamable HTTP MCP server for demos/CI
 
 ## Install
@@ -93,6 +94,8 @@ Enabled by default whenever Astro passes a `watcher` into the loader:
 
 On change, the loader re-queries/hydrates into the content data store. Astro already watches that store file and hot-reloads pages — we don’t invent a second HMR channel.
 
+If the remote server restarts (or the Streamable HTTP session expires), the transport drops its stale session, reconnects, and retries the call once — polling resumes without restarting `astro dev`. While the server is down, the loader logs one warning and then a single info line when it comes back.
+
 ```ts
 omgLoader({
   url: process.env.OMG_URL!,
@@ -119,12 +122,102 @@ const mcp = await createMcpHttpServer({
 
 Prefer your real wrapper/hosted endpoint for production builds.
 
+## Live collections (SSR)
+
+`omgLiveLoader` is an Astro [live collection](https://docs.astro.build/en/guides/content-collections/) loader (experimental in Astro 5.10+, stable in Astro 7). Nothing is loaded at build time: every `getLiveCollection` / `getLiveEntry` call runs an OQX query and/or `docs_get_many` against omg when the request comes in. Your site must render on the server (`output: "server"` in `astro.config.mjs`, with an adapter).
+
+```ts
+// src/live.config.ts
+import { defineLiveCollection } from "astro:content";
+import { omgLiveLoader } from "@omgbase/astro";
+
+const notes = defineLiveCollection({
+  loader: omgLiveLoader({
+    url: process.env.OMG_URL!,            // or `workspace: "../content"` for the local transport
+    token: process.env.OMG_TOKEN,
+    repo: "notes",
+    query: "select $path, $title, $updated_at from docs",
+    href: ({ slug }) => `/note/${slug}/`, // match your routes
+  }),
+});
+
+export const collections = { notes };
+```
+
+```astro
+---
+// src/pages/notes/index.astro
+import { getLiveCollection } from "astro:content";
+
+const { entries, error } = await getLiveCollection("notes", {
+  query: 'select $path, $title, $updated_at from docs where status == "published"',
+  limit: 50,
+});
+if (error) throw error;
+---
+<ul>
+  {entries.map((n) => <li><a href={`/note/${n.data.slug}/`}>{n.data.title}</a></li>)}
+</ul>
+```
+
+```astro
+---
+// src/pages/note/[...slug].astro
+import { getLiveEntry, render } from "astro:content";
+
+const { entry, error } = await getLiveEntry("notes", { slug: Astro.params.slug! });
+if (error) throw error;
+if (!entry) return Astro.redirect("/404");
+const { Content } = await render(entry);
+---
+<h1>{entry.data.title}</h1>
+<Content />
+```
+
+### Filters
+
+| Call | Filter | Notes |
+| --- | --- | --- |
+| `getLiveCollection(name, filter?)` | `{ query?, limit?, hydrate? }` | Each field falls back to the loader option. `query` must return document hits |
+| `getLiveEntry(name, filter)` | `{ id }` **or** `{ path }` **or** `{ slug }` | Exactly one key. `path` is repo-relative (a leading `/` is stripped); `slug` is mapped back to a path with `pathForSlug` (default `` `${slug}.md` ``) and looked up via `$path == "…"` |
+
+A missing entry resolves to `entry: undefined`; every other failure comes back as `error`, an `OmgLiveError` with a `code` of `invalid_filter`, `query_failed`, `hydrate_failed` or `render_failed` — the loader never throws.
+
+### Lean vs hydrated
+
+By default a collection is **lean**: one `query` call, and each entry's `data` holds the query's projections (plus `path`, `docId`, `slug`, and `updatedAt` / `title` aliases of `$updated_at` / `$title` when projected). There is no `rendered` content and no `body`, so a list page costs a single round trip.
+
+`getLiveEntry` always **hydrates**: `docs_get_many` for the doc, `data` = frontmatter + intrinsics (`path`, `docId`, `slug`, `contentHash`) + the lean projections + `body` (markdown after frontmatter), and `rendered.html`. Markdown links are rewritten to `href(...)` for the docs omg's out-edges say this doc links to; links to anything else are left as authored. Set `href: false` to skip rewriting.
+
+Pass `hydrate: true` (loader option or collection filter) to get the hydrated shape for every collection entry — one `query`, one `docs_get_many`, one edge lookup.
+
+`cacheHint.lastModified` is set from `$updated_at` (the newest hit for a collection) whenever your query projects it, so project it if you cache responses.
+
+### Rendering
+
+Bodies render through `@astrojs/markdown-remark`'s `createMarkdownProcessor`, created once per loader. Pass `markdown` to configure it, or `render` to replace it:
+
+```ts
+omgLiveLoader({
+  url: process.env.OMG_URL!,
+  query: "select $path, $title, $updated_at from docs",
+  markdown: { shikiConfig: { theme: "github-dark" } },
+  // render: async (markdown, { docId, path }) => ({ html: myRenderer(markdown) }),
+});
+```
+
+### Connections
+
+The loader connects lazily on the first request and keeps that transport for the life of the server process; the remote transport reconnects by itself when the MCP session is lost. Pass `transport` to share a connection between loaders or to inject a fake in tests.
+
 ## Identity & caching
 
 - Astro entry **`id`** = omg document id (`d_…`)
 - **`data.slug`** = routing key (default: path with `.md` stripped; override with `slug`)
 - **`href`** = site URL used when rewriting markdown links between hydrated docs (default `/${slug}`; override to match routes)
-- Digests use omg `contentHash` (plus an href-map fingerprint when rewriting) so unchanged docs skip rewrite on reload
+- **Hash-first sync.** Every load projects `$content_hash` onto your query, so a hit carries the server's whole-file hash (frontmatter included). Docs whose hash, path and hit projections match the stored entry are reused without `docs_get_many`; only new/changed docs are fetched, mapped and rendered. A no-change reload costs one query and nothing else — an all-docs collection is cheap to keep loaded
+- **Link-aware invalidation.** Each entry's digest also pins the hrefs of the docs it links to (via omg out-edges). Adding, removing or moving a doc re-fetches only its linkers, not the whole collection. The edge scan itself is skipped when nothing changed
+- **Fallbacks.** If the server rejects the `$content_hash` projection (older omg), the loader warns once and hydrates everything as before; the digest compare still avoids redundant re-renders. Entries stored under the pre-0.2 digest format are re-hydrated once and migrated
 
 ## Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/astro",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Astro Content Loader and helpers to use omgbase as a CMS",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,14 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "echo 'no lint yet'"
+  },
   "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@omgbase/core": "^0.5.0",
     "@omgbase/sync": "^0.4.2"
@@ -38,11 +45,5 @@
     "astro": "^7.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "lint": "echo 'no lint yet'"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 omgbase
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.