domma-cms 0.55.1 → 0.69.3

package/server/services/siteGitignore.js

@@ -0,0 +1,307 @@
+/**
+ * Site .gitignore - the content-only allowlist
+ *
+ * A site repo holds the site's CONTENT and nothing else: pages, media, blocks,
+ * views, forms, components, collections the site built, API endpoints, menus,
+ * theme and every other config/ file, plus plugins the site wrote itself. The
+ * engine - server/, admin/, public/, scripts/, node_modules/ (which carries
+ * domma-js and domma-reactive) - and every distributed plugin arrive through
+ * the updater, so they are never committed.
+ *
+ * The file is an ALLOWLIST: ignore everything at the root, then re-include what
+ * the site owns. A denylist would have to know every engine path in advance and
+ * would start tracking whatever a new release adds; an allowlist can only fail
+ * by leaving something out, and the two places a site grows new owned code
+ * append their own rule through `allowInGitignore()`:
+ *   - pluginScaffold.js: a plugin created in the admin is the site's code
+ *   - pluginInstaller.js: a distributed plugin that stores what users author
+ *     inside its own folder declares it in plugin.json `contentPaths`
+ *
+ * ONE COPY, TWO REPOS. domma-cms-manager keeps a byte-identical copy at
+ * plugins/site-manager/services/siteGitignore.js (its production install runs
+ * an npm domma-cms that may predate this file), and a test there fails when the
+ * two drift. Change this one, then copy it across.
+ *
+ * No imports beyond node built-ins: bin/cli.js loads this before a site exists.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MANAGED_HEADER = '# ── Managed by Domma: content-only allowlist (server/services/siteGitignore.js) ──';
+export const SITE_RULES_MARKER = '# ── Site-specific rules (kept when this file is regenerated) ──';
+
+/** Top-level entries that belong to the engine or the host, never to the site. */
+export const ENGINE_TOP_LEVEL = new Set([
+    'server', 'admin', 'public', 'scripts', 'node_modules', 'bin',
+    'package.json', 'package-lock.json', '.cmsVersion', '.domma', 'CLAUDE.md',
+    'logs', 'backups', '_backups', '.domma-backups', '.env', '.env.example', '.claude', '.git'
+]);
+
+/** Always-kept roots. public/ is handled separately: only site-added entries in it are kept. */
+const SITE_ROOTS = ['content', 'config', 'plugins'];
+
+/**
+ * Plugins that were promoted into core (0.67.0) or retired. A site that has not
+ * yet booted a release that removes them still has the folder; it is engine,
+ * not the site's.
+ */
+export const RETIRED_PLUGINS = [
+    'analytics', 'contacts', 'notes', 'todo', 'demo-viewer', 'theme-switcher', 'site-search'
+];
+
+/**
+ * Distributed plugins that keep what users AUTHOR inside their own folder, for
+ * installs whose plugin.json predates `contentPaths`. Both ship the folder
+ * empty, so everything in it was written by the site.
+ */
+export const KNOWN_PLUGIN_CONTENT = {
+    'docs': ['data'],                  // documents, folders, templates, versions
+    'theme-roller': ['data/themes']    // themes built in the roller
+};
+
+/**
+ * Collections whose schema.json the CMS rewrites on every boot
+ * (presetCollections.seedAll, roles.seed, userProfiles). Tracking them records
+ * the engine's schema, not the site's, and shows a diff after every update.
+ * Their data.json is a separate question - see PRIVATE_DATA.
+ */
+export const ENGINE_SCHEMAS = [
+    'notifications', 'projects', 'api-tokens', 'api-endpoints', 'notes-notes', 'todo-items',
+    'contacts-contacts', 'contacts-groups', 'roles', 'user-profiles'
+];
+
+/**
+ * Collection entries that are secrets, visitor-submitted or per-user private
+ * data, or runtime state - not something the site's authors built. Everything
+ * else in content/collections is tracked, including every collection a site
+ * creates, projects and api-endpoints.
+ */
+export const PRIVATE_DATA = [
+    'notifications', 'api-tokens', 'notes-notes', 'todo-items',
+    'contacts-contacts', 'contacts-groups', 'roles', 'user-profiles',
+    'user-messages', 'user-message-threads', 'analytics-events', 'enquiries',
+    'blog-comments', 'invoices', 'invoice-receivers', 'invoice-issuers',
+    'surveys-contacts', 'surveys-invites'
+];
+
+/**
+ * Lines bin/update.js appends when it cannot find them VERBATIM. They are
+ * already ignored by `/*` and `/plugins/*`, but writing them out keeps the
+ * updater from editing the file on every site after every release.
+ */
+const UPDATER_REQUIRED = ['.domma-backups/', 'plugins/analytics/data/'];
+
+/**
+ * Split a plugin folder listing into distributed and site-owned.
+ *
+ * @param {string[]} sitePlugins - Directory names under the site's plugins/
+ * @param {Iterable<string>} distributed - Every plugin name an upstream ships
+ * @returns {{distributed: string[], siteOwned: string[]}}
+ */
+export function classifyPlugins(sitePlugins, distributed) {
+    const known = new Set([...distributed, ...RETIRED_PLUGINS]);
+    const out = {distributed: [], siteOwned: []};
+    for (const name of [...sitePlugins].sort()) {
+        if (name.startsWith('.')) continue;
+        (known.has(name) ? out.distributed : out.siteOwned).push(name);
+    }
+    return out;
+}
+
+/**
+ * Rules that re-include a site-owned plugin.
+ *
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function sitePluginRules(name) {
+    return [`!/plugins/${name}/`];
+}
+
+/**
+ * Rules that re-include ONE content folder inside an otherwise ignored
+ * distributed plugin. Git cannot re-include a file whose parent is excluded,
+ * so every level is opened and its siblings closed again:
+ * data/themes -> !plugins/x/, plugins/x/*, !plugins/x/data/, plugins/x/data/*, !plugins/x/data/themes/
+ *
+ * @param {string} name - Plugin folder name
+ * @param {string} rel - Folder inside the plugin, e.g. 'data' or 'data/themes'
+ * @returns {string[]}
+ */
+export function pluginContentRules(name, rel) {
+    const parts = rel.split('/').filter(p => p && p !== '.' && p !== '..');
+    if (!parts.length) return [];
+    const out = [`!/plugins/${name}/`, `/plugins/${name}/*`];
+    for (let i = 1; i <= parts.length; i++) {
+        const sub = parts.slice(0, i).join('/');
+        out.push(`!/plugins/${name}/${sub}/`);
+        if (i < parts.length) out.push(`/plugins/${name}/${sub}/*`);
+    }
+    return out;
+}
+
+/**
+ * Build the .gitignore text.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.sitePlugins=[]] - Site-owned plugin folder names
+ * @param {Object<string,string[]>} [opts.pluginContent={}] - Extra content folders in distributed plugins
+ * @param {string[]} [opts.sitePublic=[]] - Site-added entries directly under public/
+ * @param {string[]} [opts.extras=[]] - Other site-owned top-level entries (docs, tools, README.md)
+ * @param {string[]} [opts.siteRules=[]] - The site-specific section
+ * @returns {string}
+ */
+export function buildGitignore({sitePlugins = [], pluginContent = {}, sitePublic = [], extras = [], siteRules = []} = {}) {
+    const L = [
+        MANAGED_HEADER,
+        '# This repo holds the site\'s CONTENT only. Everything is ignored, then what',
+        '# the site owns is re-included. The engine (server/, admin/, public/, scripts/,',
+        '# node_modules/ incl. domma-js + domma-reactive) and distributed plugins come',
+        '# from the updater and are never committed. A plugin created in the admin adds',
+        '# its own rule to the site section below.',
+        '/*',
+        '!/.gitignore'
+    ];
+    for (const root of SITE_ROOTS) L.push(`!/${root}/`);
+    for (const x of [...extras].sort()) L.push(`!/${x}${x.includes('.') ? '' : '/'}`);
+
+    L.push('', '# Plugins: only the ones this site wrote itself', '/plugins/*');
+    for (const p of [...sitePlugins].sort()) L.push(...sitePluginRules(p));
+
+    const content = {};
+    for (const [name, rels] of [...Object.entries(KNOWN_PLUGIN_CONTENT), ...Object.entries(pluginContent)]) {
+        if (sitePlugins.includes(name)) continue;           // already tracked whole
+        content[name] = [...new Set([...(content[name] || []), ...rels])];
+    }
+    L.push('', '# ...and what users author inside a distributed plugin (its code stays out)');
+    for (const name of Object.keys(content).sort()) {
+        const seen = new Set();
+        for (const rel of content[name].sort()) {
+            for (const r of pluginContentRules(name, rel)) if (!seen.has(r)) { seen.add(r); L.push(r); }
+        }
+    }
+
+    if (sitePublic.length) {
+        L.push('', '# public/ is engine except what the site added to it', '!/public/', '/public/*');
+        for (const p of [...sitePublic].sort()) L.push(`!/public/${p}`);
+    }
+
+    L.push('', '# Schemas the CMS rewrites on every boot - engine-owned, not authored');
+    for (const c of ENGINE_SCHEMAS) L.push(`/content/collections/${c}/schema.json`);
+    L.push('', '# Secrets, visitor-submitted and per-user data, runtime state');
+    for (const c of PRIVATE_DATA) L.push(`/content/collections/${c}/data.json`);
+    L.push(
+        '/content/users/',
+        '/content/versions/',
+        '/content/analytics/',
+        '/content/instances_log.json',
+        '/content/preview-links.json',
+        '/config/connections.json*',
+        '/config/keys/',
+        '/plugins/*/data/*.jsonl',
+        '/plugins/*/backups/',
+        ...UPDATER_REQUIRED,
+        '',
+        '# Cruft',
+        '*.log', '*.pid', '*.bak', '*.bak-*', '*.orig', '*.swp', '*.prev-*/', '.DS_Store',
+        '',
+        SITE_RULES_MARKER,
+        ...siteRules
+    );
+    return L.join('\n') + '\n';
+}
+
+/** Every non-comment rule above the site section, for de-duplicating carried rules. */
+export function generatedRules(text) {
+    const end = text.indexOf(SITE_RULES_MARKER);
+    return (end === -1 ? text : text.slice(0, end)).split('\n').map(l => l.trim())
+        .filter(l => l && !l.startsWith('#'));
+}
+
+/**
+ * Old rules that would hide a whole content root. The first scaffolded
+ * .gitignore ignored content/media/, and media is content - carrying that rule
+ * would keep every uploaded image out of the repo that exists to hold them.
+ */
+const NEVER_CARRY = /^(content|config|content\/(media|pages|blocks|components|forms|views|collections))\/?\*?$/;
+
+function norm(rule) {
+    return rule.replace(/^\//, '').replace(/\/$/, '');
+}
+
+/**
+ * Pull the site-specific section out of an existing .gitignore.
+ *
+ * A file this module wrote keeps everything after the marker verbatim. A
+ * hand-written file has no marker, so only the rules that still narrow
+ * something kept (content/, config/, a kept plugin or public entry) are
+ * carried; engine paths are covered by the allowlist and dropped.
+ *
+ * @param {string} existing - Current .gitignore text ('' if none)
+ * @param {{keptPlugins: string[], keptPublic: string[]}} kept
+ * @param {string[]} generated - Rules the new file already has
+ * @returns {string[]}
+ */
+export function carrySiteRules(existing, {keptPlugins, keptPublic}, generated) {
+    if (!existing) return [];
+    const idx = existing.indexOf(SITE_RULES_MARKER);
+    if (idx !== -1) {
+        return existing.slice(idx + SITE_RULES_MARKER.length).replace(/^\n+/, '').replace(/\n+$/, '').split('\n')
+            .filter(l => l.length);
+    }
+    const have = new Set(generated.map(norm));
+    // A generated `foo*` already covers every carried rule that starts with foo.
+    const globs = generated.filter(r => r.endsWith('*') && !r.startsWith('!')).map(r => norm(r).slice(0, -1))
+        .filter(g => g.includes('/') && !g.endsWith('/') && !g.includes('*'));
+    const keptPrefixes = [
+        'content/', 'config/',
+        ...keptPlugins.map(p => `plugins/${p}/`),
+        ...keptPublic.map(p => `public/${p}`)
+    ];
+    const carried = [];
+    for (const raw of existing.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) continue;
+        const bare = line.replace(/^!?\//, '').replace(/^!/, '');
+        if (!keptPrefixes.some(p => bare.startsWith(p))) continue;
+        if (NEVER_CARRY.test(bare)) continue;
+        if (have.has(norm(line)) || globs.some(g => norm(line).startsWith(g))) continue;
+        carried.push(line);
+    }
+    return carried;
+}
+
+/**
+ * Add rules to the site section of a managed .gitignore, skipping any already
+ * present. A missing or hand-written file is left alone: the site chose its own
+ * rules and this must not rewrite them.
+ *
+ * @param {string} siteRoot - Directory holding .gitignore
+ * @param {string[]} rules
+ * @returns {string[]} The rules actually added
+ */
+export function allowInGitignore(siteRoot, rules) {
+    const file = path.join(siteRoot, '.gitignore');
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+    if (!text.startsWith(MANAGED_HEADER) || !text.includes(SITE_RULES_MARKER)) return [];
+    const present = new Set(text.split('\n').map(l => l.trim()));
+    const added = rules.filter(r => !present.has(r));
+    if (added.length) fs.writeFileSync(file, text.replace(/\n*$/, '\n') + added.join('\n') + '\n');
+    return added;
+}
+
+/**
+ * The content folders a plugin manifest declares, sanitised. `contentPaths`
+ * is a list of folders relative to the plugin root; anything that could climb
+ * out of it is dropped.
+ *
+ * @param {object} manifest - Parsed plugin.json
+ * @returns {string[]}
+ */
+export function manifestContentPaths(manifest) {
+    const raw = Array.isArray(manifest?.contentPaths) ? manifest.contentPaths : [];
+    return raw.filter(p => typeof p === 'string')
+        .map(p => p.replace(/^\.?\/+/, '').replace(/\/+$/, ''))
+        .filter(p => p && !p.split('/').some(s => s === '..' || s === '.' || s === ''));
+}