quackage 1.2.2 → 1.2.4

package/docs/_brand.json

@@ -0,0 +1,18 @@
+{
+	"Hash": "quackage",
+	"Name": "Quackage",
+	"Tagline": "Standardized build tool for browser bundles, transpilation, testing, and packaging via Gulp and Browserify",
+	"Palette": "mix",
+	"Icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"frame-quackage-filled-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#1c93d7\"/>\n\t\t<g clip-path=\"url(#frame-quackage-filled-light)\"><rect x=\"20\" y=\"20\" width=\"56\" height=\"56\" rx=\"8\" fill=\"rgba(255,255,255,0.18)\"/>\n\t\t\t\t\t<path d=\"M 48 30 L 70 48 L 48 66 L 26 48 Z\" fill=\"#e76142\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"56\" font-weight=\"700\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">Q</text>\n\t</svg>",
+	"IconType": "svg",
+	"Favicon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-quackage-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#1c93d7\"/>\n\t\t<g clip-path=\"url(#fav-quackage-light)\"><rect x=\"16\" y=\"16\" width=\"64\" height=\"64\" rx=\"10\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">Q</text>\n\t</svg>",
+	"FaviconDark": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-quackage-dark\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tA 46 46 0 1 0 94 48\n\t\t\tA 46 46 0 1 0 2 48 Z\" fill=\"#69b8e6\"/>\n\t\t<g clip-path=\"url(#fav-quackage-dark)\"><rect x=\"16\" y=\"16\" width=\"64\" height=\"64\" rx=\"10\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#101418\" letter-spacing=\"-1\">Q</text>\n\t</svg>",
+	"Colors": {
+		"Primary": "#1c93d7",
+		"Secondary": "#e76142",
+		"PrimaryLight": "#1c93d7",
+		"PrimaryDark": "#69b8e6",
+		"SecondaryLight": "#e76142",
+		"SecondaryDark": "#eea897"
+	}
+}

package/docs/index.html

@@ -8,8 +8,6 @@
 
 		<title>Quackage v1.1.0 Documentation</title>
 
-		<!-- Application Stylesheet -->
-		<link href="css/docuserve.css" rel="stylesheet">
 		<!-- KaTeX stylesheet for LaTeX equation rendering -->
 		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
 		<!-- PICT Dynamic View CSS Container -->

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "quackage",
-    "version": "1.2.2",
+    "version": "1.2.4",
     "description": "Building.  Testing.  Quacking.  Reloading.",
     "main": "source/Quackage-CLIProgram.js",
     "scripts": {
@@ -60,14 +60,14 @@
         "gulp-env": "^0.4.0",
         "gulp-sourcemaps": "^3.0.0",
         "gulp-terser": "^2.1.0",
-        "indoctrinate": "^1.0.10",
+        "indoctrinate": "^1.0.12",
         "jsdoc": "^4.0.5",
         "mocha": "10.4.0",
         "npm-check-updates": "^18.0.1",
         "nyc": "^15.1.0",
-        "pict-provider-theme": "^0.0.3",
+        "pict-provider-theme": "^1.0.1",
         "pict-service-commandlineutility": "^1.0.19",
-        "retold-harness": "^1.1.10",
+        "retold-harness": "^1.1.12",
         "vinyl-buffer": "^1.0.1",
         "vinyl-source-stream": "^2.0.0"
     },
@@ -77,6 +77,6 @@
         }
     },
     "devDependencies": {
-        "pict-docuserve": "^0.1.5"
+        "pict-docuserve": "^1.3.2"
     }
 }

package/source/commands/Quackage-Command-PrepareDocs.js

@@ -18,6 +18,7 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 		this.options.CommandOptions.push({ Name: '-b, --branch [branch]', Description: 'Git branch for GitHub raw URLs (defaults to master).', Default: 'master' });
 		this.options.CommandOptions.push({ Name: '-g, --github_org [github_org]', Description: 'GitHub organization for raw URLs (defaults to stevenvelozo).', Default: 'stevenvelozo' });
 		this.options.CommandOptions.push({ Name: '-x, --excluded_modules [excluded_modules]', Description: 'Comma-separated list of module names to exclude from the catalog and keyword index.  Merged with any ExcludedModules list in indoctrinate\'s loaded config file (e.g. .indoctrinate.config.json).', Default: '' });
+		this.options.CommandOptions.push({ Name: '--docs_mode [docs_mode]', Description: 'Documentation scan mode: "module" (one module\'s docs/) or "ecosystem" (a folder of <group>/<module> repos).  Auto-detected when omitted — "module" when the scan root has a package.json, else "ecosystem".', Default: '' });
 
 		this.options.Aliases.push('docs');
 		this.options.Aliases.push('prep-docs');
@@ -77,13 +78,54 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 			tmpExtraScanArgs = ['-e', tmpDocsContentRoot];
 		}
 
+		// Documentation mode: "module" (a single module's docs/) vs
+		// "ecosystem" (a folder of <group>/<module> repos).  Auto-detected
+		// from whether the scan root is itself a package (has package.json);
+		// the --docs_mode option overrides.
+		let tmpDocsMode = (this.CommandOptions.docs_mode === 'module' || this.CommandOptions.docs_mode === 'ecosystem')
+			? this.CommandOptions.docs_mode
+			: (libFS.existsSync(libPath.join(tmpResolvedDirectoryRoot, 'package.json')) ? 'module' : 'ecosystem');
+		this.log.info(`Documentation mode: [${tmpDocsMode}] (scan root [${tmpResolvedDirectoryRoot}]).`);
+
+		// In single-module mode the catalog + keyword index describe one
+		// module — pass --single_module to indoctrinate.  The docs folder is
+		// already inside the scanned module root, so the -e extra scan is
+		// redundant there (and its content would lack the docs/ path segment).
+		let tmpSingleModuleArgs = [];
+		if (tmpDocsMode === 'module')
+		{
+			tmpSingleModuleArgs = ['-s'];
+			tmpExtraScanArgs = [];
+		}
+
 		let tmpAnticipate = this.fable.newAnticipate();
 
-		// Step 1: Generate the documentation catalog
+		// Step 1: Build and stage flagged example applications into the docs
+		// folder.  Runs first so any generated example index / quick-links
+		// markdown is on disk before the keyword index scans it into search.
+		// This is a clean no-op for modules with no flagged example
+		// applications, so it is safe to run everywhere prepare-docs runs.
+		tmpAnticipate.anticipate(
+			function (fNext)
+			{
+				this.log.info(`###############################[ STEP 1: STAGE EXAMPLE APPLICATIONS ]###############################`);
+				this.fable.QuackageProcess.execute(
+					tmpDocuserveLocation,
+					[
+						'stage-examples',
+						tmpDocsFolder,
+						'-m', tmpDirectoryRoot
+					],
+					{ cwd: this.fable.AppData.CWD },
+					fNext
+				);
+			}.bind(this));
+
+		// Step 2: Generate the documentation catalog
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 1: INDOCTRINATE CATALOG ]###############################`);
+				this.log.info(`###############################[ STEP 2: INDOCTRINATE CATALOG ]###############################`);
 				this.fable.QuackageProcess.execute(
 					tmpIndoctrinateLocation,
 					[
@@ -92,34 +134,34 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 						'-o', tmpCatalogFile,
 						'-b', tmpBranch,
 						'-g', tmpGitHubOrg
-					].concat(tmpExcludedModulesArgs),
+					].concat(tmpSingleModuleArgs).concat(tmpExcludedModulesArgs),
 					{ cwd: this.fable.AppData.CWD },
 					fNext
 				);
 			}.bind(this));
 
-		// Step 2: Generate the keyword search index
+		// Step 3: Generate the keyword search index
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 2: KEYWORD INDEX ]###############################`);
+				this.log.info(`###############################[ STEP 3: KEYWORD INDEX ]###############################`);
 				this.fable.QuackageProcess.execute(
 					tmpIndoctrinateLocation,
 					[
 						'generate_keyword_index',
 						'-d', tmpDirectoryRoot,
 						'-o', tmpKeywordIndexFile
-					].concat(tmpExtraScanArgs).concat(tmpExcludedModulesArgs),
+					].concat(tmpSingleModuleArgs).concat(tmpExtraScanArgs).concat(tmpExcludedModulesArgs),
 					{ cwd: this.fable.AppData.CWD },
 					fNext
 				);
 			}.bind(this));
 
-		// Step 3: Write _version.json version placard sidecar
+		// Step 4: Write _version.json version placard sidecar
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 3: VERSION PLACARD ]###############################`);
+				this.log.info(`###############################[ STEP 4: VERSION PLACARD ]###############################`);
 				try
 				{
 					let tmpPackageJsonPath = libPath.join(tmpDirectoryRoot, 'package.json');
@@ -163,11 +205,11 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 				return fNext();
 			}.bind(this));
 
-		// Step 4: Inject pict-docuserve assets
+		// Step 5: Inject pict-docuserve assets
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 4: DOCUSERVE INJECT ]###############################`);
+				this.log.info(`###############################[ STEP 5: DOCUSERVE INJECT ]###############################`);
 				this.fable.QuackageProcess.execute(
 					tmpDocuserveLocation,
 					[
@@ -179,14 +221,14 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 				);
 			}.bind(this));
 
-		// Step 5: Stamp meaningful <title> and <meta name="description">
+		// Step 6: Stamp meaningful <title> and <meta name="description">
 		// into the freshly-injected index.html so social-card scrapers
 		// (Slack, etc.) read the module name + version instead of the
 		// generic "powered by pict-docuserve" boilerplate.
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 5: STAMP HTML METADATA ]###############################`);
+				this.log.info(`###############################[ STEP 6: STAMP HTML METADATA ]###############################`);
 				try
 				{
 					let tmpIndexPath = libPath.join(tmpDocsFolder, 'index.html');

package/source/services/Quackage-ExampleService.js

@@ -2,6 +2,8 @@ const libPict = require('pict');
 const libFS = require('fs');
 const libPath = require('path');
 const libHTTP = require('http');
+const libHTTPS = require('https');
+const libURL = require('url');
 
 const libFable = require('fable');
 const libBookstoreSchema = require('retold-harness/source/schemas/Retold-Harness-Service-Schema-Bookstore.js');
@@ -207,8 +209,8 @@ class QuackageExampleService extends libPict.ServiceProviderBase
 
 		/* --- Header Bar --- */
 		.pict-example-header { display: flex; align-items: stretch; background: #264653; border-bottom: 3px solid #E76F51; }
-		.pict-example-badge { background: #E76F51; color: #fff; padding: 0.6rem 1rem; font-size: 0.7rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.1em; display: flex; align-items: center; gap: 0.5rem; }
-		.pict-example-badge svg { width: 14px; height: 14px; fill: #fff; flex-shrink: 0; }
+		.pict-example-badge { background: #E76F51; color: var(--theme-color-background-panel, #fff); padding: 0.6rem 1rem; font-size: 0.7rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.1em; display: flex; align-items: center; gap: 0.5rem; }
+		.pict-example-badge svg { width: 14px; height: 14px; fill: var(--theme-color-background-panel, #fff); flex-shrink: 0; }
 		.pict-example-app-name { padding: 0.6rem 1rem; color: #FAEDCD; font-size: 1.1rem; font-weight: 600; display: flex; align-items: center; }
 		.pict-example-module { margin-left: auto; padding: 0.6rem 1rem; color: #D4A373; font-size: 0.75rem; display: flex; align-items: center; letter-spacing: 0.03em; }
 
@@ -219,7 +221,7 @@ class QuackageExampleService extends libPict.ServiceProviderBase
 
 		/* --- Example List --- */
 		.example-list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0.5rem; }
-		.example-list li { background: #fff; border: 1px solid #D4A373; border-left: 4px solid #E76F51; border-radius: 4px; transition: border-color 0.15s, box-shadow 0.15s; }
+		.example-list li { background: var(--theme-color-background-panel, #fff); border: 1px solid #D4A373; border-left: 4px solid #E76F51; border-radius: 4px; transition: border-color 0.15s, box-shadow 0.15s; }
 		.example-list li:hover { border-left-color: #264653; box-shadow: 0 2px 8px rgba(38,70,83,0.1); }
 		.example-list a { display: block; padding: 0.75rem 1rem; text-decoration: none; color: #264653; font-weight: 500; font-size: 0.95rem; }
 		.example-list a:hover { color: #E76F51; }
@@ -533,6 +535,235 @@ ${tmpExampleListItems}		</ul>
 			});
 	}
 
+	// --- Serve static + reverse-proxy a configured upstream ---
+
+	/**
+	 * Serve example files out of pExamplesFolder, but reverse-proxy any request
+	 * whose path starts with one of pProxyConfig.paths to pProxyConfig.upstream.
+	 *
+	 * Used by mode='proxy' so cookie-credentialed APIs (Headlight, etc.) appear
+	 * same-origin to the browser and CORS doesn't get in the way.
+	 */
+	serveStaticWithProxy(pExamplesFolder, pIndexHTML, pPort, pExamples, pProjectName, pProxyConfig, fCallback)
+	{
+		const tmpUpstreamParsed = libURL.parse(pProxyConfig.upstream);
+		const tmpUpstreamClient = (tmpUpstreamParsed.protocol === 'https:') ? libHTTPS : libHTTP;
+		const tmpUpstreamHost = tmpUpstreamParsed.host;
+		const tmpUpstreamOrigin = `${tmpUpstreamParsed.protocol}//${tmpUpstreamHost}`;
+
+		const tmpShouldProxy = (pRequestPath) =>
+		{
+			for (let i = 0; i < pProxyConfig.paths.length; i++)
+			{
+				if (pRequestPath === pProxyConfig.paths[i] || pRequestPath.indexOf(pProxyConfig.paths[i]) === 0)
+				{
+					return true;
+				}
+			}
+			return false;
+		};
+
+		const tmpRewriteSetCookie = (pCookies) =>
+		{
+			if (!pCookies) { return pCookies; }
+			const tmpArray = Array.isArray(pCookies) ? pCookies : [pCookies];
+			return tmpArray.map((pCookie) => String(pCookie)
+				.replace(/;\s*Domain=[^;]+/i, '')
+				.replace(/;\s*Secure/i, ''));
+		};
+
+		const tmpProxyRequest = (pRequest, pResponse) =>
+		{
+			const tmpProxyHeaders = Object.assign({}, pRequest.headers);
+			if (pProxyConfig.rewriteOrigin)
+			{
+				tmpProxyHeaders.host = tmpUpstreamHost;
+				if (tmpProxyHeaders.origin)  { tmpProxyHeaders.origin  = tmpUpstreamOrigin; }
+				if (tmpProxyHeaders.referer) { tmpProxyHeaders.referer = tmpUpstreamOrigin + '/'; }
+			}
+			delete tmpProxyHeaders['accept-encoding'];
+
+			const tmpProxyOptions =
+			{
+				protocol: tmpUpstreamParsed.protocol,
+				hostname: tmpUpstreamParsed.hostname,
+				port:     tmpUpstreamParsed.port || (tmpUpstreamParsed.protocol === 'https:' ? 443 : 80),
+				method:   pRequest.method,
+				path:     pRequest.url,
+				headers:  tmpProxyHeaders
+			};
+
+			const tmpProxyReq = tmpUpstreamClient.request(tmpProxyOptions, (pProxyRes) =>
+			{
+				const tmpResponseHeaders = Object.assign({}, pProxyRes.headers);
+				if (pProxyConfig.rewriteCookies && tmpResponseHeaders['set-cookie'])
+				{
+					tmpResponseHeaders['set-cookie'] = tmpRewriteSetCookie(tmpResponseHeaders['set-cookie']);
+				}
+				pResponse.writeHead(pProxyRes.statusCode || 502, tmpResponseHeaders);
+				pProxyRes.pipe(pResponse);
+			});
+
+			tmpProxyReq.on('error', (pError) =>
+			{
+				this.log.error(`Proxy upstream error for ${pRequest.method} ${pRequest.url}: ${pError.message}`);
+				if (!pResponse.headersSent)
+				{
+					pResponse.writeHead(502, { 'Content-Type': 'text/plain' });
+				}
+				pResponse.end(`Bad gateway: ${pError.message}`);
+			});
+
+			pRequest.pipe(tmpProxyReq);
+		};
+
+		const tmpServeStaticFile = (pRequest, pResponse) =>
+		{
+			let tmpRequestURL = pRequest.url.split('?')[0];
+
+			if (tmpRequestURL === '/' || tmpRequestURL === '/index.html')
+			{
+				pResponse.writeHead(200, { 'Content-Type': 'text/html' });
+				pResponse.end(pIndexHTML);
+				return;
+			}
+
+			let tmpFilePath = libPath.join(pExamplesFolder, decodeURIComponent(tmpRequestURL));
+			if (!tmpFilePath.startsWith(pExamplesFolder))
+			{
+				pResponse.writeHead(403);
+				pResponse.end('Forbidden');
+				return;
+			}
+			if (libFS.existsSync(tmpFilePath) && libFS.statSync(tmpFilePath).isDirectory())
+			{
+				tmpFilePath = libPath.join(tmpFilePath, 'index.html');
+			}
+			if (!libFS.existsSync(tmpFilePath))
+			{
+				pResponse.writeHead(404);
+				pResponse.end('Not Found');
+				return;
+			}
+
+			let tmpExtension = libPath.extname(tmpFilePath).toLowerCase();
+			let tmpMimeType = this.getMimeType(tmpExtension);
+			try
+			{
+				let tmpContent = libFS.readFileSync(tmpFilePath);
+				pResponse.writeHead(200, { 'Content-Type': tmpMimeType });
+				pResponse.end(tmpContent);
+			}
+			catch (pReadError)
+			{
+				pResponse.writeHead(500);
+				pResponse.end('Internal Server Error');
+			}
+		};
+
+		const tmpServer = libHTTP.createServer((pRequest, pResponse) =>
+		{
+			const tmpPath = pRequest.url.split('?')[0];
+			if (tmpShouldProxy(tmpPath))
+			{
+				tmpProxyRequest(pRequest, pResponse);
+			}
+			else
+			{
+				tmpServeStaticFile(pRequest, pResponse);
+			}
+		});
+
+		tmpServer.listen(pPort, () =>
+		{
+			this.log.info(`##############################################`);
+			this.log.info(`  Example server running at http://localhost:${pPort}/`);
+			this.log.info(`  Project: ${pProjectName}`);
+			this.log.info(`  Proxy upstream: ${pProxyConfig.upstream}`);
+			this.log.info(`  Proxied paths:  ${pProxyConfig.paths.join(', ')}`);
+			this.log.info(`  Serving ${pExamples.length} example(s):`);
+			for (let i = 0; i < pExamples.length; i++)
+			{
+				this.log.info(`    - ${pExamples[i].DisplayName}: http://localhost:${pPort}/${pExamples[i].RelativePath}`);
+			}
+			this.log.info(`##############################################`);
+			this.log.info(`Press Ctrl+C to stop.`);
+		});
+
+		tmpServer.on('error', (pError) =>
+		{
+			if (pError.code === 'EADDRINUSE')
+			{
+				this.log.error(`Port ${pPort} is already in use.  Try specifying a different port with -p.`);
+			}
+			else
+			{
+				this.log.error(`Server error: ${pError.message}`);
+			}
+			return fCallback(pError);
+		});
+	}
+
+	// --- Per-project examples configuration ---
+
+	/**
+	 * Resolve the host project's examples configuration from its package.json.
+	 * Reads `quackageExamples` (preferred) or `quack.examples` (alias).
+	 *
+	 * Recognised shapes:
+	 *
+	 *   "quackageExamples": { "mode": "bookstore" }   // default — Meadow + SQLite + bookstore data
+	 *   "quackageExamples": { "mode": "static"   }    // serve files only, no API
+	 *   "quackageExamples": {
+	 *       "mode": "proxy",
+	 *       "proxy": {
+	 *           "upstream": "https://fieldbook.qa.headlight.com",
+	 *           "paths": ["/1.0/", "/CheckSession", "/Authenticate", "/Report/"],
+	 *           "rewriteCookies": true,
+	 *           "rewriteOrigin":  true
+	 *       }
+	 *   }
+	 *
+	 * Defaults (mode='proxy'):
+	 *   paths           = ["/1.0/"]
+	 *   rewriteCookies  = true     (strip Domain= and Secure so localhost keeps the session)
+	 *   rewriteOrigin   = true     (rewrite Host/Origin/Referer to the upstream)
+	 */
+	resolveExamplesConfig()
+	{
+		const tmpPackage = (this.fable && this.fable.AppData && this.fable.AppData.Package) || {};
+		const tmpRaw = tmpPackage.quackageExamples
+			|| (tmpPackage.quack && tmpPackage.quack.examples)
+			|| {};
+
+		const tmpMode = (typeof tmpRaw.mode === 'string') ? tmpRaw.mode.toLowerCase() : 'bookstore';
+		const tmpResolved = { mode: tmpMode };
+
+		if (tmpMode === 'proxy')
+		{
+			const tmpProxy = tmpRaw.proxy || {};
+			tmpResolved.proxy =
+			{
+				upstream:       (typeof tmpProxy.upstream === 'string' && tmpProxy.upstream) ? tmpProxy.upstream.replace(/\/+$/, '') : null,
+				paths:          (Array.isArray(tmpProxy.paths) && tmpProxy.paths.length) ? tmpProxy.paths.slice() : ['/1.0/'],
+				rewriteCookies: (tmpProxy.rewriteCookies !== false),
+				rewriteOrigin:  (tmpProxy.rewriteOrigin !== false)
+			};
+			// Allow env-var override for the upstream so devs can switch envs without
+			// editing package.json: `UPSTREAM=https://fieldbook.headlight.com npx quack examples`.
+			if (process.env.QUACKAGE_PROXY_UPSTREAM)
+			{
+				tmpResolved.proxy.upstream = process.env.QUACKAGE_PROXY_UPSTREAM.replace(/\/+$/, '');
+			}
+			else if (process.env.UPSTREAM)
+			{
+				tmpResolved.proxy.upstream = process.env.UPSTREAM.replace(/\/+$/, '');
+			}
+		}
+
+		return tmpResolved;
+	}
+
 	// --- Serve examples ---
 
 	serveExamples(pExamplesFolder, pPort, fCallback)
@@ -555,7 +786,28 @@ ${tmpExampleListItems}		</ul>
 
 		let tmpIndexHTML = this.generateIndexHTML(tmpProjectName, tmpExamples, tmpPort);
 
-		// Initialize the bookstore API (retold-harness + SQLite)
+		const tmpConfig = this.resolveExamplesConfig();
+
+		if (tmpConfig.mode === 'proxy')
+		{
+			if (!tmpConfig.proxy.upstream)
+			{
+				this.log.error(`quackageExamples.mode is 'proxy' but no upstream URL was configured.`);
+				this.log.error(`Set quackageExamples.proxy.upstream in package.json (or QUACKAGE_PROXY_UPSTREAM / UPSTREAM env var).`);
+				return fCallback(new Error('Proxy mode requires an upstream.'));
+			}
+			this.log.info(`Examples mode: proxy → ${tmpConfig.proxy.upstream}`);
+			this.log.info(`Proxying paths: ${tmpConfig.proxy.paths.join(', ')}`);
+			return this.serveStaticWithProxy(tmpExamplesFolder, tmpIndexHTML, tmpPort, tmpExamples, tmpProjectName, tmpConfig.proxy, fCallback);
+		}
+
+		if (tmpConfig.mode === 'static')
+		{
+			this.log.info(`Examples mode: static (no API)`);
+			return this.serveStaticHTTP(tmpExamplesFolder, tmpIndexHTML, tmpPort, fCallback);
+		}
+
+		// Default: bookstore API
 		this.log.info(`Initializing bookstore API with SQLite ...`);
 		this.initializeBookstoreAPI(tmpPort, tmpExamplesFolder,
 			(pError, pHarnessFable) =>

package/docs/css/docuserve.css

@@ -1,327 +0,0 @@
-/* ============================================================================
-   Pict Docuserve - Base Styles & Theme Variables
-   ============================================================================ */
-
-/* ----------------------------------------------------------------------------
-   Theme variables — light defaults on :root.
-   Dark mode applies when either:
-     (a) the user explicitly selected dark via <html data-theme="dark">
-     (b) the user hasn't chosen anything AND the system prefers dark
-   An explicit <html data-theme="light"> pins the light palette regardless.
-   ---------------------------------------------------------------------------- */
-
-:root
-{
-	/* Surfaces */
-	--docuserve-bg: #FDFBF7;
-	--docuserve-bg-elevated: #FFFFFF;
-	--docuserve-border: #DDD6CA;
-	--docuserve-border-soft: #EAE3D8;
-
-	/* Text */
-	--docuserve-text: #2A241E;
-	--docuserve-text-strong: #3D3229;
-	--docuserve-text-muted: #5E5549;
-	--docuserve-text-dim: #8A7F72;
-
-	/* Accent / links */
-	--docuserve-accent: #2E7D74;
-	--docuserve-accent-hover: #236660;
-
-	/* Top bar */
-	--docuserve-topbar-bg: #3D3229;
-	--docuserve-topbar-text: #E8E0D4;
-	--docuserve-topbar-text-muted: #B5AA9A;
-	--docuserve-topbar-text-dim: #8A7F72;
-	--docuserve-topbar-hover-bg: #524438;
-	--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.06);
-	--docuserve-topbar-version-border: rgba(255, 255, 255, 0.08);
-	--docuserve-topbar-version-text: #B5AA9A;
-
-	/* Sidebar */
-	--docuserve-sidebar-bg: #FAF7F1;
-	--docuserve-sidebar-border: #DDD6CA;
-	--docuserve-sidebar-border-soft: #E5DED1;
-	--docuserve-sidebar-text: #423D37;
-	--docuserve-sidebar-group-title: #3D3229;
-	--docuserve-sidebar-module-text: #5E5549;
-	--docuserve-sidebar-hover-bg: #EAE3D8;
-	--docuserve-sidebar-hover-text: #2E7D74;
-	--docuserve-sidebar-active-bg: #E5DED1;
-	--docuserve-sidebar-active-text: #2E7D74;
-	--docuserve-sidebar-search-bg: #FFFFFF;
-	--docuserve-sidebar-search-border: #DDD6CA;
-
-	/* Inline code */
-	--docuserve-inline-code-bg: #F0ECE4;
-	--docuserve-inline-code-text: #9E3A50;
-
-	/* Code block panel */
-	--docuserve-code-bg: #F6F3EE;
-	--docuserve-code-border: #E5DED1;
-	--docuserve-code-gutter-bg: #EFEAE0;
-	--docuserve-code-gutter-border: #DDD6CA;
-	--docuserve-code-gutter-text: #A59986;
-	--docuserve-code-text: #2A241E;
-
-	/* Syntax tokens — low-chroma dark-on-light palette */
-	--docuserve-tok-keyword: #A03472;
-	--docuserve-tok-string: #1A6640;
-	--docuserve-tok-number: #B25A00;
-	--docuserve-tok-comment: #8A7F72;
-	--docuserve-tok-operator: #2E7D74;
-	--docuserve-tok-punctuation: #2A241E;
-	--docuserve-tok-function: #2A5DB0;
-	--docuserve-tok-property: #9E3A50;
-	--docuserve-tok-tag: #9E3A50;
-	--docuserve-tok-attr-name: #B25A00;
-	--docuserve-tok-attr-value: #1A6640;
-
-	/* Tables, blockquotes, mermaid */
-	--docuserve-table-header-bg: #F5F0E8;
-	--docuserve-table-row-alt-bg: #F9F6F0;
-	--docuserve-blockquote-bg: #F7F5F0;
-	--docuserve-blockquote-border: #2E7D74;
-	--docuserve-blockquote-text: #5E5549;
-	--docuserve-mermaid-bg: #FFFFFF;
-
-	/* Scrollbars */
-	--docuserve-scrollbar-track: #F5F0E8;
-	--docuserve-scrollbar-thumb: #D4CCBE;
-	--docuserve-scrollbar-thumb-hover: #B5AA9A;
-}
-
-@media (prefers-color-scheme: dark)
-{
-	:root:not([data-theme="light"])
-	{
-		--docuserve-bg: #15120F;
-		--docuserve-bg-elevated: #1B1814;
-		--docuserve-border: #2F2823;
-		--docuserve-border-soft: #26211C;
-
-		--docuserve-text: #E8E0D4;
-		--docuserve-text-strong: #F2ECE0;
-		--docuserve-text-muted: #B5AA9A;
-		--docuserve-text-dim: #7A6F62;
-
-		--docuserve-accent: #5DB8A8;
-		--docuserve-accent-hover: #7FCCB8;
-
-		--docuserve-topbar-bg: #1A1612;
-		--docuserve-topbar-text: #E8E0D4;
-		--docuserve-topbar-text-muted: #B5AA9A;
-		--docuserve-topbar-text-dim: #7A6F62;
-		--docuserve-topbar-hover-bg: #2A241E;
-		--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.05);
-		--docuserve-topbar-version-border: rgba(255, 255, 255, 0.09);
-		--docuserve-topbar-version-text: #B5AA9A;
-
-		--docuserve-sidebar-bg: #1B1814;
-		--docuserve-sidebar-border: #2F2823;
-		--docuserve-sidebar-border-soft: #26211C;
-		--docuserve-sidebar-text: #C9C0B3;
-		--docuserve-sidebar-group-title: #F2ECE0;
-		--docuserve-sidebar-module-text: #B5AA9A;
-		--docuserve-sidebar-hover-bg: #2A241E;
-		--docuserve-sidebar-hover-text: #7FCCB8;
-		--docuserve-sidebar-active-bg: #2F2823;
-		--docuserve-sidebar-active-text: #7FCCB8;
-		--docuserve-sidebar-search-bg: #26211C;
-		--docuserve-sidebar-search-border: #2F2823;
-
-		--docuserve-inline-code-bg: #2A241E;
-		--docuserve-inline-code-text: #E8B07A;
-
-		--docuserve-code-bg: #1E1A17;
-		--docuserve-code-border: #2F2823;
-		--docuserve-code-gutter-bg: #17130F;
-		--docuserve-code-gutter-border: #2F2823;
-		--docuserve-code-gutter-text: #6A6052;
-		--docuserve-code-text: #E8E0D4;
-
-		--docuserve-tok-keyword: #C678DD;
-		--docuserve-tok-string: #98C379;
-		--docuserve-tok-number: #D19A66;
-		--docuserve-tok-comment: #7F848E;
-		--docuserve-tok-operator: #56B6C2;
-		--docuserve-tok-punctuation: #E8E0D4;
-		--docuserve-tok-function: #61AFEF;
-		--docuserve-tok-property: #E06C75;
-		--docuserve-tok-tag: #E06C75;
-		--docuserve-tok-attr-name: #D19A66;
-		--docuserve-tok-attr-value: #98C379;
-
-		--docuserve-table-header-bg: #26211C;
-		--docuserve-table-row-alt-bg: #1F1B17;
-		--docuserve-blockquote-bg: #1F1B17;
-		--docuserve-blockquote-border: #5DB8A8;
-		--docuserve-blockquote-text: #C9C0B3;
-		--docuserve-mermaid-bg: #E8E0D4;
-
-		--docuserve-scrollbar-track: #1B1814;
-		--docuserve-scrollbar-thumb: #3A322B;
-		--docuserve-scrollbar-thumb-hover: #524438;
-	}
-}
-
-:root[data-theme="dark"]
-{
-	--docuserve-bg: #15120F;
-	--docuserve-bg-elevated: #1B1814;
-	--docuserve-border: #2F2823;
-	--docuserve-border-soft: #26211C;
-
-	--docuserve-text: #E8E0D4;
-	--docuserve-text-strong: #F2ECE0;
-	--docuserve-text-muted: #B5AA9A;
-	--docuserve-text-dim: #7A6F62;
-
-	--docuserve-accent: #5DB8A8;
-	--docuserve-accent-hover: #7FCCB8;
-
-	--docuserve-topbar-bg: #1A1612;
-	--docuserve-topbar-text: #E8E0D4;
-	--docuserve-topbar-text-muted: #B5AA9A;
-	--docuserve-topbar-text-dim: #7A6F62;
-	--docuserve-topbar-hover-bg: #2A241E;
-	--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.05);
-	--docuserve-topbar-version-border: rgba(255, 255, 255, 0.09);
-	--docuserve-topbar-version-text: #B5AA9A;
-
-	--docuserve-sidebar-bg: #1B1814;
-	--docuserve-sidebar-border: #2F2823;
-	--docuserve-sidebar-border-soft: #26211C;
-	--docuserve-sidebar-text: #C9C0B3;
-	--docuserve-sidebar-group-title: #F2ECE0;
-	--docuserve-sidebar-module-text: #B5AA9A;
-	--docuserve-sidebar-hover-bg: #2A241E;
-	--docuserve-sidebar-hover-text: #7FCCB8;
-	--docuserve-sidebar-active-bg: #2F2823;
-	--docuserve-sidebar-active-text: #7FCCB8;
-	--docuserve-sidebar-search-bg: #26211C;
-	--docuserve-sidebar-search-border: #2F2823;
-
-	--docuserve-inline-code-bg: #2A241E;
-	--docuserve-inline-code-text: #E8B07A;
-
-	--docuserve-code-bg: #1E1A17;
-	--docuserve-code-border: #2F2823;
-	--docuserve-code-gutter-bg: #17130F;
-	--docuserve-code-gutter-border: #2F2823;
-	--docuserve-code-gutter-text: #6A6052;
-	--docuserve-code-text: #E8E0D4;
-
-	--docuserve-tok-keyword: #C678DD;
-	--docuserve-tok-string: #98C379;
-	--docuserve-tok-number: #D19A66;
-	--docuserve-tok-comment: #7F848E;
-	--docuserve-tok-operator: #56B6C2;
-	--docuserve-tok-punctuation: #E8E0D4;
-	--docuserve-tok-function: #61AFEF;
-	--docuserve-tok-property: #E06C75;
-	--docuserve-tok-tag: #E06C75;
-	--docuserve-tok-attr-name: #D19A66;
-	--docuserve-tok-attr-value: #98C379;
-
-	--docuserve-table-header-bg: #26211C;
-	--docuserve-table-row-alt-bg: #1F1B17;
-	--docuserve-blockquote-bg: #1F1B17;
-	--docuserve-blockquote-border: #5DB8A8;
-	--docuserve-blockquote-text: #C9C0B3;
-	--docuserve-mermaid-bg: #E8E0D4;
-
-	--docuserve-scrollbar-track: #1B1814;
-	--docuserve-scrollbar-thumb: #3A322B;
-	--docuserve-scrollbar-thumb-hover: #524438;
-}
-
-/* ----------------------------------------------------------------------------
-   Reset and base
-   ---------------------------------------------------------------------------- */
-
-*, *::before, *::after
-{
-	box-sizing: border-box;
-}
-
-html, body
-{
-	margin: 0;
-	padding: 0;
-	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-	font-size: 16px;
-	line-height: 1.5;
-	color: var(--docuserve-text);
-	background-color: var(--docuserve-bg);
-	-webkit-font-smoothing: antialiased;
-	-moz-osx-font-smoothing: grayscale;
-	transition: background-color 0.15s ease, color 0.15s ease;
-}
-
-/* Typography */
-h1, h2, h3, h4, h5, h6
-{
-	margin-top: 0;
-	line-height: 1.3;
-	color: var(--docuserve-text-strong);
-}
-
-a
-{
-	color: var(--docuserve-accent);
-	text-decoration: none;
-}
-
-a:hover
-{
-	color: var(--docuserve-accent-hover);
-}
-
-/* Application container */
-#Docuserve-Application-Container
-{
-	min-height: 100vh;
-}
-
-/* Utility: scrollbar styling */
-::-webkit-scrollbar
-{
-	width: 8px;
-	height: 8px;
-}
-
-::-webkit-scrollbar-track
-{
-	background: var(--docuserve-scrollbar-track);
-}
-
-::-webkit-scrollbar-thumb
-{
-	background: var(--docuserve-scrollbar-thumb);
-	border-radius: 4px;
-}
-
-::-webkit-scrollbar-thumb:hover
-{
-	background: var(--docuserve-scrollbar-thumb-hover);
-}
-
-/* Responsive adjustments */
-@media (max-width: 768px)
-{
-	html
-	{
-		font-size: 14px;
-	}
-
-	#Docuserve-Sidebar-Container
-	{
-		display: none;
-	}
-
-	.docuserve-body
-	{
-		flex-direction: column;
-	}
-}