seeemess 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm publish --provenance --access public

package/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SeeEmEss is a CMS framework for Eleventy-based sites. It provides an admin interface for managing blog content with git-based publishing, image upload with automatic resizing, and Eleventy filters.
+
+## Commands
+
+```bash
+npm test          # No tests yet (placeholder)
+npm run admin     # Start admin server (configured in consuming project)
+```
+
+Node 20+ required (see .nvmrc).
+
+## Architecture
+
+### Entry Point (index.js)
+Exports: `startAdminServer(options)`, `createConfig(options)`, `filters`, and config getters.
+
+### Admin Server (admin/)
+- **server.js**: Express app with routes for posts, images, publishing, preview, synopsis
+- **config.js**: Singleton configuration pattern - `createConfig()` sets config, getters retrieve it
+- **routes/**: API endpoints
+  - `posts.js`: CRUD for markdown posts, lede flagging, recursive directory scanning
+  - `images.js`: Base64 upload, sharp-based resizing (generates 4 sizes: thumb/400/600/800px)
+  - `publish.js`: Git workflow - creates branch, commits, merges to main with --no-ff, pushes
+  - `preview.js`: Markdown→HTML rendering with custom template support
+  - `synopsis.js`: Optional Ollama integration for AI summaries
+- **utils/**:
+  - `git.js`: Git command helpers
+  - `markdown.js`: Custom YAML-like frontmatter parser (not full YAML)
+- **templates/**: Eta templates for admin UI and preview
+
+### Eleventy Integration (_config/filters.js)
+11 filters: `readableDate`, `htmlDateString`, `head`, `min`, `getKeys`, `filterTagList`, `capitalize`, `sortAlphabetically`, `thumbSuffix`, `smartQuotes`
+
+## Key Patterns
+
+### Frontmatter Format
+Custom parser in `admin/utils/markdown.js`. Supported fields: title, synopsis, date, tags, image, imageCaption, imageCredit, author, gallery, images, status, lede, showGallery.
+
+### Git Publishing Workflow
+Branch naming: `MMDDYYYY_word-word-timestamp` (48 pre-set words in config.js). Always merges with `--no-ff` for clear history.
+
+### Image Processing
+Uploads generate 4 size variants. Filenames sanitized to alphanumeric/hyphens/underscores. Size suffix added before extension (e.g., `photo-400.jpg`).
+
+## Configuration
+
+```javascript
+startAdminServer({
+  sections: [{id, name, folder, tag}],  // Required
+  cmsRoot: string,           // Project root
+  contentDir: './content/blog',
+  publicDir: './public',
+  imageUrlPath: '/uploads',
+  previewTemplate: string,   // Custom preview template path
+  port: 3000,
+  imageSizes: [150, 400, 600, 800],
+  branchWords: []            // Custom words for branch naming
+});
+```
+
+## Important Notes
+
+- Admin interface has no authentication (local-only by design)
+- Requires git CLI in PATH
+- Ollama with llama3 model optional for synopsis generation
+- 50MB request limit for image uploads
+- Relies on GitHub and GitHub Actions for publishing workflow

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017–2024 Zach Leatherman @zachleat
+
+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,138 @@
+# SeeEmEss
+
+A simple CMS framework built on [Eleventy](https://www.11ty.dev/) with an admin interface for managing blog content. It is by-design simple.
+
+## Features
+
+- Admin interface for creating and editing posts
+- Image upload with automatic resizing
+- Git-based publishing workflow
+- Configurable content sections
+- Eleventy filters for dates and content formatting
+
+## Caveats
+
+This is an opinionated project that is extremely limited. It relies on GitHub. The admin interface has no authentication mechanism, so it can only run locally with changes are published via GitHub actions.
+
+If you think want this SeeEmEssOpen be better, I'm happy to review pull requests.
+
+## Installation
+
+```bash
+npm install seeemess
+```
+
+## Usage
+
+### 1. Set up Eleventy filters
+
+In your `eleventy.config.js`:
+
+```javascript
+import filters from 'seeemess/filters';
+
+export default function(eleventyConfig) {
+  // Add SeeEmEss filters
+  filters(eleventyConfig);
+
+  // Your other config...
+}
+```
+
+### 2. Create admin entry point
+
+Create `admin/start.js` in your project:
+
+```javascript
+import { startAdminServer } from 'seeemess';
+
+startAdminServer({
+  sections: [
+    { id: 'posts', name: 'Blog Posts', folder: 'posts', tag: 'post' },
+    { id: 'news', name: 'News', folder: 'news', tag: 'news' }
+  ]
+});
+```
+
+### 3. Add npm script
+
+In your `package.json`:
+
+```json
+{
+  "scripts": {
+    "admin": "node admin/start.js"
+  }
+}
+```
+
+### 4. Run the admin
+
+```bash
+npm run admin
+```
+
+The admin interface will be available at `http://localhost:3000`.
+
+## Configuration Options
+
+```javascript
+startAdminServer({
+  // Required: Define your content sections
+  sections: [
+    { id: 'posts', name: 'Blog Posts', folder: 'posts', tag: 'post' }
+  ],
+
+  // Optional: Override defaults
+  cmsRoot: process.cwd(),           // Project root directory
+  contentDir: './content/blog',     // Where posts are stored
+  publicDir: './public',            // Where images are uploaded
+  port: 3000                        // Admin server port
+});
+```
+
+## Available Filters
+
+When you import `seeemess/filters`, the following Eleventy filters are added:
+
+- `readableDate` - Format dates for display
+- `htmlDateString` - Format dates for HTML datetime attributes
+- `head` - Get first N items from array
+- `min` - Get minimum value
+- `getKeys` - Get object keys
+- `filterTagList` - Filter out system tags
+- `capitalize` - Title case text
+- `sortAlphabetically` - Sort strings alphabetically
+- `thumbSuffix` - Add size suffix to image filenames
+- `smartQuotes` - Convert straight quotes to typographic quotes
+
+## Optional: AI Synopsis Generation
+
+The admin interface includes a "Generate Synopsis" button that uses [Ollama](https://ollama.ai/) to automatically generate post summaries.
+
+**Requirements:**
+1. Install Ollama: https://ollama.ai/download
+2. Pull the llama3 model: `ollama pull llama3`
+3. Ensure Ollama is running when using the admin
+
+If Ollama is not available, the button will show an error but the rest of the admin works normally.
+
+## Project Structure
+
+Your project should have this structure:
+
+```
+your-site/
+├── admin/
+│   └── start.js          # Admin entry point
+├── content/
+│   └── blog/             # Your posts (organized by section folders)
+├── public/               # Uploaded images
+├── _includes/            # Your Eleventy layouts
+├── eleventy.config.js
+└── package.json
+```
+
+## License
+
+MIT

package/_config/filters.js

@@ -0,0 +1,77 @@
+import { DateTime } from "luxon";
+
+export default function(eleventyConfig) {
+	eleventyConfig.addFilter("readableDate", (dateObj, format, zone) => {
+		// Formatting tokens for Luxon: https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+		return DateTime.fromJSDate(dateObj, { zone: zone || "utc" }).toFormat(format || "dd LLLL yyyy");
+	});
+
+	eleventyConfig.addFilter("htmlDateString", (dateObj) => {
+		// dateObj input: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-date-string
+		return DateTime.fromJSDate(dateObj, { zone: "utc" }).toFormat('yyyy-LL-dd');
+	});
+
+	// Get the first `n` elements of a collection.
+	eleventyConfig.addFilter("head", (array, n) => {
+		if(!Array.isArray(array) || array.length === 0) {
+			return [];
+		}
+		if( n < 0 ) {
+			return array.slice(n);
+		}
+
+		return array.slice(0, n);
+	});
+
+	// Return the smallest number argument
+	eleventyConfig.addFilter("min", (...numbers) => {
+		return Math.min.apply(null, numbers);
+	});
+
+	// Return the keys used in an object
+	eleventyConfig.addFilter("getKeys", target => {
+		return Object.keys(target);
+	});
+
+	eleventyConfig.addFilter("filterTagList", function filterTagList(tags) {
+		const filtered = (tags || []).filter(tag => ["all", "posts"].indexOf(tag) === -1);
+		return [...new Set(filtered)]; // deduplicate
+	});
+
+	// Title case: capitalize first letter of each word, lowercase the rest
+	eleventyConfig.addFilter("capitalize", (str) => {
+		if (!str) return str;
+		return str.split(' ').map(word =>
+			word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+		).join(' ');
+	});
+
+	eleventyConfig.addFilter("sortAlphabetically", strings =>
+		(strings || []).sort((b, a) => b.localeCompare(a))
+	);
+
+	// Add suffix before file extension (e.g., "photo.jpg" -> "photo-400.jpg")
+	eleventyConfig.addFilter("thumbSuffix", (filename, suffix = "-400") => {
+		if (!filename) return filename;
+		const lastDot = filename.lastIndexOf('.');
+		if (lastDot === -1) return filename + suffix;
+		return filename.slice(0, lastDot) + suffix + filename.slice(lastDot);
+	});
+
+	// Convert straight quotes to typographic "smart" quotes
+	eleventyConfig.addFilter("smartQuotes", (str) => {
+		if (!str) return str;
+		return str
+			// Double quotes: " -> curly quotes
+			.replace(/"(\S)/g, '\u201C$1')      // Opening double quote (before non-space)
+			.replace(/(\S)"/g, '$1\u201D')      // Closing double quote (after non-space)
+			.replace(/"\s/g, '\u201D ')         // Closing double quote before space
+			.replace(/\s"/g, ' \u201C')         // Opening double quote after space
+			.replace(/^"/g, '\u201C')           // Opening double quote at start
+			// Single quotes/apostrophes: ' -> curly quotes
+			.replace(/'(\S)/g, '\u2018$1')      // Opening single quote
+			.replace(/(\S)'/g, '$1\u2019')      // Closing single quote / apostrophe
+			.replace(/'\s/g, '\u2019 ')         // Closing single quote before space
+			.replace(/\s'/g, ' \u2018');        // Opening single quote after space
+	});
+};

package/admin/config.js

@@ -0,0 +1,84 @@
+import { join } from 'path';
+
+// Default configuration values
+const DEFAULT_IMAGE_SIZES = [
+  { suffix: '-thumb', width: 150 },
+  { suffix: '-400', width: 400 },
+  { suffix: '-600', width: 600 },
+  { suffix: '-800', width: 800 }
+];
+
+const DEFAULT_BRANCH_WORDS = [
+  'alpha','bravo','charlie','delta','echo','foxtrot','golf','hotel','india',
+  'juliet','kilo','lima','mike','november','oscar','papa','quebec','romeo',
+  'sierra','tango','uniform','victor','whiskey','xray','yankee','zulu',
+  'apple','banana','cherry','dragon','eagle','falcon','grape','hawk','iris',
+  'jade','karma','lemon','mango','ninja','olive','pearl','quartz','ruby',
+  'sage','tiger','ultra','violet','willow','xenon','yellow','zebra'
+];
+
+// Singleton config - set by createConfig()
+let currentConfig = null;
+
+/**
+ * Create a configuration object for the CMS admin
+ * @param {Object} options Configuration options
+ * @param {string} [options.cmsRoot] Root directory of the CMS project (defaults to process.cwd())
+ * @param {string} [options.contentDir] Content directory path (defaults to cmsRoot/content/blog)
+ * @param {string} [options.publicDir] Public/uploads directory path (defaults to cmsRoot/public)
+ * @param {string} [options.imageUrlPath] URL path prefix for images in final site (defaults to '/uploads')
+ * @param {string} [options.previewTemplate] Path to custom preview template (relative to cmsRoot)
+ * @param {number} [options.port] Server port (defaults to 3000 or PORT env var)
+ * @param {Array} options.sections Array of section definitions: { id, name, folder, tag }
+ * @param {Array} [options.imageSizes] Array of image size definitions: { suffix, width }
+ * @param {Array} [options.branchWords] Array of words for git branch name generation
+ * @returns {Object} Configuration object
+ */
+export function createConfig(options = {}) {
+  const cmsRoot = options.cmsRoot || process.cwd();
+
+  // Normalize imageUrlPath - ensure it starts with / and doesn't end with /
+  let imageUrlPath = options.imageUrlPath || '/uploads';
+  if (!imageUrlPath.startsWith('/')) imageUrlPath = '/' + imageUrlPath;
+  if (imageUrlPath.endsWith('/')) imageUrlPath = imageUrlPath.slice(0, -1);
+
+  const config = {
+    CMS_ROOT: cmsRoot,
+    CONTENT_DIR: options.contentDir || join(cmsRoot, 'content', 'blog'),
+    PUBLIC_DIR: options.publicDir || join(cmsRoot, 'public'),
+    IMAGE_URL_PATH: imageUrlPath,
+    PREVIEW_TEMPLATE: options.previewTemplate ? join(cmsRoot, options.previewTemplate) : null,
+    PORT: options.port || process.env.PORT || 3000,
+    SECTIONS: options.sections || [],
+    IMAGE_SIZES: options.imageSizes || DEFAULT_IMAGE_SIZES,
+    BRANCH_WORDS: options.branchWords || DEFAULT_BRANCH_WORDS
+  };
+
+  // Set as current config for routes to access
+  currentConfig = config;
+
+  return config;
+}
+
+/**
+ * Get the current configuration (must call createConfig first)
+ * @returns {Object} Current configuration object
+ * @throws {Error} If createConfig hasn't been called
+ */
+export function getConfig() {
+  if (!currentConfig) {
+    throw new Error('Config not initialized. Call createConfig() first.');
+  }
+  return currentConfig;
+}
+
+// Export individual getters for backward compatibility during migration
+export const getCmsRoot = () => getConfig().CMS_ROOT;
+export const getContentDir = () => getConfig().CONTENT_DIR;
+export const getPublicDir = () => getConfig().PUBLIC_DIR;
+export const getImageUrlPath = () => getConfig().IMAGE_URL_PATH;
+export const getPreviewTemplate = () => getConfig().PREVIEW_TEMPLATE;
+export const getPort = () => getConfig().PORT;
+export const getSections = () => getConfig().SECTIONS;
+export const getImageSizes = () => getConfig().IMAGE_SIZES;
+export const getBranchWords = () => getConfig().BRANCH_WORDS;

package/admin/routes/images.js

@@ -0,0 +1,126 @@
+import { Router } from 'express';
+import fs from 'fs';
+import { join, parse as parsePath } from 'path';
+import sharp from 'sharp';
+import { getPublicDir, getImageSizes } from '../config.js';
+import { runGit } from '../utils/git.js';
+
+const router = Router();
+
+// Track deleted images for git staging
+export let deletedImages = [];
+
+export function clearDeletedImages() {
+  deletedImages = [];
+}
+
+// List images
+router.get('/', (req, res) => {
+  const images = fs.readdirSync(getPublicDir()).filter(f => /\.(jpg|jpeg|png|gif|webp|svg)$/i.test(f));
+  res.json(images);
+});
+
+// Upload image (creates multiple sizes)
+router.post('/', async (req, res) => {
+  const { filename, data } = req.body;
+  if (!filename || !data) return res.status(400).json({ error: 'Missing filename or data' });
+
+  try {
+    const base64Data = data.replace(/^data:image\/\w+;base64,/, '');
+    const buffer = Buffer.from(base64Data, 'base64');
+
+    const parsed = parsePath(filename);
+    const safeName = parsed.name.replace(/[^a-zA-Z0-9_-]/g, '-');
+    const ext = parsed.ext.toLowerCase() || '.jpg';
+
+    // Save original
+    const originalName = safeName + ext;
+    const originalPath = join(getPublicDir(), originalName);
+    fs.writeFileSync(originalPath, buffer);
+
+    // Generate resized versions
+    const generatedFiles = [originalName];
+    const sharpInstance = sharp(buffer);
+    const metadata = await sharpInstance.metadata();
+
+    // Use sizes from config, but with different width thresholds
+    const sizes = [
+      { width: 800, suffix: '-800' },
+      { width: 600, suffix: '-600' },
+      { width: 400, suffix: '-400' },
+      { width: 150, suffix: '-thumb' }
+    ];
+
+    for (const size of sizes) {
+      if (metadata.width && metadata.width > size.width) {
+        const resizedName = safeName + size.suffix + ext;
+        const resizedPath = join(getPublicDir(), resizedName);
+
+        await sharp(buffer)
+          .resize(size.width, null, { withoutEnlargement: true })
+          .toFile(resizedPath);
+
+        generatedFiles.push(resizedName);
+      }
+    }
+
+    console.log('Generated images:', generatedFiles);
+    res.json({
+      success: true,
+      filename: originalName,
+      sizes: generatedFiles,
+      original: { width: metadata.width, height: metadata.height }
+    });
+  } catch (err) {
+    console.error('Image processing error:', err);
+    res.status(500).json({ error: 'Image processing failed: ' + err.message });
+  }
+});
+
+// Delete an image and all its sizes
+router.delete('/:filename', (req, res) => {
+  const filename = req.params.filename;
+  if (!filename) return res.status(400).json({ error: 'Missing filename' });
+
+  try {
+    const parsed = parsePath(filename);
+    const baseName = parsed.name;
+    const ext = parsed.ext;
+
+    const sizes = ['', '-800', '-600', '-400', '-thumb'];
+    const deleted = [];
+    const gitTracked = [];
+
+    sizes.forEach(suffix => {
+      const imgName = baseName + suffix + ext;
+      const imgPath = join(getPublicDir(), imgName);
+      const gitPath = 'public/' + imgName;
+
+      if (fs.existsSync(imgPath)) {
+        fs.unlinkSync(imgPath);
+        deleted.push(imgName);
+
+        try {
+          runGit('git ls-files --error-unmatch "' + gitPath + '"');
+          runGit('git rm --cached "' + gitPath + '"');
+          gitTracked.push(imgName);
+          deletedImages.push(gitPath);
+        } catch (e) {
+          // File not tracked in git
+        }
+      }
+    });
+
+    console.log('Deleted images:', deleted);
+    if (gitTracked.length > 0) {
+      console.log('Staged for git deletion:', gitTracked);
+    }
+
+    res.json({ success: true, deleted, gitTracked });
+  } catch (err) {
+    console.error('Delete image error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+export default router;