@symbiosis-lab/moss-plugin-matters 1.4.2

package/src/utils.ts

@@ -0,0 +1,305 @@
+/**
+ * Utility functions for the Matters Syndicator Plugin
+ *
+ * This module wraps SDK utilities with plugin-specific functionality
+ * and provides Matters-specific helper functions.
+ */
+
+import {
+  setMessageContext,
+  sendMessage as sdkSendMessage,
+  reportError as sdkReportError,
+  fetchUrl,
+  downloadAsset as sdkDownloadAsset,
+  type PluginMessage,
+} from "@symbiosis-lab/moss-api";
+
+// ============================================================================
+// Plugin Configuration
+// ============================================================================
+
+const PLUGIN_NAME = "matters";
+
+// Initialize message context on load
+setMessageContext(PLUGIN_NAME, "");
+
+// ============================================================================
+// Re-exports from SDK (with plugin context)
+// ============================================================================
+
+/**
+ * Set the current hook name for message routing
+ */
+export function setCurrentHookName(name: string): void {
+  setMessageContext(PLUGIN_NAME, name);
+}
+
+/**
+ * Get the current hook name (for compatibility)
+ */
+let _currentHookName = "";
+export function getCurrentHookName(): string {
+  return _currentHookName;
+}
+
+// Override setCurrentHookName to also track locally
+const originalSetCurrentHookName = setCurrentHookName;
+export { originalSetCurrentHookName };
+
+/**
+ * Send a message to moss (logs, progress, errors)
+ */
+export async function sendMessage(message: PluginMessage): Promise<void> {
+  await sdkSendMessage(message);
+}
+
+/**
+ * Report an error to moss during hook execution
+ */
+export async function reportError(
+  error: string,
+  context?: string,
+  fatal = false
+): Promise<void> {
+  await sdkReportError(error, context, fatal);
+}
+
+// ============================================================================
+// String Utilities
+// ============================================================================
+
+/**
+ * Generate a URL-safe slug from text
+ * Preserves Unicode characters (CJK, Cyrillic, Arabic, etc.)
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .replace(/\s+/g, "-")
+    .replace(/--+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "");
+}
+
+/**
+ * Simple hash function for generating filenames
+ */
+export function simpleHash(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16);
+}
+
+// ============================================================================
+// Filename Utilities
+// ============================================================================
+
+/**
+ * Generate a local filename from a URL
+ */
+export function generateLocalFilename(url: string): string | null {
+  try {
+    const urlObj = new URL(url);
+    const pathname = urlObj.pathname;
+    const cleanPath = pathname.replace(/\/public$/, "");
+    const segments = cleanPath.split("/").filter((s) => s.length > 0);
+
+    // Find a segment with an extension
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const segment = segments[i];
+      const extMatch = segment.match(/\.(\w+)$/);
+      if (extMatch) {
+        const ext = extMatch[1].toLowerCase();
+        if (i > 0 && /^[a-f0-9-]{36}$/i.test(segments[i - 1])) {
+          return `${segments[i - 1]}.${ext}`;
+        }
+        return segment;
+      }
+    }
+
+    // No extension found, try to find a UUID
+    for (const segment of segments) {
+      if (/^[a-f0-9-]{36}$/i.test(segment)) {
+        return segment;
+      }
+    }
+
+    // Fallback: hash the URL
+    return simpleHash(url);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get file extension from Content-Type header
+ */
+export function getExtensionFromContentType(contentType: string): string | null {
+  const mapping: Record<string, string> = {
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/svg+xml": "svg",
+  };
+
+  for (const [type, ext] of Object.entries(mapping)) {
+    if (contentType.includes(type)) {
+      return ext;
+    }
+  }
+  return null;
+}
+
+// ============================================================================
+// Async Utilities
+// ============================================================================
+
+/**
+ * Sleep for specified milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================================================
+// HTTP Utilities (using moss-api)
+// ============================================================================
+
+/**
+ * Result from downloadAsset function
+ */
+export interface DownloadAssetResult {
+  status: number;
+  ok: boolean;
+  content_type: string | null;
+  bytes_written: number;
+  actual_path: string;
+}
+
+/**
+ * Fetch a URL using moss-api (bypasses WebKit CORS).
+ *
+ * Returns a Response-like object for compatibility with existing code.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  timeoutMs = 30000
+): Promise<Response> {
+  const result = await fetchUrl(url, { timeoutMs });
+
+  // Create Response-like object
+  const headers = new Headers();
+  if (result.contentType) {
+    headers.set("content-type", result.contentType);
+  }
+
+  return new Response(result.body.buffer as ArrayBuffer, {
+    status: result.status,
+    headers,
+  });
+}
+
+/**
+ * Download a URL and save directly to disk using moss-api.
+ *
+ * This function downloads a file and writes it directly to disk without
+ * passing the binary data through JavaScript. This avoids event loop blocking
+ * that occurs with large files when using base64 encoding/decoding.
+ *
+ * moss handles filename derivation from the URL and adds file extension from
+ * Content-Type if the URL has no extension.
+ *
+ * @param url - URL to download
+ * @param targetDir - Target directory within project (e.g., "assets")
+ * @param timeoutMs - Optional timeout in milliseconds (defaults to 30 seconds)
+ * @returns Result with status, content-type, bytes written, and actual_path
+ */
+export async function downloadAsset(
+  url: string,
+  targetDir: string,
+  timeoutMs = 30000
+): Promise<DownloadAssetResult> {
+  const result = await sdkDownloadAsset(url, targetDir, { timeoutMs });
+
+  // Map moss-api result to existing interface for backward compatibility
+  return {
+    status: result.status,
+    ok: result.ok,
+    content_type: result.contentType,
+    bytes_written: result.bytesWritten,
+    actual_path: result.actualPath,
+  };
+}
+
+// ============================================================================
+// Sync receipt formatting
+// ============================================================================
+
+/**
+ * Format the article-sync outcome as a NOUN-LED receipt line for the progress
+ * surface — "12 articles already up to date", not a bare "12 unchanged" whose
+ * subject the reader has to guess. Pure + total-aware so the headline reads as
+ * one fact (how many articles, and what happened to them) rather than a string
+ * of disconnected counts.
+ *
+ * Image/link/comment outcomes are NOT folded in here — successes stay silent
+ * ("success makes no sound") and failed images ride a per-image advisory.
+ */
+export function formatArticleSyncSummary(counts: {
+  created: number;
+  updated: number;
+  skipped: number;
+  failed: number;
+}): string {
+  const { created, updated, skipped, failed } = counts;
+  const synced = created + updated + skipped;
+  const s = (n: number): string => (n === 1 ? "" : "s");
+
+  if (synced === 0) {
+    return failed > 0
+      ? `${failed} article${s(failed)} failed to sync`
+      : "no articles to sync";
+  }
+
+  let base: string;
+  if (created === 0 && updated === 0) {
+    // Every synced article already matched its remote — the common "nothing
+    // changed" run. This is the line the user found opaque as "5 unchanged".
+    base = `${synced} article${s(synced)} already up to date`;
+  } else {
+    const changed: string[] = [];
+    if (created > 0) changed.push(`${created} new`);
+    if (updated > 0) changed.push(`${updated} updated`);
+    if (skipped > 0) changed.push(`${skipped} unchanged`);
+    base = `${synced} article${s(synced)}: ${changed.join(", ")}`;
+  }
+
+  // Trailing failure clause with an explicit verb so it reads as a SEPARATE
+  // cohort, not part of the synced set — "5 articles already up to date,
+  // 2 failed to sync" (the bare ", 2 failed" looked like 2 of the 5 broke).
+  return failed > 0 ? `${base}, ${failed} failed to sync` : base;
+}
+
+// ============================================================================
+// Binary Utilities
+// ============================================================================
+
+/**
+ * Convert Uint8Array to base64 string in chunks to avoid stack overflow
+ */
+export function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const chunkSize = 8192;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const chunk = bytes.subarray(i, i + chunkSize);
+    binary += String.fromCharCode.apply(null, chunk as unknown as number[]);
+  }
+  return btoa(binary);
+}

package/test-fixtures/syndication-test-site/input/index.md

@@ -0,0 +1,8 @@
+---
+title: Syndication Test Site
+uid: 37facec5
+---
+
+# Syndication Test Site
+
+A test site for validating the Matters plugin syndication flow.

package/test-fixtures/syndication-test-site/input/posts/rich-test-article.md

@@ -0,0 +1,90 @@
+---
+title: "Exploring Decentralized Publishing: A Test Article"
+uid: 6aef0cb6
+date: 2025-02-10
+tags:
+  - web3
+  - publishing
+  - decentralization
+  - test
+description: A comprehensive test article for validating Matters syndication with rich markdown content including code, quotes, lists, and more.
+---
+
+## Introduction
+
+This article tests the full syndication pipeline from a local moss project to [Matters](https://matters.icu), a decentralized publishing platform built on IPFS. The goal is to verify that all markdown elements render correctly after conversion to HTML.
+
+## Why Decentralized Publishing Matters
+
+Traditional publishing platforms come with **inherent risks**: content can be censored, servers can go down, and users don't truly *own* their work. Decentralized platforms address these issues by:
+
+1. Storing content on **distributed networks** like IPFS
+2. Giving authors **cryptographic ownership** of their publications
+3. Enabling **peer-to-peer** content distribution
+4. Providing **censorship resistance** through redundancy
+
+> "The internet was designed to be decentralized. We're simply returning to first principles."
+> -- Tim Berners-Lee
+
+## Technical Deep Dive
+
+The syndication process works through a POSSE (Publish Own Site, Syndicate Elsewhere) workflow:
+
+### Step 1: Content Processing
+
+The plugin reads local markdown files and converts them to HTML using a custom converter. Here's a simplified example of the conversion pipeline:
+
+```python
+def convert_article(markdown_content: str) -> str:
+    """Convert markdown to Matters-compatible HTML."""
+    html = markdown_to_html(markdown_content)
+    html = rewrite_image_urls(html)
+    html = add_canonical_link(html)
+    return html
+```
+
+### Step 2: Draft Creation
+
+After conversion, the plugin creates a draft on Matters via the GraphQL API:
+
+```graphql
+mutation PutDraft($input: PutDraftInput!) {
+  putDraft(input: $input) {
+    id
+    title
+    content
+    publishState
+  }
+}
+```
+
+### Step 3: User Review & Publish
+
+The draft opens in a browser window for review. The user can:
+
+- Edit the title and summary
+- Add or modify tags
+- Upload a cover image
+- Click **Publish** when ready
+
+## Feature Checklist
+
+Here's what we're testing with this article:
+
+- [x] Basic paragraphs and text formatting
+- [x] Headings (H2, H3)
+- [x] Bold and italic text
+- [x] Ordered and unordered lists
+- [x] Code blocks with syntax highlighting
+- [x] Blockquotes
+- [x] External links
+- [x] Horizontal rules
+- [ ] Image embedding (requires separate test)
+
+---
+
+## Conclusion
+
+If you're reading this on Matters, the syndication was successful. The article was originally published on a local test site and automatically syndicated using the moss Matters plugin.
+
+For more information about moss, visit the [project repository](https://github.com/nicholasgasior/gostatic).

package/test-helpers/TEST_ACCOUNT.md

@@ -0,0 +1,151 @@
+> **Warning:** This file documents how to configure test credentials. NEVER commit a real wallet private key. Use a throwaway test account funded only with disposable test tokens.
+
+# Matters Test Account Setup
+
+This document describes how to set up a test account for E2E testing on Matters.icu (test environment).
+
+## Overview
+
+The Matters plugin uses Ethereum wallet authentication for E2E tests. This allows programmatic login without requiring email verification, making it suitable for CI/CD environments.
+
+## Environment
+
+- **Test Server**: `https://server.matters.icu/graphql`
+- **Test Website**: `https://matters.icu`
+- **Authentication**: Ethereum wallet (EIP-4361 Sign-In with Ethereum)
+
+## Setting Up a Test Account
+
+### 1. Generate a Test Wallet
+
+You can generate a new Ethereum wallet using ethers.js:
+
+```typescript
+import { Wallet } from "ethers";
+
+const wallet = Wallet.createRandom();
+console.log("Private Key:", wallet.privateKey);
+console.log("Address:", wallet.address);
+```
+
+Or using the command line with Foundry:
+
+```bash
+cast wallet new
+```
+
+### 2. Store the Private Key
+
+Add the private key to your GitHub repository secrets:
+
+1. Go to your repository Settings → Secrets and variables → Actions
+2. Create a new secret: `MATTERS_TEST_WALLET_PRIVATE_KEY`
+3. Paste the private key (with or without `0x` prefix)
+
+For local development, add to your `.env` file (never commit this!):
+
+```bash
+MATTERS_TEST_WALLET_PRIVATE_KEY=0x...your-private-key...
+```
+
+### 3. First Login Creates Account
+
+The first time you authenticate with the wallet, Matters will automatically create a new account. Subsequent logins will use the existing account.
+
+## Usage in Tests
+
+### Basic Authentication
+
+```typescript
+import { walletLogin, createAuthenticatedClient } from "./wallet-auth";
+
+// Login with environment variable
+const auth = await walletLogin();
+console.log("Logged in as:", auth.user.userName);
+
+// Create authenticated client
+const query = createAuthenticatedClient(auth.token);
+
+// Make authenticated requests
+const result = await query(`
+  query {
+    viewer {
+      id
+      userName
+    }
+  }
+`);
+```
+
+### With Custom Endpoint
+
+```typescript
+const auth = await walletLogin(
+  process.env.MATTERS_TEST_WALLET_PRIVATE_KEY,
+  "https://server.matters.icu/graphql"
+);
+```
+
+## CI Configuration
+
+### GitHub Actions Example
+
+```yaml
+name: E2E Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      MATTERS_TEST_WALLET_PRIVATE_KEY: ${{ secrets.MATTERS_TEST_WALLET_PRIVATE_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npm run test:e2e
+```
+
+## Security Notes
+
+1. **Never commit private keys** to the repository
+2. Use GitHub Secrets for CI/CD
+3. The test wallet should only hold test assets
+4. Consider using a dedicated test wallet, not a production wallet
+5. The test environment (matters.icu) is separate from production (matters.town)
+
+## Troubleshooting
+
+### "ethers.js is required"
+
+Install ethers as a dev dependency:
+
+```bash
+npm install --save-dev ethers
+```
+
+### "Login failed: auth returned false"
+
+- Verify the private key is correct
+- Check if the endpoint is reachable
+- Ensure the signing message hasn't expired (10 minute validity)
+
+### Rate Limiting
+
+The Matters API has rate limits. If you see 429 errors, wait a few minutes before retrying.
+
+## Test Data Considerations
+
+When writing tests that create content (articles, comments, etc.):
+
+1. Use descriptive titles with test identifiers (e.g., `[TEST] My Article`)
+2. Clean up test data after tests when possible
+3. Consider using unique identifiers to avoid conflicts between parallel test runs
+
+## Related Files
+
+- [wallet-auth.ts](./wallet-auth.ts) - Wallet authentication implementation
+- [api-client.ts](./api-client.ts) - GraphQL client for public queries