@norskvideo/ctl-sdk 0.1.21 → 0.1.23

package/docs-router.d.ts

@@ -0,0 +1,21 @@
+import { type Express } from "express";
+/**
+ * Where a product's docs bundle (dev-kit doc-guide `buildBundle`) is, given the
+ * backend's own directory — or null when the product shipped none.
+ *
+ * Two layouts, one relative path: the image bakes the bundle at `<app>/docs`
+ * beside `backend/` (Dockerfile.bundle), a repo checkout has it at
+ * `<repo>/docs/generated/bundle`; from `backend/dist` and `backend/src`
+ * respectively both are `../../docs`. The image's `docs/` exists even when
+ * empty, so presence is judged by `bundle.json`, not the directory.
+ */
+export declare function docsBundleDir(fromDir: string): string | null;
+/**
+ * Mount the docs bundle at `/docs`: `manual.html` as the index, `bundle.json`,
+ * `pages/*.md` and `captures/*` by path. Returns whether anything was mounted,
+ * so a product without a bundle boots exactly as before. `/docs` redirects to
+ * `/docs/` with a root-absolute Location, which the daemon's product proxy
+ * rewrites under `/products/<name>` — so the manual's hash routing works
+ * through the daemon too.
+ */
+export declare function serveDocs(app: Express, dir: string | null): boolean;

package/docs-router.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import express from "express";
+/**
+ * Where a product's docs bundle (dev-kit doc-guide `buildBundle`) is, given the
+ * backend's own directory — or null when the product shipped none.
+ *
+ * Two layouts, one relative path: the image bakes the bundle at `<app>/docs`
+ * beside `backend/` (Dockerfile.bundle), a repo checkout has it at
+ * `<repo>/docs/generated/bundle`; from `backend/dist` and `backend/src`
+ * respectively both are `../../docs`. The image's `docs/` exists even when
+ * empty, so presence is judged by `bundle.json`, not the directory.
+ */
+export function docsBundleDir(fromDir) {
+    const docs = resolve(fromDir, "../../docs");
+    for (const candidate of [docs, resolve(docs, "generated/bundle")]) {
+        if (existsSync(resolve(candidate, "bundle.json")))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Mount the docs bundle at `/docs`: `manual.html` as the index, `bundle.json`,
+ * `pages/*.md` and `captures/*` by path. Returns whether anything was mounted,
+ * so a product without a bundle boots exactly as before. `/docs` redirects to
+ * `/docs/` with a root-absolute Location, which the daemon's product proxy
+ * rewrites under `/products/<name>` — so the manual's hash routing works
+ * through the daemon too.
+ */
+export function serveDocs(app, dir) {
+    if (!dir)
+        return false;
+    app.use("/docs", express.static(dir, { index: "manual.html" }));
+    return true;
+}

package/index.d.ts

@@ -3,6 +3,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./docs-router.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";

package/index.js

@@ -5,6 +5,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./docs-router.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";

package/manifest-fetch.d.ts

@@ -17,7 +17,18 @@ export declare function specBaseUrl(spec: ProductSpec, port?: number, reachHost?
  *  so a recorded reachHost is never forgotten. */
 export declare function productBaseUrl(reg: Pick<ProductRegistration, "spec" | "port" | "reachHost">): string;
 export declare function fetchManifest(baseUrl: string): Promise<Manifest>;
-export declare function waitForReady(baseUrl: string): Promise<void>;
+/** Poll a product's manifest until it answers.
+ *
+ *  The timeout names `baseUrl`. That is the whole point of the message: the
+ *  daemon dials a container product on loopback, and where that loopback is not
+ *  the daemon's own (a docker-outside-of-docker runner, where it belongs to the
+ *  docker host — see product-reach.ts) the product is perfectly healthy and
+ *  simply unreachable. Without the address, that reads identically to a product
+ *  that genuinely failed to start. */
+export declare function waitForReady(baseUrl: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;
 /**
  * Probe the product's configScreenUrl after registration. Two hard
  * rejections:

package/manifest-fetch.js

@@ -56,8 +56,18 @@ export async function fetchManifest(baseUrl) {
     }
     return parsed.data;
 }
-export async function waitForReady(baseUrl) {
-    const deadline = Date.now() + READINESS_TIMEOUT_MS;
+/** Poll a product's manifest until it answers.
+ *
+ *  The timeout names `baseUrl`. That is the whole point of the message: the
+ *  daemon dials a container product on loopback, and where that loopback is not
+ *  the daemon's own (a docker-outside-of-docker runner, where it belongs to the
+ *  docker host — see product-reach.ts) the product is perfectly healthy and
+ *  simply unreachable. Without the address, that reads identically to a product
+ *  that genuinely failed to start. */
+export async function waitForReady(baseUrl, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? READINESS_TIMEOUT_MS;
+    const intervalMs = opts.intervalMs ?? READINESS_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         try {
             const r = await fetch(`${baseUrl}/manifest.json`);
@@ -67,9 +77,9 @@ export async function waitForReady(baseUrl) {
         catch {
             // not ready yet
         }
-        await new Promise((resolve) => setTimeout(resolve, READINESS_INTERVAL_MS));
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
-    throw new ProductError("READINESS_TIMEOUT", `product did not become ready within ${READINESS_TIMEOUT_MS}ms`);
+    throw new ProductError("READINESS_TIMEOUT", `product did not become ready within ${timeoutMs}ms — nothing answered ${baseUrl}/manifest.json`);
 }
 /**
  * Probe the product's configScreenUrl after registration. Two hard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "exports": {
     ".": {
@@ -37,7 +37,7 @@
   "types": "./index.d.ts",
   "dependencies": {
     "@norskvideo/ctl-foundation": "^0.1.0",
-    "@norskvideo/ctl-product-template-schema": "^0.1.5",
+    "@norskvideo/ctl-product-template-schema": "^0.1.12",
     "express": "5",
     "lucide-react": "^0.483.0",
     "react": "^19.0.0",

package/product-service.js

@@ -127,7 +127,7 @@ export class ProductService {
             }
             port = allocated;
             await this.refreshImage(spec.image);
-            logger.info(`Starting product container: ${spec.image} on host port ${port}`);
+            logger.info(`Starting product container: ${spec.image} on host port ${port} (reach: ${this.reach})`);
             containerId = await this.containerOps.run(spec.image, port);
             reachHost = await this.reachHostFor(containerId);
             baseUrl = specBaseUrl(spec, port, reachHost);