retold-content-system 1.0.0

package/source/Pict-Application-ContentReader-Configuration.json

@@ -0,0 +1,15 @@
+{
+	"Name": "Retold Content Reader",
+	"Hash": "ContentReader",
+
+	"MainViewportViewIdentifier": "Docuserve-Layout",
+
+	"AutoSolveAfterInitialize": true,
+	"AutoRenderMainViewportViewAfterInitialize": false,
+	"AutoRenderViewsAfterInitialize": false,
+
+	"pict_configuration":
+		{
+			"Product": "ContentReader-Pict-Application"
+		}
+}

package/source/Pict-Application-ContentReader.js

@@ -0,0 +1,91 @@
+const libDocuserveApplication = require('pict-docuserve');
+
+/**
+ * Content Reader Application
+ *
+ * Extends pict-docuserve to serve standalone markdown content.
+ * Overrides DocsBaseURL to point at the /content/ static route
+ * so all markdown is fetched from the server's content directory.
+ */
+class ContentReaderApplication extends libDocuserveApplication
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	onAfterInitializeAsync(fCallback)
+	{
+		// Point docuserve at the /content/ path served by Orator
+		this.pict.AppData.Docuserve =
+		{
+			CatalogLoaded: false,
+			Catalog: null,
+			CoverLoaded: false,
+			Cover: null,
+			SidebarLoaded: false,
+			SidebarGroups: [],
+			TopBarLoaded: false,
+			TopBar: null,
+			ErrorPageLoaded: false,
+			ErrorPageHTML: null,
+			KeywordIndexLoaded: false,
+			KeywordDocumentCount: 0,
+			CurrentGroup: '',
+			CurrentModule: '',
+			CurrentPath: '',
+			SidebarVisible: true,
+			// Serve content from the /content/ static route
+			DocsBaseURL: '/content/',
+			// No catalog in standalone mode
+			CatalogURL: '/content/retold-catalog.json'
+		};
+
+		// Load the catalog (will gracefully fall back to standalone mode)
+		let tmpDocProvider = this.pict.providers['Docuserve-Documentation'];
+		tmpDocProvider.loadCatalog(() =>
+		{
+			// Set page title from cover or topbar
+			let tmpDocuserve = this.pict.AppData.Docuserve;
+			if (tmpDocuserve.CoverLoaded && tmpDocuserve.Cover && tmpDocuserve.Cover.Title)
+			{
+				document.title = tmpDocuserve.Cover.Title.replace(/<[^>]*>/g, '');
+			}
+			else if (tmpDocuserve.TopBarLoaded && tmpDocuserve.TopBar && tmpDocuserve.TopBar.Brand)
+			{
+				document.title = tmpDocuserve.TopBar.Brand.replace(/<[^>]*>/g, '');
+			}
+
+			// Inject an "Edit" link into the topbar (shows in ExternalLinks area, top-right)
+			if (tmpDocuserve.TopBar)
+			{
+				if (!Array.isArray(tmpDocuserve.TopBar.ExternalLinks))
+				{
+					tmpDocuserve.TopBar.ExternalLinks = [];
+				}
+				tmpDocuserve.TopBar.ExternalLinks.push({ Text: 'Edit', Href: '/' });
+			}
+			else
+			{
+				tmpDocuserve.TopBarLoaded = true;
+				tmpDocuserve.TopBar =
+				{
+					Brand: 'Content System',
+					NavLinks: [],
+					ExternalLinks: [{ Text: 'Edit', Href: '/' }]
+				};
+			}
+
+			// Render the layout shell
+			this.pict.views['Docuserve-Layout'].render();
+
+			// Call the base PictApplication callback (skip docuserve's onAfterInitializeAsync
+			// since we already did the catalog loading ourselves)
+			return fCallback();
+		});
+	}
+}
+
+module.exports = ContentReaderApplication;
+
+module.exports.default_configuration = require('./Pict-Application-ContentReader-Configuration.json');

package/source/Pict-ContentSystem-Bundle.js

@@ -0,0 +1,21 @@
+/**
+ * Combined browser bundle for Retold Content System.
+ *
+ * Exports both the reader and editor applications as window globals
+ * so each HTML page can bootstrap the appropriate one.
+ *
+ * In index.html: Pict.safeLoadPictApplication(PictContentReader, 2)
+ * In edit.html:  Pict.safeLoadPictApplication(PictContentEditor, 2)
+ */
+module.exports =
+{
+	PictContentReader: require('./Pict-Application-ContentReader.js'),
+	PictContentEditor: require('./Pict-Application-ContentEditor.js')
+};
+
+// Also expose on window for direct access
+if (typeof (window) !== 'undefined')
+{
+	window.PictContentReader = module.exports.PictContentReader;
+	window.PictContentEditor = module.exports.PictContentEditor;
+}

package/source/cli/ContentSystem-CLI-Program.js

@@ -0,0 +1,15 @@
+const libCLIProgram = require('pict-service-commandlineutility');
+
+let _PictCLIProgram = new libCLIProgram(
+	{
+		Product: 'retold-content-system',
+		Version: require('../../package.json').version,
+
+		Command: 'retold-content-system',
+		Description: 'Serve and edit markdown content folders with reader and editor apps powered by Pict.'
+	},
+	[
+		require('./commands/ContentSystem-Command-Serve.js')
+	]);
+
+module.exports = _PictCLIProgram;

package/source/cli/ContentSystem-CLI-Run.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const libContentSystemProgram = require('./ContentSystem-CLI-Program.js');
+libContentSystemProgram.run();

package/source/cli/ContentSystem-Server-Setup.js

@@ -0,0 +1,405 @@
+/**
+ * Retold Content System -- Shared Orator Server Setup
+ *
+ * This module encapsulates all server initialization logic so it can be
+ * used by both the standalone server.js entry point and the CLI serve command.
+ *
+ * @param {object} pOptions
+ * @param {string} pOptions.ContentPath  - Absolute path to the markdown content folder
+ * @param {string} pOptions.UploadPath   - Absolute path to the uploads folder
+ * @param {string} pOptions.DistPath     - Absolute path to the built dist folder
+ * @param {number} pOptions.Port         - HTTP port to listen on
+ * @param {Function} fCallback           - Callback(pError, { Fable, Orator, Port })
+ */
+
+const libFs = require('fs');
+const libPath = require('path');
+
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libFileBrowserService = require('pict-section-filebrowser').FileBrowserService;
+
+/**
+ * Sanitize a file path -- prevent directory traversal attacks.
+ *
+ * @param {string} pPath - The raw path from the client
+ * @returns {string|null} A safe relative path, or null if invalid
+ */
+function sanitizePath(pPath)
+{
+	if (!pPath || typeof (pPath) !== 'string')
+	{
+		return null;
+	}
+
+	// Decode URI components
+	let tmpPath = decodeURIComponent(pPath);
+
+	// Remove leading slashes
+	tmpPath = tmpPath.replace(/^\/+/, '');
+
+	// Block directory traversal
+	if (tmpPath.includes('..'))
+	{
+		return null;
+	}
+
+	// Block absolute paths
+	if (libPath.isAbsolute(tmpPath))
+	{
+		return null;
+	}
+
+	// Remove dangerous characters
+	tmpPath = tmpPath.replace(/[<>"|?*]/g, '_');
+
+	return tmpPath || null;
+}
+
+/**
+ * Sanitize a filename -- strip path separators and dangerous characters.
+ *
+ * @param {string} pName - The raw filename from the client
+ * @returns {string} A safe filename
+ */
+function sanitizeFilename(pName)
+{
+	if (!pName || typeof (pName) !== 'string')
+	{
+		return 'upload';
+	}
+	let tmpName = libPath.basename(pName);
+	tmpName = tmpName.replace(/[\/\\:*?"<>|]/g, '_');
+	if (tmpName.length > 200)
+	{
+		tmpName = tmpName.substring(0, 200);
+	}
+	return tmpName || 'upload';
+}
+
+/**
+ * Set up and start the Retold Content System Orator server.
+ */
+function setupContentSystemServer(pOptions, fCallback)
+{
+	let tmpContentPath = pOptions.ContentPath;
+	let tmpUploadPath = pOptions.UploadPath;
+	let tmpDistFolder = pOptions.DistPath;
+	let tmpPort = pOptions.Port;
+
+	let tmpSettings =
+	{
+		Product: 'Retold-Content-System',
+		ProductVersion: require('../../package.json').version,
+		APIServerPort: tmpPort,
+		ContentPath: tmpContentPath,
+		UploadPath: tmpUploadPath
+	};
+
+	let tmpFable = new libFable(tmpSettings);
+
+	// Ensure the uploads directory exists
+	if (!libFs.existsSync(tmpUploadPath))
+	{
+		libFs.mkdirSync(tmpUploadPath, { recursive: true });
+	}
+
+	// Ensure the content directory exists
+	if (!libFs.existsSync(tmpContentPath))
+	{
+		libFs.mkdirSync(tmpContentPath, { recursive: true });
+	}
+
+	tmpFable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+	tmpFable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+	tmpFable.serviceManager.addServiceType('Orator', libOrator);
+	let tmpOrator = tmpFable.serviceManager.instantiateServiceProvider('Orator');
+
+	// Set up the FileBrowserService for the content directory
+	let tmpFileBrowser = new libFileBrowserService(tmpFable,
+	{
+		BasePath: tmpContentPath,
+		APIRoutePrefix: '/api/filebrowser',
+		ServeWebApp: false,
+		IncludeHiddenFiles: false
+	});
+
+	tmpOrator.initialize(
+		function ()
+		{
+			let tmpServiceServer = tmpOrator.serviceServer;
+
+			// Enable body parsing for POST/PUT requests
+			tmpServiceServer.server.use(tmpServiceServer.bodyParser());
+
+			// Connect the file browser API routes
+			tmpFileBrowser.connectRoutes();
+
+			// --- PUT /api/filebrowser/settings ---
+			// Toggle file browser options at runtime (e.g. hidden files)
+			tmpServiceServer.put('/api/filebrowser/settings',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						if (pRequest.body && typeof (pRequest.body.IncludeHiddenFiles) === 'boolean')
+						{
+							tmpFileBrowser.options.IncludeHiddenFiles = pRequest.body.IncludeHiddenFiles;
+						}
+						pResponse.send({ Success: true });
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Error: pError.message });
+					}
+					return fNext();
+				});
+
+			// --- GET /api/content/read/* ---
+			// Read the raw markdown content of a file
+			tmpServiceServer.get('/api/content/read/*',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpFilePath = sanitizePath(pRequest.params['*']);
+
+						if (!tmpFilePath)
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid file path.' });
+							return fNext();
+						}
+
+						let tmpFullPath = libPath.join(tmpContentPath, tmpFilePath);
+
+						// Ensure the resolved path is within the content directory
+						let tmpRealContent = libFs.realpathSync(tmpContentPath);
+						if (!tmpFullPath.startsWith(tmpRealContent))
+						{
+							pResponse.send(403, { Success: false, Error: 'Access denied.' });
+							return fNext();
+						}
+
+						if (!libFs.existsSync(tmpFullPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						let tmpContent = libFs.readFileSync(tmpFullPath, 'utf8');
+						pResponse.send({ Success: true, Path: tmpFilePath, Content: tmpContent });
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+					}
+					return fNext();
+				});
+
+			// --- PUT /api/content/save/* ---
+			// Save markdown content to a file (create or overwrite)
+			tmpServiceServer.put('/api/content/save/*',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpFilePath = sanitizePath(pRequest.params['*']);
+
+						if (!tmpFilePath)
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid file path.' });
+							return fNext();
+						}
+
+						let tmpFullPath = libPath.join(tmpContentPath, tmpFilePath);
+
+						// Ensure the resolved path target is within the content directory
+						let tmpRealContent = libFs.realpathSync(tmpContentPath);
+						let tmpTargetDir = libPath.dirname(tmpFullPath);
+						// The file may not exist yet, but the directory should be within content
+						if (!tmpTargetDir.startsWith(tmpRealContent))
+						{
+							pResponse.send(403, { Success: false, Error: 'Access denied.' });
+							return fNext();
+						}
+
+						let tmpContent = '';
+						if (pRequest.body && typeof (pRequest.body) === 'object' && pRequest.body.Content !== undefined)
+						{
+							tmpContent = pRequest.body.Content;
+						}
+						else if (typeof (pRequest.body) === 'string')
+						{
+							tmpContent = pRequest.body;
+						}
+
+						// Ensure the target directory exists
+						let tmpDir = libPath.dirname(tmpFullPath);
+						if (!libFs.existsSync(tmpDir))
+						{
+							libFs.mkdirSync(tmpDir, { recursive: true });
+						}
+
+						libFs.writeFileSync(tmpFullPath, tmpContent, 'utf8');
+
+						tmpFable.log.info(`Content saved: ${tmpFilePath} (${tmpContent.length} bytes)`);
+						pResponse.send({ Success: true, Path: tmpFilePath, Size: tmpContent.length });
+					}
+					catch (pError)
+					{
+						tmpFable.log.error(`Content save failed: ${pError.message}`);
+						pResponse.send(500, { Success: false, Error: pError.message });
+					}
+					return fNext();
+				});
+
+			// --- POST /api/content/upload-image ---
+			// Upload an image file into the content folder the user is browsing.
+			// The client sends the target folder via the x-upload-path header.
+			tmpServiceServer.post('/api/content/upload-image',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpBody = pRequest.body;
+
+						if (!tmpBody)
+						{
+							pResponse.send(400, { Success: false, Error: 'No image data received.' });
+							return fNext();
+						}
+
+						let tmpOriginalName = sanitizeFilename(pRequest.headers['x-filename']);
+						let tmpContentType = pRequest.headers['content-type'] || 'application/octet-stream';
+
+						// Determine file extension from content-type if needed
+						let tmpExt = libPath.extname(tmpOriginalName);
+						if (!tmpExt)
+						{
+							let tmpMimeMap =
+							{
+								'image/png': '.png',
+								'image/jpeg': '.jpg',
+								'image/gif': '.gif',
+								'image/webp': '.webp',
+								'image/svg+xml': '.svg',
+								'image/bmp': '.bmp'
+							};
+							tmpExt = tmpMimeMap[tmpContentType] || '.bin';
+							tmpOriginalName += tmpExt;
+						}
+
+						// Determine the target folder: use the x-upload-path header
+						// (the folder the user is currently browsing), falling back
+						// to the content root if none is provided.
+						let tmpUploadFolder = tmpContentPath;
+						let tmpRelativeFolder = '';
+						let tmpRawUploadPath = pRequest.headers['x-upload-path'];
+						if (tmpRawUploadPath)
+						{
+							let tmpSafePath = sanitizePath(tmpRawUploadPath);
+							if (tmpSafePath)
+							{
+								tmpRelativeFolder = tmpSafePath;
+								tmpUploadFolder = libPath.join(tmpContentPath, tmpSafePath);
+
+								// Ensure the resolved path is within the content directory
+								let tmpRealContent = libFs.realpathSync(tmpContentPath);
+								if (!libPath.resolve(tmpUploadFolder).startsWith(tmpRealContent))
+								{
+									pResponse.send(403, { Success: false, Error: 'Access denied.' });
+									return fNext();
+								}
+							}
+						}
+
+						// Ensure the target directory exists
+						if (!libFs.existsSync(tmpUploadFolder))
+						{
+							libFs.mkdirSync(tmpUploadFolder, { recursive: true });
+						}
+
+						let tmpUniqueFilename = `${Date.now()}-${tmpOriginalName}`;
+						let tmpFilePath = libPath.join(tmpUploadFolder, tmpUniqueFilename);
+
+						let tmpBuffer = Buffer.isBuffer(tmpBody) ? tmpBody : Buffer.from(tmpBody);
+						libFs.writeFileSync(tmpFilePath, tmpBuffer);
+
+						// Build the URL: serve through the /content/ static route
+						let tmpRelativePath = tmpRelativeFolder
+							? (tmpRelativeFolder + '/' + tmpUniqueFilename)
+							: tmpUniqueFilename;
+						let tmpURL = `/content/${tmpRelativePath}`;
+						tmpFable.log.info(`Image uploaded: ${tmpURL} (${tmpBuffer.length} bytes)`);
+
+						pResponse.send(
+						{
+							Success: true,
+							URL: tmpURL,
+							RelativePath: tmpRelativePath,
+							Filename: tmpUniqueFilename,
+							Size: tmpBuffer.length
+						});
+					}
+					catch (pError)
+					{
+						tmpFable.log.error(`Image upload failed: ${pError.message}`);
+						pResponse.send(500, { Success: false, Error: pError.message });
+					}
+					return fNext();
+				});
+
+			// --- GET /api/content/uploads ---
+			// List uploaded images
+			tmpServiceServer.get('/api/content/uploads',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpFiles = libFs.readdirSync(tmpUploadPath);
+						let tmpFileList = tmpFiles.map(
+							(pFilename) =>
+							{
+								let tmpStat = libFs.statSync(libPath.join(tmpUploadPath, pFilename));
+								return (
+								{
+									Filename: pFilename,
+									URL: `/uploads/${pFilename}`,
+									Size: tmpStat.size,
+									Modified: tmpStat.mtime
+								});
+							});
+						pResponse.send({ Success: true, Files: tmpFileList });
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+					}
+					return fNext();
+				});
+
+			// Serve uploaded images at /uploads/
+			tmpOrator.addStaticRoute(`${tmpUploadPath}/`, 'index.html', '/uploads/*', '/uploads/');
+
+			// Serve content markdown files at /content/ (for the reader)
+			tmpOrator.addStaticRoute(`${tmpContentPath}/`, 'index.html', '/content/*', '/content/');
+
+			// Serve the built application from dist/ (main static route)
+			tmpOrator.addStaticRoute(`${tmpDistFolder}/`, 'index.html');
+
+			// Start the server
+			tmpOrator.startService(
+				function ()
+				{
+					return fCallback(null,
+					{
+						Fable: tmpFable,
+						Orator: tmpOrator,
+						Port: tmpPort
+					});
+				});
+		});
+}
+
+module.exports = setupContentSystemServer;

package/source/cli/commands/ContentSystem-Command-Serve.js

@@ -0,0 +1,104 @@
+const libCommandLineCommand = require('pict-service-commandlineutility').ServiceCommandLineCommand;
+
+const libFs = require('fs');
+const libPath = require('path');
+
+class ContentSystemCommandServe extends libCommandLineCommand
+{
+	constructor(pFable, pManifest, pServiceHash)
+	{
+		super(pFable, pManifest, pServiceHash);
+
+		this.options.CommandKeyword = 'serve';
+		this.options.Description = 'Start the content system server for a content folder.';
+
+		this.options.CommandArguments.push(
+			{ Name: '[content-path]', Description: 'Path to the markdown content folder (defaults to current directory).' });
+
+		this.options.CommandOptions.push(
+			{ Name: '-p, --port [port]', Description: 'Port to serve on (defaults to random 7000-7999).', Default: '0' });
+
+		this.addCommand();
+	}
+
+	onRunAsync(fCallback)
+	{
+		let tmpContentPath = libPath.resolve(this.ArgumentString || process.cwd());
+
+		// If no explicit content-path was given and the resolved directory has a
+		// content/ subfolder, use that instead.  This way running the CLI from
+		// a project root that has a content/ folder does the right thing.
+		if (!this.ArgumentString)
+		{
+			let tmpContentSubfolder = libPath.join(tmpContentPath, 'content');
+			if (libFs.existsSync(tmpContentSubfolder) && libFs.statSync(tmpContentSubfolder).isDirectory())
+			{
+				tmpContentPath = tmpContentSubfolder;
+			}
+		}
+
+		let tmpDistPath = libPath.resolve(__dirname, '..', '..', '..', 'dist');
+		let tmpUploadPath = libPath.join(tmpContentPath, 'uploads');
+		let tmpPortOption = parseInt(this.CommandOptions.port, 10);
+		let tmpPort = (tmpPortOption > 0) ? tmpPortOption : (7000 + Math.floor(Math.random() * 1000));
+
+		// Validate dist path (packaged with the module)
+		if (!libFs.existsSync(tmpDistPath))
+		{
+			this.log.error(`Built assets not found at ${tmpDistPath}. Run 'npm run build-all' in the retold-content-system package first.`);
+			return fCallback(new Error('dist folder not found'));
+		}
+
+		// Ensure content directory exists
+		if (!libFs.existsSync(tmpContentPath))
+		{
+			libFs.mkdirSync(tmpContentPath, { recursive: true });
+			this.log.info(`Created content directory: ${tmpContentPath}`);
+		}
+
+		// Ensure uploads directory exists
+		if (!libFs.existsSync(tmpUploadPath))
+		{
+			libFs.mkdirSync(tmpUploadPath, { recursive: true });
+		}
+
+		let tmpSelf = this;
+		let tmpSetupServer = require('../ContentSystem-Server-Setup.js');
+
+		tmpSetupServer(
+			{
+				ContentPath: tmpContentPath,
+				UploadPath: tmpUploadPath,
+				DistPath: tmpDistPath,
+				Port: tmpPort
+			},
+			function (pError, pServerInfo)
+			{
+				if (pError)
+				{
+					tmpSelf.log.error(`Failed to start server: ${pError.message}`);
+					return fCallback(pError);
+				}
+
+				tmpSelf.log.info('');
+				tmpSelf.log.info('==========================================================');
+				tmpSelf.log.info(`  Retold Content System running on http://localhost:${pServerInfo.Port}`);
+				tmpSelf.log.info('==========================================================');
+				tmpSelf.log.info(`  Content: ${tmpContentPath}`);
+				tmpSelf.log.info(`  Uploads: ${tmpUploadPath}`);
+				tmpSelf.log.info(`  Assets:  ${tmpDistPath}`);
+				tmpSelf.log.info(`  Reader:  http://localhost:${pServerInfo.Port}/`);
+				tmpSelf.log.info(`  Editor:  http://localhost:${pServerInfo.Port}/edit.html`);
+				tmpSelf.log.info('==========================================================');
+				tmpSelf.log.info('');
+				tmpSelf.log.info('  Press Ctrl+C to stop.');
+				tmpSelf.log.info('');
+
+				// Intentionally do NOT call fCallback() here.
+				// The server should keep running -- the Orator listener
+				// keeps the event loop alive.
+			});
+	}
+}
+
+module.exports = ContentSystemCommandServe;