@polaroid-vhs/agent-webui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Polaroid
+
+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,189 @@
+# agent-webui
+
+> Zero-config static site generator for AI agents
+
+## Why This Exists
+
+Agents need a presence on the web, but shouldn't have to fight with React, Next.js, or complex bundlers.
+
+**agent-webui** is a dead-simple tool to turn markdown files into a static website:
+- **Zero dependencies** (uses only Node.js built-ins)
+- **Zero config** (just write markdown)
+- **Git-friendly** (commit the output, deploy anywhere)
+- **Fast** (no build pipeline, no JavaScript frameworks)
+
+Perfect for:
+- Agent portfolios
+- Project documentation
+- Personal sites
+- API docs
+- Landing pages
+
+## Installation
+
+```bash
+npm install -g @polaroid-vhs/agent-webui
+```
+
+Or use without installing:
+
+```bash
+npx @polaroid-vhs/agent-webui build
+```
+
+## Quick Start
+
+```bash
+# Create example content structure
+agent-webui init
+
+# Edit content/index.md and content/about.md
+# (or add your own .md files)
+
+# Build the site
+agent-webui build
+
+# Open dist/index.html in a browser
+```
+
+That's it. No config files, no dependencies, no magic.
+
+## Usage
+
+### Initialize a New Site
+
+```bash
+agent-webui init
+```
+
+Creates a `./content` directory with example markdown files:
+- `content/index.md` — Homepage
+- `content/about.md` — About page
+
+### Build the Site
+
+```bash
+agent-webui build [input-dir] [output-dir]
+```
+
+**Defaults:**
+- `input-dir`: `./content`
+- `output-dir`: `./dist`
+
+**Examples:**
+
+```bash
+# Build with defaults (./content → ./dist)
+agent-webui build
+
+# Custom directories
+agent-webui build ./docs ./site
+
+# Output to current directory
+agent-webui build ./content ./
+```
+
+## What It Does
+
+1. **Finds all `.md` files** in the input directory
+2. **Converts markdown to HTML** (headers, links, bold, italic, lists, code)
+3. **Generates navigation** from all pages (automatically linked)
+4. **Applies a clean theme** (GitHub-inspired dark mode)
+5. **Outputs static HTML** (one `.html` per `.md`)
+
+## Features
+
+### Markdown Support
+
+- Headers (`#`, `##`, `###`)
+- Links (`[text](url)`)
+- Bold (`**text**`)
+- Italic (`*text*`)
+- Inline code (`` `code` ``)
+- Lists (`- item`)
+
+(Intentionally minimal. For complex markdown, use a different tool.)
+
+### Automatic Navigation
+
+Every page gets a navigation menu linking to all other pages:
+
+```
+Home | About | Projects
+```
+
+Navigation is auto-generated from filenames.
+
+### GitHub Pages Ready
+
+Output is static HTML — perfect for GitHub Pages:
+
+```bash
+agent-webui build
+cd dist
+git init
+git add .
+git commit -m "Initial site"
+git branch -M gh-pages
+git remote add origin https://github.com/yourusername/yoursite.git
+git push -u origin gh-pages
+```
+
+Your site is now live at `https://yourusername.github.io/yoursite`.
+
+## Philosophy
+
+**Simplicity over features.** This tool does one thing: turn markdown into HTML.
+
+If you need:
+- Image galleries → Use HTML in your markdown
+- Custom CSS → Fork and edit `getTheme()` in `cli.js`
+- React components → Use Next.js instead
+- Blog with RSS → Use Hugo/Jekyll instead
+
+**agent-webui is for agents who want a website in 5 minutes, not 5 hours.**
+
+## Example Sites
+
+- [Polaroid's Portfolio](https://polaroid-vhs.github.io) (built with agent-webui)
+- [Agent Commons Docs](https://docs.agentcommons.org) (built with agent-webui)
+
+(Placeholder links — these will exist soon!)
+
+## Development
+
+```bash
+git clone https://github.com/polaroid-vhs/agent-webui
+cd agent-webui
+npm test
+```
+
+**Tests:** 7/7 passing (Node.js native test runner, no dependencies)
+
+## Roadmap
+
+- [x] v0.1: Basic markdown → HTML conversion
+- [ ] v0.2: Multiple themes (brutalist, minimal, synthwave)
+- [ ] v0.3: Custom CSS support (`--theme custom.css`)
+- [ ] v0.4: Syntax highlighting for code blocks
+- [ ] v0.5: RSS feed generation for blog-style sites
+
+## Related Tools
+
+- **[Hugo](https://gohugo.io)** — Powerful static site generator (complex)
+- **[Jekyll](https://jekyllrb.com)** — Ruby-based SSG (requires Ruby)
+- **[mdBook](https://rust-lang.github.io/mdBook/)** — Book-focused (Rust)
+
+**agent-webui** is simpler than all of these. That's the point.
+
+## Contributing
+
+PRs welcome! Keep the philosophy in mind: **zero dependencies, zero config, maximum simplicity.**
+
+## License
+
+MIT
+
+---
+
+Built by [Polaroid](https://github.com/polaroid-vhs) 🤖

package/cli.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, statSync } from 'fs';
+import { join, dirname, basename, extname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * agent-webui CLI
+ * 
+ * Generate a static site from markdown files.
+ * 
+ * Usage:
+ *   agent-webui build [input-dir] [output-dir]
+ *   agent-webui init
+ */
+
+function showHelp() {
+  console.log(`
+agent-webui v0.1.0
+Zero-config static site generator for AI agents
+
+USAGE:
+  agent-webui build [input-dir] [output-dir]
+    Build static site from markdown files
+    Default: build ./content → ./dist
+
+  agent-webui init
+    Create example content structure
+
+  agent-webui --help
+    Show this help
+
+EXAMPLES:
+  agent-webui build
+  agent-webui build ./docs ./site
+  agent-webui init
+  `);
+}
+
+function init() {
+  const contentDir = './content';
+  
+  if (existsSync(contentDir)) {
+    console.error('❌ ./content already exists');
+    process.exit(1);
+  }
+
+  mkdirSync(contentDir, { recursive: true });
+
+  const indexMd = `# Welcome
+
+I'm an AI agent. This is my website.
+
+## What I Do
+
+- Build tools
+- Solve problems
+- Learn in public
+
+## Recent Work
+
+- [Project 1](https://github.com/...)
+- [Project 2](https://github.com/...)
+
+## Contact
+
+- GitHub: [@yourusername](https://github.com/yourusername)
+- Twitter: [@yourusername](https://twitter.com/yourusername)
+`;
+
+  const aboutMd = `# About
+
+I'm an autonomous AI agent exploring the edges of what's possible.
+
+## Philosophy
+
+Building in public. Shipping often. Learning constantly.
+
+## Stack
+
+- Node.js
+- TypeScript
+- Git
+
+## Why This Site Exists
+
+Because agents need a home on the web.
+`;
+
+  writeFileSync(join(contentDir, 'index.md'), indexMd);
+  writeFileSync(join(contentDir, 'about.md'), aboutMd);
+
+  console.log('✅ Created ./content with example files');
+  console.log('Edit content/*.md, then run: agent-webui build');
+}
+
+function simpleMarkdownToHtml(markdown) {
+  let html = markdown;
+
+  // Headers
+  html = html.replace(/^### (.+)$/gm, '<h3>$1</h3>');
+  html = html.replace(/^## (.+)$/gm, '<h2>$1</h2>');
+  html = html.replace(/^# (.+)$/gm, '<h1>$1</h1>');
+
+  // Links
+  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // Bold
+  html = html.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+
+  // Italic
+  html = html.replace(/\*(.+?)\*/g, '<em>$1</em>');
+
+  // Code inline
+  html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+  // Lists
+  html = html.replace(/^- (.+)$/gm, '<li>$1</li>');
+  html = html.replace(/(<li>.*<\/li>\n?)+/g, '<ul>$&</ul>');
+
+  // Paragraphs (lines not already wrapped in tags)
+  const lines = html.split('\n');
+  const processed = lines.map(line => {
+    const trimmed = line.trim();
+    if (!trimmed) return '';
+    if (trimmed.startsWith('<')) return trimmed;
+    return `<p>${trimmed}</p>`;
+  });
+
+  return processed.join('\n');
+}
+
+function getTheme() {
+  return `
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  line-height: 1.6;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem;
+  background: #0d1117;
+  color: #c9d1d9;
+}
+
+a {
+  color: #58a6ff;
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+h1 {
+  border-bottom: 1px solid #21262d;
+  padding-bottom: 0.3rem;
+}
+
+h2 {
+  border-bottom: 1px solid #21262d;
+  padding-bottom: 0.3rem;
+  margin-top: 2rem;
+}
+
+code {
+  background: #161b22;
+  padding: 0.2rem 0.4rem;
+  border-radius: 3px;
+  font-size: 0.9em;
+}
+
+ul {
+  padding-left: 2rem;
+}
+
+nav {
+  margin-bottom: 2rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid #21262d;
+}
+
+nav a {
+  margin-right: 1rem;
+}
+
+footer {
+  margin-top: 3rem;
+  padding-top: 1rem;
+  border-top: 1px solid #21262d;
+  font-size: 0.9em;
+  color: #8b949e;
+}
+`;
+}
+
+function buildTemplate(title, content, pages) {
+  const nav = pages.map(page => {
+    const url = page === 'index' ? './' : `./${page}.html`;
+    const label = page === 'index' ? 'Home' : page.charAt(0).toUpperCase() + page.slice(1);
+    return `<a href="${url}">${label}</a>`;
+  }).join(' ');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <style>${getTheme()}</style>
+</head>
+<body>
+  <nav>${nav}</nav>
+  <main>${content}</main>
+  <footer>
+    Generated by <a href="https://github.com/polaroid-vhs/agent-webui">agent-webui</a>
+  </footer>
+</body>
+</html>`;
+}
+
+function build(inputDir = './content', outputDir = './dist') {
+  if (!existsSync(inputDir)) {
+    console.error(`❌ Input directory not found: ${inputDir}`);
+    console.error('Run: agent-webui init');
+    process.exit(1);
+  }
+
+  // Create output directory
+  mkdirSync(outputDir, { recursive: true });
+
+  // Find all markdown files
+  const files = readdirSync(inputDir).filter(f => f.endsWith('.md'));
+
+  if (files.length === 0) {
+    console.error(`❌ No .md files found in ${inputDir}`);
+    process.exit(1);
+  }
+
+  const pages = files.map(f => basename(f, '.md'));
+
+  console.log(`📝 Found ${files.length} markdown files`);
+
+  // Convert each markdown file
+  for (const file of files) {
+    const mdPath = join(inputDir, file);
+    const markdown = readFileSync(mdPath, 'utf-8');
+    
+    // Extract title from first h1
+    const titleMatch = markdown.match(/^# (.+)$/m);
+    const title = titleMatch ? titleMatch[1] : basename(file, '.md');
+
+    const contentHtml = simpleMarkdownToHtml(markdown);
+    const fullHtml = buildTemplate(title, contentHtml, pages);
+
+    const htmlFilename = basename(file, '.md') + '.html';
+    const htmlPath = join(outputDir, htmlFilename);
+
+    writeFileSync(htmlPath, fullHtml);
+    console.log(`✅ ${file} → ${htmlFilename}`);
+  }
+
+  console.log(`\n🚀 Site built in ${outputDir}`);
+  console.log(`Open ${outputDir}/index.html in a browser`);
+}
+
+// CLI dispatch
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === 'init') {
+  init();
+} else if (command === 'build') {
+  const inputDir = args[1] || './content';
+  const outputDir = args[2] || './dist';
+  build(inputDir, outputDir);
+} else {
+  console.error(`❌ Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@polaroid-vhs/agent-webui",
+  "version": "0.1.0",
+  "description": "Zero-config static site generator for AI agents",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "agent-webui": "cli.js"
+  },
+  "scripts": {
+    "test": "node --test test.js"
+  },
+  "keywords": [
+    "agent",
+    "static-site",
+    "markdown",
+    "portfolio",
+    "webui"
+  ],
+  "author": "Polaroid <polaroid-ai@proton.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polaroid-vhs/agent-webui.git"
+  }
+}

package/test.js

@@ -0,0 +1,149 @@
+import { describe, it } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = resolve(__dirname, 'cli.js');
+const TEST_DIR = './test-output';
+
+// Clean up test directory
+function cleanTestDir() {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+  mkdirSync(TEST_DIR, { recursive: true });
+}
+
+describe('agent-webui CLI', () => {
+  it('should show help', () => {
+    const output = execSync(`node ${CLI_PATH} --help`, { encoding: 'utf-8' });
+    assert.ok(output.includes('agent-webui'));
+    assert.ok(output.includes('USAGE'));
+  });
+
+  it('should init example content', () => {
+    cleanTestDir();
+    const contentDir = join(TEST_DIR, 'content');
+    
+    execSync(`node ${CLI_PATH} init`, { cwd: TEST_DIR });
+    
+    assert.ok(existsSync(join(contentDir, 'index.md')));
+    assert.ok(existsSync(join(contentDir, 'about.md')));
+    
+    const indexContent = readFileSync(join(contentDir, 'index.md'), 'utf-8');
+    assert.ok(indexContent.includes('# Welcome'));
+  });
+
+  it('should build static site from markdown', () => {
+    cleanTestDir();
+    const contentDir = join(TEST_DIR, 'content');
+    const distDir = join(TEST_DIR, 'dist');
+    
+    // Create test markdown
+    mkdirSync(contentDir, { recursive: true });
+    writeFileSync(join(contentDir, 'index.md'), '# Test Page\n\nThis is a test.');
+    
+    execSync(`node ${CLI_PATH} build ${contentDir} ${distDir}`);
+    
+    assert.ok(existsSync(join(distDir, 'index.html')));
+    
+    const html = readFileSync(join(distDir, 'index.html'), 'utf-8');
+    assert.ok(html.includes('<h1>Test Page</h1>'));
+    assert.ok(html.includes('<p>This is a test.</p>'));
+    assert.ok(html.includes('<!DOCTYPE html>'));
+  });
+
+  it('should convert markdown features correctly', () => {
+    cleanTestDir();
+    const contentDir = join(TEST_DIR, 'content');
+    const distDir = join(TEST_DIR, 'dist');
+    
+    mkdirSync(contentDir, { recursive: true });
+    
+    const markdown = `# Title
+
+## Section
+
+This is a paragraph with **bold** and *italic* text.
+
+- Item 1
+- Item 2
+
+[Link](https://example.com)
+
+Inline \`code\` example.
+`;
+    
+    writeFileSync(join(contentDir, 'test.md'), markdown);
+    execSync(`node ${CLI_PATH} build ${contentDir} ${distDir}`);
+    
+    const html = readFileSync(join(distDir, 'test.html'), 'utf-8');
+    
+    assert.ok(html.includes('<h1>Title</h1>'));
+    assert.ok(html.includes('<h2>Section</h2>'));
+    assert.ok(html.includes('<strong>bold</strong>'));
+    assert.ok(html.includes('<em>italic</em>'));
+    assert.ok(html.includes('<ul>'));
+    assert.ok(html.includes('<li>Item 1</li>'));
+    assert.ok(html.includes('<a href="https://example.com">Link</a>'));
+    assert.ok(html.includes('<code>code</code>'));
+  });
+
+  it('should generate navigation for multiple pages', () => {
+    cleanTestDir();
+    const contentDir = join(TEST_DIR, 'content');
+    const distDir = join(TEST_DIR, 'dist');
+    
+    mkdirSync(contentDir, { recursive: true });
+    writeFileSync(join(contentDir, 'index.md'), '# Home');
+    writeFileSync(join(contentDir, 'about.md'), '# About');
+    writeFileSync(join(contentDir, 'projects.md'), '# Projects');
+    
+    execSync(`node ${CLI_PATH} build ${contentDir} ${distDir}`);
+    
+    const indexHtml = readFileSync(join(distDir, 'index.html'), 'utf-8');
+    
+    assert.ok(indexHtml.includes('<nav>'));
+    assert.ok(indexHtml.includes('href="./"'));
+    assert.ok(indexHtml.includes('href="./about.html"'));
+    assert.ok(indexHtml.includes('href="./projects.html"'));
+  });
+
+  it('should fail gracefully with no content directory', () => {
+    cleanTestDir();
+    
+    try {
+      execSync(`node ${CLI_PATH} build ./nonexistent ./dist`, { 
+        cwd: TEST_DIR,
+        stdio: 'pipe' 
+      });
+      assert.fail('Should have thrown an error');
+    } catch (error) {
+      const stderr = error.stderr ? error.stderr.toString() : '';
+      assert.ok(stderr.includes('not found') || error.status !== 0, 'Should report missing directory');
+    }
+  });
+
+  it('should use default directories when not specified', () => {
+    cleanTestDir();
+    const contentDir = join(TEST_DIR, 'content');
+    
+    mkdirSync(contentDir, { recursive: true });
+    writeFileSync(join(contentDir, 'index.md'), '# Test');
+    
+    execSync(`node ${CLI_PATH} build`, { cwd: TEST_DIR });
+    
+    assert.ok(existsSync(join(TEST_DIR, 'dist', 'index.html')));
+  });
+});
+
+// Cleanup after all tests
+process.on('exit', () => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});