Merge worktree-agent-190: Fail loudly on a missing docs content root (#190)

Author: alexeygrigorev

backend/e2e/auth-error-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require('@playwright/test');
 const { spawn } = require('child_process');
 const http = require('http');
 const path = require('path');
+const { createDocsCacheRoot } = require('./helpers/docs-content-root');
 
 const PORT = 3017;
 const BASE_URL = `http://127.0.0.1:${PORT}`;
@@ -34,6 +35,7 @@ test.describe('production portal authentication error', () => {
         DATAOPS_DOCS_DOMAIN: '1',
         WORK_ENGINE_AUTH_MODE: 'portal',
         DTC_OFFLINE: '1',
+        DTC_CACHE_ROOT: createDocsCacheRoot('issue-190-docs-cache/auth-error-production-portal'),
         FRONTEND_ROOT: path.resolve(__dirname, '..', '..', 'frontend'),
         AUTH_BASE_URL: 'https://auth.example.test',
         AUTH_ISSUER: 'https://issuer.example.test/pool',

backend/e2e/bookkeeping-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require("@playwright/test");
 const { spawn } = require("child_process");
 const http = require("http");
 const path = require("path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 
 const PORT = 3014;
 const BASE_URL = `http://127.0.0.1:${PORT}`;
@@ -37,6 +38,7 @@ test.describe("production portal bookkeeping", () => {
         SKIP_AUTH: "true",
         DATAOPS_DOCS_DOMAIN: "1",
         DTC_OFFLINE: "1",
+        DTC_CACHE_ROOT: createDocsCacheRoot("issue-190-docs-cache/bookkeeping-production-portal"),
         FRONTEND_ROOT: path.resolve(__dirname, "..", "..", "frontend"),
         PORT: String(PORT),
       },

backend/e2e/bookkeeping-sponsors-design-production-portal.spec.js

@@ -4,6 +4,7 @@ const { spawn } = require("child_process");
 const fs = require("fs");
 const http = require("http");
 const path = require("path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 
 const PORT = 3318;
 const BASE_URL = `http://127.0.0.1:${PORT}`;
@@ -203,6 +204,7 @@ test.describe("Bookkeeping and Sponsors design prototype", () => {
         SKIP_AUTH: "true",
         DATAOPS_DOCS_DOMAIN: "1",
         DTC_OFFLINE: "1",
+        DTC_CACHE_ROOT: createDocsCacheRoot("issue-190-docs-cache/bookkeeping-sponsors-design-production-portal"),
         CONVERSATIONAL_TELEGRAM_INGRESS_ENABLED: "false",
         CONVERSATIONAL_EXECUTION_ENABLED: "false",
         CONVERSATIONAL_ENABLED_PLUGINS: "none",

backend/e2e/browser-cookie-bootstrap-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require('@playwright/test');
 const { spawn } = require('child_process');
 const http = require('http');
 const path = require('path');
+const { createDocsCacheRoot } = require('./helpers/docs-content-root');
 
 const PORT = 3018;
 const BASE_URL = `http://localhost:${PORT}`;
@@ -35,6 +36,7 @@ test.describe('production portal browser-cookie bootstrap', () => {
         DATAOPS_DOCS_DOMAIN: '1',
         WORK_ENGINE_AUTH_MODE: 'portal',
         DTC_OFFLINE: '1',
+        DTC_CACHE_ROOT: createDocsCacheRoot('issue-190-docs-cache/browser-cookie-bootstrap-production-portal'),
         // The built artifact packages this same canonical source at
         // dist/frontend; source-mode E2E points to it explicitly.
         FRONTEND_ROOT: path.resolve(__dirname, '..', '..', 'frontend'),

backend/e2e/frontend-module-characterization.spec.js

@@ -1,9 +1,32 @@
 const { test, expect } = require("@playwright/test");
 const { spawn } = require("node:child_process");
+const fs = require("node:fs");
 const net = require("node:net");
 const path = require("node:path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 
 const ROOT = path.resolve(__dirname, "..", "..");
+const SCREENSHOT_DIR = path.join(ROOT, ".tmp", "screenshots", "issue-190");
+const FIXTURE_DOC_PATH = "content/overview/reference/schedule.md";
+const FIXTURE_DOC_TITLE = "Synthetic Characterization Schedule";
+const FIXTURE_DOC_SUMMARY = "Synthetic reference used only by browser characterization tests.";
+// `buildOperationsReferenceLinks` indexes this exact path, so the docs surface
+// only lists this document when `GET /docs` really returned the spec's corpus.
+const FIXTURE_DOC = [
+  "---",
+  "id: ref.synthetic.characterization-schedule",
+  `title: ${FIXTURE_DOC_TITLE}`,
+  `summary: ${FIXTURE_DOC_SUMMARY}`,
+  "doc_type: reference",
+  "tags: [synthetic]",
+  "systems: [dataops]",
+  "---",
+  "",
+  `# ${FIXTURE_DOC_TITLE}`,
+  "",
+  "Synthetic public-safe content for the characterization corpus.",
+  "",
+].join("\n");
 let server;
 let baseURL;
 
@@ -111,6 +134,10 @@ test.describe("pre-refactor frontend module characterization", () => {
   test.beforeAll(async () => {
     const port = await freePort();
     baseURL = `http://127.0.0.1:${port}`;
+    const cacheRoot = createDocsCacheRoot("issue-190-frontend-characterization", {
+      [FIXTURE_DOC_PATH]: FIXTURE_DOC,
+    });
+    fs.mkdirSync(SCREENSHOT_DIR, { recursive: true });
     server = spawn(path.join(ROOT, "node_modules", ".bin", "tsx"), ["scripts/test-server.ts"], {
       cwd: path.join(ROOT, "backend"),
       detached: true,
@@ -122,6 +149,7 @@ test.describe("pre-refactor frontend module characterization", () => {
         SKIP_AUTH: "true",
         DATAOPS_DOCS_DOMAIN: "1",
         DTC_OFFLINE: "1",
+        DTC_CACHE_ROOT: cacheRoot,
         FRONTEND_ROOT: path.join(ROOT, "frontend"),
         E2E_TEMPLATE_ACTOR_ID: "00000000-0000-0000-0000-000000000001",
         CONVERSATIONAL_TELEGRAM_INGRESS_ENABLED: "false",
@@ -226,6 +254,15 @@ test.describe("pre-refactor frontend module characterization", () => {
       await expect(page).toHaveURL(`${baseURL}/#${route}`);
       await expect(page.locator("#library-title")).toHaveText(title);
       await expect(page.locator(marker)).toBeVisible();
+      if (route === "/processes") {
+        // The docs surface must list the spec's own corpus. Without this the
+        // suite would pass just as happily against an empty or wrongly pointed
+        // content root.
+        await expect(
+          page.locator(".ops-surface-docs .ops-reference-link", { hasText: FIXTURE_DOC_TITLE }),
+        ).toBeVisible();
+        await page.screenshot({ path: path.join(SCREENSHOT_DIR, "processes.png"), fullPage: true });
+      }
       await expectNoHorizontalOverflow(page, route);
     }
     await page.goto(`${baseURL}/#/templates`);

backend/e2e/helpers/docs-content-root.js

@@ -0,0 +1,44 @@
+/**
+ * Spec-owned docs content roots for offline browser tests.
+ *
+ * `scripts/test-server.ts` builds its docs store from the environment, and
+ * `githubStoreConfigFromEnv()` falls back to `/tmp/dataops` when
+ * `DTC_CACHE_ROOT` is unset. Offline (`DTC_OFFLINE=1`) nothing hydrates that
+ * directory, so a spec without an explicit cache root inherits whatever the
+ * machine happens to have: present and empty on a developer laptop, absent on a
+ * clean CI runner. Every offline spec therefore owns a content root under the
+ * project-local `.tmp/`, created fresh for each run.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const TMP_ROOT = path.join(REPO_ROOT, '.tmp');
+
+/**
+ * Create an empty-but-present docs cache for `name` and return its root.
+ *
+ * The returned path is what `DTC_CACHE_ROOT` must be set to; `<root>/content`
+ * is created so the docs collection endpoints see a readable (possibly empty)
+ * corpus instead of a missing configured content root.
+ *
+ * @param {string} name spec-unique directory name, relative to `<repo>/.tmp/`
+ * @param {Record<string, string>} documents repo-relative `content/...` path -> markdown
+ * @returns {string} absolute cache root for `DTC_CACHE_ROOT`
+ */
+function createDocsCacheRoot(name, documents = {}) {
+  const cacheRoot = path.join(TMP_ROOT, name);
+  fs.rmSync(cacheRoot, { recursive: true, force: true });
+  const contentRoot = path.join(cacheRoot, 'content');
+  fs.mkdirSync(contentRoot, { recursive: true });
+  for (const [repoPath, markdown] of Object.entries(documents)) {
+    const relative = repoPath.replace(/^content\//, '');
+    const target = path.join(contentRoot, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, markdown);
+  }
+  return cacheRoot;
+}
+
+module.exports = { createDocsCacheRoot, REPO_ROOT, TMP_ROOT };

backend/e2e/newsletter-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require("@playwright/test"),
   { spawn } = require("child_process"),
   http = require("http"),
   path = require("path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 const PORT = 3017,
   BASE = `http://127.0.0.1:${PORT}`;
 let child;
@@ -29,6 +30,7 @@ test.describe("production newsletter planner", () => {
         SKIP_AUTH: "true",
         DATAOPS_DOCS_DOMAIN: "1",
         DTC_OFFLINE: "1",
+        DTC_CACHE_ROOT: createDocsCacheRoot("issue-190-docs-cache/newsletter-production-portal"),
         FRONTEND_ROOT: path.resolve(__dirname, "..", "..", "frontend"),
         PORT: String(PORT),
       },

backend/e2e/planning-surfaces-design.spec.js

@@ -4,6 +4,7 @@ const { spawn } = require("child_process");
 const fs = require("fs");
 const http = require("http");
 const path = require("path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 
 const screenshots = path.resolve(__dirname, "..", "..", ".tmp", "screenshots", "planning-surfaces");
 const PORT = 3197;
@@ -102,6 +103,7 @@ test.beforeAll(async () => {
       SKIP_AUTH: "true",
       DATAOPS_DOCS_DOMAIN: "1",
       DTC_OFFLINE: "1",
+      DTC_CACHE_ROOT: createDocsCacheRoot("issue-190-docs-cache/planning-surfaces-design"),
       CONVERSATIONAL_TELEGRAM_INGRESS_ENABLED: "false",
       CONVERSATIONAL_EXECUTION_ENABLED: "false",
       CONVERSATIONAL_ENABLED_PLUGINS: "none",

backend/e2e/sponsor-crm-communications-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require('@playwright/test');
 const { spawn } = require('child_process');
 const http = require('http');
 const path = require('path');
+const { createDocsCacheRoot } = require('./helpers/docs-content-root');
 
 const PORT = 3016;
 const BASE_URL = `http://127.0.0.1:${PORT}`;
@@ -33,6 +34,7 @@ test.describe('production sponsor CRM communications portal', () => {
         SKIP_AUTH: 'true',
         DATAOPS_DOCS_DOMAIN: '1',
         DTC_OFFLINE: '1',
+        DTC_CACHE_ROOT: createDocsCacheRoot('issue-190-docs-cache/sponsor-crm-communications-production-portal'),
         FRONTEND_ROOT: path.resolve(__dirname, '..', '..', 'frontend'),
         PORT: String(PORT),
       },

backend/e2e/sponsor-crm-production-portal.spec.js

@@ -2,6 +2,7 @@ const { test, expect } = require("@playwright/test");
 const { spawn } = require("child_process");
 const http = require("http");
 const path = require("path");
+const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 const PORT = 3116,
   BASE_URL = `http://127.0.0.1:${PORT}`;
 let child;
@@ -31,6 +32,7 @@ test.describe("production sponsor CRM portal", () => {
         SKIP_AUTH: "true",
         DATAOPS_DOCS_DOMAIN: "1",
         DTC_OFFLINE: "1",
+        DTC_CACHE_ROOT: createDocsCacheRoot("issue-190-docs-cache/sponsor-crm-production-portal"),
         FRONTEND_ROOT: path.resolve(__dirname, "..", "..", "frontend"),
         PORT: String(PORT),
       },