wiki-plugin-farmmanager 0.1.0

package/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <YEAR> <COPYRIGHT HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# Federated Wiki - FarmManager Plugin
+
+Plugin for managing a wiki instance as a farm of multiple wiki sites.
+
+The focus of this plugin is to allow for programmatic, centralized management of a wiki farm by a farm administrator. It is intended to supersede `wiki-plugin-register` by providing administrative oversight rather than self-service registration.
+
+## Design Philosophy
+
+- **Admin-Focused**: All features are designed to be used by a farm administrator. Access will be restricted to admin users.
+- **JSON API**: The server-side component will expose a well-defined API for managing sites. This ensures the API is predictable and can be used by other tools, not just our web interface.
+- **Clear Separation**: The backend (API) and frontend (web interface) will be clearly separated. The web interface will be a client of the API.
+- **Safety**: Destructive operations (like deleting a site) are non-destructive by default and require confirmation.
+
+## API Design
+
+Authentication for all endpoints will be handled by a middleware that checks `app.securityhandler.isAdmin(req)`.
+
+### Endpoints
+
+- **`GET /plugin/farmmanager/sites`**
+  - **Action**: List all wiki sites in the farm.
+  - **Response Body**: An array of site objects.
+  - `[{ "name": "site1.myfarm.com", "owner": "Alice", "pages": 12, "status": "active" }, ...]`
+
+- **`POST /plugin/farmmanager/sites`**
+  - **Action**: Create a new wiki site.
+  - **Request Body**: `{ "domain": "newsite", "owner": "Bob" }`
+  - **Response Body**: The new site object.
+
+- **`GET /plugin/farmmanager/sites/:domain`**
+  - **Action**: Get detailed information for a single site.
+  - **URL Parameter**: `:domain` is the full domain of the site (e.g., `site1.myfarm.com`).
+  - **Response Body**: A single site object.
+
+- **`PATCH /plugin/farmmanager/sites/:domain`**
+  - **Action**: Partially update a site's properties (preserves unspecified fields).
+  - **Request Body**: `{ "owner": {"name": "Carol", ...} }` or `{ "status": "active" }` or both
+  - **Response Body**: The updated site object.
+
+- **`DELETE /plugin/farmmanager/sites/:domain`**
+  - **Action**: Deactivate a wiki site (soft delete). Adds a `status.json` file marking the site as inactive.
+  - **Query Parameters**: 
+    - `hard=true` - Permanently delete the site directory and all its contents (irreversible).
+  - **Response Body**: `{ "status": "ok", "message": "Site site1.myfarm.com deactivated." }`
+
+## Web Interface Design
+
+The web interface will be developed after the backend API is complete. It will follow the established FedWiki pattern of providing a client-side component that can be embedded and used within a wiki page.
+
+## Development Plan
+
+We can build this in phases.
+
+- **Phase 1: Backend API**
+  1.  **Setup**: Create the basic `server/server.js` file and `admin` security middleware.
+  2.  **List Sites (Read)**: Implement the `GET /sites` endpoint. This will involve scanning the data directory for site folders and reading their `owner.json` and `status.json`.
+  3.  **Create Site**: Implement the `POST /sites` endpoint. This can borrow logic from `wiki-plugin-register` but will be wrapped in admin security.
+  4.  **Deactivate Site**: Implement the `DELETE /sites/:domain` endpoint. This will involve creating or updating a `status.json` file in the site's directory.
+  5.  **Update Site**: Implement the `PUT /sites/:domain` endpoint to change the `owner.json`.
+
+- **Phase 2: Frontend UI**
+  - TBD after the backend API is stable.
+
+## Roadmap
+
+- **Search/Filter**: Add a search or filter feature to the UI for farms with many sites.
+- **UI Pattern Documentation**: Create documentation for the pattern of building plugins that render as components within a wiki page.
+
+## Architecture Notes
+
+### Site-Level Plugin with Farm-Level Scope
+
+This plugin follows the standard FedWiki plugin architecture, which means it is loaded **per-site** when you navigate to a specific site in the farm. However, its purpose is to manage **farm-level** resources (all sites in the farm).
+
+**What this means in practice:**
+
+1. **Access Pattern**: You must first navigate to a specific site (e.g., `http://localhost`) to load the plugin. Once loaded, the API endpoints are available and can manage all sites in the farm.
+
+2. **Admin Site Approach**: In practice, designate one site as your "admin site" (e.g., `localhost` or `admin.example.com`) and always access the farm management API through that site.
+
+3. **Data Directory Resolution**: The plugin receives `argv.data` pointing to the current site's directory (e.g., `/data-farm/localhost`). It uses `path.resolve(argv.data, '..')` to access the parent farm directory and enumerate all sites.
+
+4. **Security Context**: Admin authentication and authorization are tied to the site you're accessing the API from, which aligns with FedWiki's per-site security model.
+
+This is consistent with how other farm-management plugins (like `wiki-plugin-register`) operate in the FedWiki ecosystem.
+
+## Build
+
+`npm install`
+`npm run build`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "wiki-plugin-farmmanager",
+  "version": "0.1.0",
+  "description": "Federated Wiki - Farm Manager Plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://git.coopcloud.tech/wiki-cafe/wiki-plugin-farmmanager.git"
+  },
+  "keywords": [
+    "wiki",
+    "federated wiki",
+    "plugin",
+    "farm",
+    "manager",
+    "admin",
+    "fedwiki"
+  ],
+  "scripts": {
+    "prettier:format": "prettier --write './**/*.js'",
+    "prettier:check": "prettier --check ./**/*.js"
+  },
+  "author": {
+    "name": "Christian Galo",
+    "email": "christian.galo@wiki.cafe",
+    "url": "http://galo.wiki.cafe"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.x"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "esbuild": "^0.25.5",
+    "eslint": "^9.28.0",
+    "globals": "^16.2.0",
+    "prettier": "^3.5.3"
+  }
+}

package/pages/about-farmmanager-plugin

@@ -0,0 +1,20 @@
+{
+  "title": "About FarmManager Plugin",
+  "story": [
+    { "type": "paragraph", "id": "9c1d7c35ad98ba82", "text": "Describe the plugin here." },
+    { "type": "farmmanager", "id": "c5ab6c3b5cadc5f9", "text": "SAMPLE Markup" }
+  ],
+  "journal": [
+    {
+      "type": "create",
+      "item": {
+        "title": "About FarmManager Plugin",
+        "story": [
+          { "type": "paragraph", "id": "9c1d7c35ad98ba82", "text": "Describe the plugin here." },
+          { "type": "farmmanager", "id": "c5ab6c3b5cadc5f9" , "text":"SAMPLE Markup" }
+        ]
+      },
+      "date": 1749415263346
+    }
+  ]
+}

package/server/server.js

@@ -0,0 +1,292 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+// Helper function to read owner information from a site directory
+const readSiteOwner = async function (siteDir) {
+  try {
+    const ownerPath = path.join(siteDir, 'status', 'owner.json')
+    const ownerData = await fsp.readFile(ownerPath, 'utf8')
+    const owner = JSON.parse(ownerData)
+    return owner.name || 'Unknown'
+  } catch (err) {
+    return 'Unknown'
+  }
+}
+
+// Helper function to read site status
+const readSiteStatus = async function (siteDir) {
+  try {
+    const statusPath = path.join(siteDir, 'status.json')
+    const statusData = await fsp.readFile(statusPath, 'utf8')
+    const status = JSON.parse(statusData)
+    return status.status || 'active'
+  } catch (err) {
+    // If no status.json exists, assume the site is active
+    return 'active'
+  }
+}
+
+// Helper function to count pages in a site
+const countSitePages = async function (siteDir) {
+  try {
+    const pagesDir = path.join(siteDir, 'pages')
+    const files = await fsp.readdir(pagesDir)
+    return files.length
+  } catch (err) {
+    return 0
+  }
+}
+
+// Helper function to get site information
+const getSiteInfo = async function (siteName, dataDir) {
+  const siteDir = path.join(dataDir, siteName)
+
+  try {
+    const stats = await fsp.stat(siteDir)
+    if (!stats.isDirectory()) {
+      return null
+    }
+
+    // Check if this is actually a site by looking for status directory
+    try {
+      const statusStat = await fsp.stat(path.join(siteDir, 'status'))
+      if (!statusStat.isDirectory()) {
+        return null
+      }
+    } catch (err) {
+      // Missing status directory means this isn't a valid site
+      return null
+    }
+
+    const [owner, status, pageCount] = await Promise.all([
+      readSiteOwner(siteDir),
+      readSiteStatus(siteDir),
+      countSitePages(siteDir),
+    ])
+
+    return {
+      name: siteName,
+      owner: owner,
+      pages: pageCount,
+      status: status,
+    }
+  } catch (err) {
+    return null
+  }
+}
+
+// Main plugin export
+const startServer = async function (params) {
+  const { app, argv } = params
+
+  // Calculate data directory once
+  // In farm mode, argv.data points to the current site's directory
+  // We need to go up one level to get to the farm root
+  const dataDir = path.resolve(argv.data || './data', '..')
+
+  // Middleware to ensure only admin users can access these endpoints
+  const admin = function (req, res, next) {
+    if (req.app.securityhandler && req.app.securityhandler.isAdmin(req)) {
+      next()
+    } else {
+      res.status(403).json({ error: 'Admin access required' })
+    }
+  }
+
+  // Middleware to ensure server is running in farm mode
+  const farm = function (req, res, next) {
+    if (argv.farm) {
+      next()
+    } else {
+      res.status(400).json({ error: 'Server must be running in farm mode' })
+    }
+  }
+
+  // GET /plugin/farmmanager/sites - List all sites
+  app.get('/plugin/farmmanager/sites', farm, admin, async function (req, res) {
+    try {
+      const entries = await fsp.readdir(dataDir)
+
+      const sitePromises = entries.map(async entry => {
+        return await getSiteInfo(entry, dataDir)
+      })
+
+      const sites = await Promise.all(sitePromises)
+      const validSites = sites.filter(site => site !== null)
+
+      res.json(validSites)
+    } catch (err) {
+      console.error('Error listing sites:', err)
+      res.status(500).json({ error: 'Failed to list sites' })
+    }
+  })
+
+  // GET /plugin/farmmanager/sites/:domain - Get single site info
+  app.get('/plugin/farmmanager/sites/:domain', farm, admin, async function (req, res) {
+    try {
+      const domain = req.params.domain
+
+      const siteInfo = await getSiteInfo(domain, dataDir)
+
+      if (!siteInfo) {
+        return res.status(404).json({ error: 'Site not found' })
+      }
+
+      res.json(siteInfo)
+    } catch (err) {
+      console.error('Error getting site info:', err)
+      res.status(500).json({ error: 'Failed to get site information' })
+    }
+  })
+
+  // POST /plugin/farmmanager/sites - Create a new site
+  app.post('/plugin/farmmanager/sites', farm, admin, async function (req, res) {
+    try {
+      const { domain, owner } = req.body
+
+      if (!domain || !owner) {
+        return res.status(400).json({ error: 'Domain and owner are required' })
+      }
+
+      const siteDir = path.join(dataDir, domain)
+
+      // Check if site already exists
+      try {
+        await fsp.stat(siteDir)
+        return res.status(409).json({ error: 'Site already exists' })
+      } catch (err) {
+        // Site doesn't exist, which is what we want
+      }
+
+      // Create site directory structure (minimal - let wiki-server create others on-demand)
+      await fsp.mkdir(siteDir, { recursive: true })
+      await fsp.mkdir(path.join(siteDir, 'status'), { recursive: true })
+
+      // Create owner.json
+      const ownerData = req.body.owner
+      await fsp.writeFile(path.join(siteDir, 'status', 'owner.json'), JSON.stringify(ownerData, null, 2))
+
+      // Get the new site info and return it
+      const siteInfo = await getSiteInfo(domain, dataDir)
+      res.status(201).json(siteInfo)
+    } catch (err) {
+      console.error('Error creating site:', err)
+      res.status(500).json({ error: 'Failed to create site' })
+    }
+  })
+
+  // PATCH /plugin/farmmanager/sites/:domain - Partial update of site properties
+  app.patch('/plugin/farmmanager/sites/:domain', farm, admin, async function (req, res) {
+    try {
+      const domain = req.params.domain
+      const { owner, status } = req.body
+
+      if (!owner && !status) {
+        return res.status(400).json({ error: 'At least one field (owner or status) must be specified' })
+      }
+
+      const siteDir = path.join(dataDir, domain)
+      const ownerPath = path.join(siteDir, 'status', 'owner.json')
+      const statusPath = path.join(siteDir, 'status.json')
+
+      // Check if site exists
+      try {
+        await fsp.stat(siteDir)
+      } catch (err) {
+        return res.status(404).json({ error: 'Site not found' })
+      }
+
+      // Update owner if specified (preserve existing data)
+      if (owner && typeof owner.name === 'string') {
+        let ownerData
+        try {
+          const existingData = await fsp.readFile(ownerPath, 'utf8')
+          ownerData = JSON.parse(existingData)
+        } catch (err) {
+          ownerData = {} // Start with an empty object if file doesn't exist
+        }
+
+        ownerData.name = owner.name
+        await fsp.writeFile(ownerPath, JSON.stringify(ownerData, null, 2))
+      }
+
+      // Update status if specified
+      if (status) {
+        if (status !== 'active' && status !== 'inactive') {
+          return res.status(400).json({ error: 'Status must be either "active" or "inactive"' })
+        }
+
+        let statusData = {}
+        try {
+          const existingData = await fsp.readFile(statusPath, 'utf8')
+          statusData = JSON.parse(existingData)
+        } catch (err) {
+          // No existing status file, which is fine
+        }
+
+        statusData.status = status
+        if (status === 'inactive') {
+          statusData.deactivatedAt = new Date().toISOString()
+        } else {
+          // If re-activating, remove the deactivation timestamp
+          delete statusData.deactivatedAt
+        }
+
+        await fsp.writeFile(statusPath, JSON.stringify(statusData, null, 2))
+      }
+
+      // Return updated site info
+      const siteInfo = await getSiteInfo(domain, dataDir)
+      res.json(siteInfo)
+    } catch (err) {
+      console.error('Error updating site properties:', err)
+      res.status(500).json({ error: 'Failed to update site properties' })
+    }
+  })
+
+  // DELETE /plugin/farmmanager/sites/:domain - Deactivate or permanently delete site
+  app.delete('/plugin/farmmanager/sites/:domain', farm, admin, async function (req, res) {
+    try {
+      const domain = req.params.domain
+      const hardDelete = req.query.hard === 'true'
+      const siteDir = path.join(dataDir, domain)
+
+      // Check if site exists
+      try {
+        await fsp.stat(siteDir)
+      } catch (err) {
+        return res.status(404).json({ error: 'Site not found' })
+      }
+
+      if (hardDelete) {
+        // Hard delete - permanently remove the entire site directory
+        await fsp.rm(siteDir, { recursive: true, force: true })
+
+        res.json({
+          status: 'ok',
+          message: `Site ${domain} permanently deleted.`,
+        })
+      } else {
+        // Soft delete - set status to inactive and add timestamp
+        const statusPath = path.join(siteDir, 'status.json')
+        const statusData = {
+          status: 'inactive',
+          deactivatedAt: new Date().toISOString(),
+        }
+        await fsp.writeFile(statusPath, JSON.stringify(statusData, null, 2))
+
+        res.json({
+          status: 'ok',
+          message: `Site ${domain} deactivated.`,
+        })
+      }
+    } catch (err) {
+      console.error('Error deleting site:', err)
+      res.status(500).json({ error: 'Failed to delete site' })
+    }
+  })
+
+  console.log('FarmManager plugin server started')
+}
+
+export { startServer }