anbaric-cloud-hosting 1.27.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.27.0",
-    "anbaric-plugins": "^1.27.0",
-    "anbaric-tsapi": "^1.27.0",
-    "anbaric-web": "^1.27.0",
+    "anbaric-data-store": "^1.28.0",
+    "anbaric-plugins": "^1.28.0",
+    "anbaric-tsapi": "^1.28.0",
+    "anbaric-web": "^1.28.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.27.0",
-    "anbaric-state-machine": "^1.27.0",
+    "anbaric-impl-cloud": "^1.28.0",
+    "anbaric-state-machine": "^1.28.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/data-store/AppDocsStore.ts

@@ -2,12 +2,16 @@ type AppDoc = {
     slug : string,
     title : string,
     markdown : string,
+    parentSlug : string | null,
+    position : number,
 };
 
-/* Generated user documentation for an app. Docs are regenerated wholesale on
-   every deploy, so the store replaces an app's whole set at once rather than
-   upserting doc by doc - a doc that no longer applies after a redeploy must not
-   linger. */
+/* Generated user documentation for an app, held as a shallow tree: root docs
+   (an "Introduction" and, verbatim, any README) have a null parent, and every
+   other doc names its parent's slug, ordered among its siblings by position.
+   Docs are regenerated wholesale on every deploy, so the store replaces an
+   app's whole set at once rather than upserting doc by doc - a doc that no
+   longer applies after a redeploy must not linger. */
 interface AppDocsStore {
 
     replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void>;

package/src/data-store/PostgresAppDocsStore.ts

@@ -17,9 +17,14 @@ class PostgresAppDocsStore implements AppDocsStore {
 
             if (docs.length > 0) {
                 await client.query(
-                    `INSERT INTO app_docs (app_id, slug, title, markdown)
-                     SELECT $1, * FROM unnest($2::text[], $3::text[], $4::text[])`,
-                    [appId, docs.map(doc => doc.slug), docs.map(doc => doc.title), docs.map(doc => doc.markdown)],
+                    `INSERT INTO app_docs (app_id, slug, title, markdown, parent_slug, position)
+                     SELECT $1, * FROM unnest($2::text[], $3::text[], $4::text[], $5::text[], $6::int[])`,
+                    [appId,
+                     docs.map(doc => doc.slug),
+                     docs.map(doc => doc.title),
+                     docs.map(doc => doc.markdown),
+                     docs.map(doc => doc.parentSlug),
+                     docs.map(doc => doc.position)],
                 );
             }
 
@@ -34,8 +39,16 @@ class PostgresAppDocsStore implements AppDocsStore {
 
     async listForApp(appId : string) : Promise<Array<AppDoc>> {
         const result = await this.pool.query(
-            "SELECT slug, title, markdown FROM app_docs WHERE app_id = $1 ORDER BY slug", [appId]);
-        return result.rows.map(row => ({ slug: row.slug, title: row.title, markdown: row.markdown }));
+            `SELECT slug, title, markdown, parent_slug, position
+             FROM app_docs WHERE app_id = $1
+             ORDER BY position, slug`, [appId]);
+        return result.rows.map(row => ({
+            slug: row.slug,
+            title: row.title,
+            markdown: row.markdown,
+            parentSlug: row.parent_slug,
+            position: row.position,
+        }));
     }
 
 }

package/src/data-store/Schema.ts

@@ -95,17 +95,23 @@ const ensureSchema = async (pool : Pool) : Promise<void> => {
     await pool.query(`CREATE INDEX IF NOT EXISTS job_run_schedule_due
         ON job_run_schedule (run_at) WHERE claimed_at IS NULL`);
     // User documentation the platform generates from an app's source on deploy,
-    // keyed by (app_id, slug). A redeploy replaces the whole set for an app.
+    // keyed by (app_id, slug) and held as a shallow tree: a root doc has a null
+    // parent_slug, a child names its parent's slug, and position orders
+    // siblings. A redeploy replaces the whole set for an app.
     await pool.query(`
         CREATE TABLE IF NOT EXISTS app_docs (
             app_id       TEXT NOT NULL,
             slug         TEXT NOT NULL,
             title        TEXT NOT NULL DEFAULT '',
             markdown     TEXT NOT NULL,
+            parent_slug  TEXT,
+            position     INTEGER NOT NULL DEFAULT 0,
             generated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
             PRIMARY KEY (app_id, slug)
         )
     `);
+    await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS parent_slug TEXT");
+    await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS position INTEGER NOT NULL DEFAULT 0");
     await pool.query("CREATE SCHEMA IF NOT EXISTS anbaric_system");
     await pool.query(`
         CREATE TABLE IF NOT EXISTS anbaric_system.cli_keys (

package/src/docs/DocGenerator.ts

@@ -1,7 +1,71 @@
-import {AppDocsStore} from "../data-store/AppDocsStore";
-import {DocModel} from "./DocModel";
+import {AppDoc, AppDocsStore} from "../data-store/AppDocsStore";
+import {DocModel, DraftDoc} from "./DocModel";
 import {gatherSources} from "./gatherSources";
 
+const README = /^readme(\.md|\.markdown)?$/i;
+
+/* Arranges the model's draft docs into the shallow tree the store holds: one
+   "introduction" root with every other page beneath it, plus the app's README
+   copied in verbatim as a second root beside the introduction. It is defensive
+   about what the model returned - a missing introduction, a dangling or looping
+   parent - so the stored set is always a well-formed single-rooted tree (two
+   roots once the README is added). */
+const buildDocTree = (drafts : Array<DraftDoc>, readme : string | undefined) : Array<AppDoc> => {
+    const cleaned = drafts
+        .filter(draft => draft && typeof draft.slug === "string" && draft.slug.trim() && typeof draft.markdown === "string")
+        .map(draft => ({
+            slug: draft.slug.trim(),
+            title: (typeof draft.title === "string" && draft.title.trim() ? draft.title : draft.slug).trim(),
+            markdown: draft.markdown,
+            parentSlug: typeof draft.parentSlug === "string" && draft.parentSlug.trim() ? draft.parentSlug.trim() : null,
+        }))
+        .filter(draft => draft.slug !== "readme");
+
+    if (cleaned.length === 0) return [];
+
+    const bySlug = new Map(cleaned.map(draft => [draft.slug, draft]));
+
+    const intro = bySlug.get("introduction") ?? cleaned.find(draft => draft.parentSlug === null) ?? cleaned[0];
+    intro.parentSlug = null;
+
+    const reachesIntro = (draft : typeof cleaned[number]) : boolean => {
+        const seen = new Set<string>();
+        let current : typeof cleaned[number] | undefined = draft;
+
+        while (current && current !== intro) {
+            if (seen.has(current.slug)) return false;
+            seen.add(current.slug);
+            current = current.parentSlug === null ? undefined : bySlug.get(current.parentSlug);
+        }
+
+        return current === intro;
+    };
+
+    for (const draft of cleaned) {
+        if (draft !== intro && ! reachesIntro(draft)) draft.parentSlug = intro.slug;
+    }
+
+    const nextPosition = new Map<string, number>();
+    const positioned = (parentSlug : string | null) : number => {
+        const key = parentSlug ?? "";
+        const position = nextPosition.get(key) ?? 0;
+        nextPosition.set(key, position + 1);
+        return position;
+    };
+
+    const docs : Array<AppDoc> = [{ ...intro, position: positioned(null) }];
+
+    for (const draft of cleaned) {
+        if (draft !== intro) docs.push({ ...draft, position: positioned(draft.parentSlug) });
+    }
+
+    if (readme !== undefined) {
+        docs.push({ slug: "readme", title: "README", markdown: readme, parentSlug: null, position: positioned(null) });
+    }
+
+    return docs;
+};
+
 /* Generates an app's user documentation from its source and stores it. It runs
    off the deploy's critical path (the build layer calls it fire-and-forget), so
    it is deliberately all-or-nothing and never throws: any failure - no model
@@ -16,7 +80,9 @@ class DocGenerator {
             const { files, truncated } = await gatherSources(appDir);
             if (files.length === 0) return;
 
-            const docs = await this.model.writeDocs({ appName, files, truncated });
+            const drafts = await this.model.writeDocs({ appName, files, truncated });
+            const readme = files.find(file => README.test(file.path))?.content;
+            const docs = buildDocTree(drafts, readme);
             if (docs.length === 0) return;
 
             await this.store.replaceForApp(appName, docs);
@@ -28,4 +94,4 @@ class DocGenerator {
 
 }
 
-export { DocGenerator }
+export { DocGenerator, buildDocTree }

package/src/docs/DocModel.ts

@@ -1,18 +1,27 @@
-import {AppDoc} from "../data-store/AppDocsStore";
-
 type DocContext = {
     appName : string,
     files : Array<{ path : string, content : string }>,
     truncated : boolean,
 };
 
+/* One doc as the model proposes it, before the generator arranges the set into
+   a tree: a slug, a title, its markdown, and optionally the slug of the doc it
+   belongs under (the introduction, or another page). The generator fills in the
+   final parent and sibling position. */
+type DraftDoc = {
+    slug : string,
+    title : string,
+    markdown : string,
+    parentSlug? : string | null,
+};
+
 /* Turns an app's source into a set of user-facing docs. An implementation that
    cannot reach a model (nothing configured) returns an empty set rather than
    throwing, so doc generation quietly does nothing. */
 interface DocModel {
 
-    writeDocs(context : DocContext) : Promise<Array<AppDoc>>;
+    writeDocs(context : DocContext) : Promise<Array<DraftDoc>>;
 
 }
 
-export type { DocContext, DocModel };
+export type { DocContext, DraftDoc, DocModel };

package/src/docs/GatewayDocModel.ts

@@ -1,11 +1,14 @@
-import {AppDoc} from "../data-store/AppDocsStore";
-import {DocContext, DocModel} from "./DocModel";
+import {DocContext, DocModel, DraftDoc} from "./DocModel";
 
 type FetchFn = (url : string, init : RequestInit) => Promise<Response>;
 
 const SYSTEM_PROMPT = `You write user documentation for an application deployed on Anbaric.
 
-Anbaric apps model their domain as state machines: long-lived jobs move through named states, driven by actions and transitions, with data validated against a schema and every change attributed to an actor. Read the whole source you are given and write documentation for the people who will USE this app - what it does, the workflows it runs, how someone drives it, and anything they need to know. Write clear markdown. Prefer several focused docs over one long one; give each a short kebab-case slug and a human title. Do not invent features the source does not show. If the source was truncated, document only what you can see.`;
+Anbaric apps model their domain as state machines: long-lived jobs move through named states, driven by actions and transitions, with data validated against a schema and every change attributed to an actor. Read the whole source you are given and write documentation for the people who will USE this app - what it does, the workflows it runs, how someone drives it, and anything they need to know.
+
+Organise the docs as a shallow tree. Write exactly one top-level page with the slug "introduction" and a null parentSlug: a concise overview of the app that orients a new user. Write every other page as a child, giving its parentSlug as "introduction" (or, to nest one level deeper, the slug of another page). Prefer several focused child pages over one long page. Do not write a page with the slug "readme" - the app's README is added separately.
+
+Write clear markdown. Give each page a short kebab-case slug and a human title. Do not invent features the source does not show. If the source was truncated, document only what you can see.`;
 
 const OUTPUT_SCHEMA = {
     type: "object",
@@ -20,8 +23,9 @@ const OUTPUT_SCHEMA = {
                     slug: { type: "string" },
                     title: { type: "string" },
                     markdown: { type: "string" },
+                    parentSlug: { type: ["string", "null"] },
                 },
-                required: ["slug", "title", "markdown"],
+                required: ["slug", "title", "markdown", "parentSlug"],
             },
         },
     },
@@ -39,7 +43,7 @@ class GatewayDocModel implements DocModel {
                 private model : string = process.env.ANBARIC_AGENTIC_MODEL ?? "gpt-5.4-mini",
                 private fetchFn : FetchFn = (url, init) => fetch(url, init)) {}
 
-    async writeDocs(context : DocContext) : Promise<Array<AppDoc>> {
+    async writeDocs(context : DocContext) : Promise<Array<DraftDoc>> {
         if (!this.apiKey) {
             console.warn(`[docs] no ANBARIC_AI_GATEWAY_TOKEN - skipping documentation for "${context.appName}"`);
             return [];