@bryanguffey/astro-standard-site 1.0.0

package/README.md

@@ -0,0 +1,348 @@
+# astro-standard-site
+
+The first Astro integration for [standard.site](https://standard.site) — a unified schema for longform publishing on ATProto.
+
+**Write once, publish everywhere.** Sync your Astro blog with any platform that supports the standard.site lexicon, like [pckt](https://pckt.blog)(**soon**), [Leaflet](https://leaflet.pub)(**soon**), and [Offprint](https://offprint.app)
+(also **soon**). 
+
+Created with love by Bryan Guffey
+
+## Features
+
+- 📤 **Publish** — Sync your Astro blog posts to ATProto
+- 📥 **Load** — Fetch documents from any ATProto repository  
+- 💬 **Comments** — Display Bluesky replies as comments on your blog
+- 🔄 **Transform** — Convert sidenotes, resolve relative links, extract plain text
+- ✅ **Verify** — Generate `.well-known` endpoints and link tags per spec
+- 📝 **Type-safe** — Full TypeScript support with Zod schemas
+
+## Installation
+
+```bash
+npm install astro-standard-site
+```
+
+## Quick Start
+
+### 1. Publish Your Blog Posts to ATProto
+
+```ts
+// scripts/sync-to-atproto.ts
+import { getCollection } from 'astro:content';
+import { StandardSitePublisher, transformPost } from 'astro-standard-site';
+
+const publisher = new StandardSitePublisher({
+  identifier: 'your-handle.bsky.social',
+  password: process.env.ATPROTO_APP_PASSWORD!,
+});
+
+await publisher.login();
+console.log('Logged in! PDS:', publisher.getPdsUrl());
+
+// Get all blog posts
+const posts = await getCollection('blog');
+
+for (const post of posts) {
+  if (post.data.draft) continue;
+  
+  // Transform Astro post to standard.site format
+  const doc = transformPost(post, { 
+    siteUrl: 'https://yourblog.com' 
+  });
+  
+  // Publish to ATProto
+  const result = await publisher.publishDocument(doc);
+  console.log(`Published: ${post.slug} → ${result.uri}`);
+}
+```
+
+### 2. Add Comments from Bluesky
+
+```astro
+---
+// src/layouts/BlogPost.astro
+import Comments from 'astro-standard-site/components/Comments.astro';
+
+// After publishing, save the Bluesky post URI in your frontmatter
+const { bskyPostUri } = Astro.props.post.data;
+---
+
+<article>
+  <slot />
+</article>
+
+<Comments 
+  bskyPostUri={bskyPostUri}
+  canonicalUrl={Astro.url.href}
+/>
+```
+
+### 3. Set Up Verification
+
+```ts
+// src/pages/.well-known/site.standard.publication.ts
+import type { APIRoute } from 'astro';
+import { generatePublicationWellKnown } from 'astro-standard-site';
+
+export const GET: APIRoute = () => {
+  return new Response(
+    generatePublicationWellKnown({
+      did: 'did:plc:your-did-here',
+      publicationRkey: 'your-publication-rkey',
+    }),
+    { headers: { 'Content-Type': 'text/plain' } }
+  );
+};
+```
+
+## API Reference
+
+### Publisher
+
+```ts
+import { StandardSitePublisher } from 'astro-standard-site';
+
+const publisher = new StandardSitePublisher({
+  identifier: 'handle.bsky.social',  // or DID
+  password: process.env.ATPROTO_APP_PASSWORD!,
+  // service: 'https://...'  // Optional: auto-resolved from DID
+});
+
+await publisher.login();
+
+// Publish a document
+await publisher.publishDocument({
+  site: 'https://yourblog.com',        // Required
+  title: 'My Post',                     // Required
+  publishedAt: new Date().toISOString(), // Required
+  path: '/blog/my-post',               // Optional
+  description: 'A great post',         // Optional
+  tags: ['tag1', 'tag2'],              // Optional
+  textContent: 'Plain text...',        // Optional (for search)
+  content: {                           // Optional (for rendering)
+    $type: 'site.standard.content.markdown',
+    text: '# My Post\n\nFull markdown...',
+  },
+});
+
+// Publish a publication (your blog itself)
+await publisher.publishPublication({
+  name: 'My Blog',
+  url: 'https://yourblog.com',
+  description: 'Thoughts and writings',
+});
+
+// List, update, delete
+const docs = await publisher.listDocuments();
+await publisher.updateDocument('rkey', { ...updatedData });
+await publisher.deleteDocument('rkey');
+```
+
+### Content Transformation
+
+```ts
+import { 
+  transformPost,      // Full Astro post transformation
+  transformContent,   // Just the markdown body
+  stripToPlainText,   // Extract plain text for textContent
+  convertSidenotes,   // HTML sidenotes → markdown blockquotes
+} from 'astro-standard-site';
+
+// Transform an Astro blog post
+const doc = transformPost(post, { siteUrl: 'https://yourblog.com' });
+
+// Or transform just the content
+const { markdown, textContent, wordCount, readingTime } = transformContent(
+  rawMarkdown,
+  { siteUrl: 'https://yourblog.com' }
+);
+```
+
+#### Sidenote Conversion
+
+Your HTML sidenotes:
+```html
+<div class="sidenote sidenote--tip">
+  <span class="sidenote-label">Tip</span>
+  <p>This is helpful!</p>
+</div>
+```
+
+Become markdown blockquotes:
+```markdown
+> **Tip:** This is helpful!
+```
+
+### Comments
+
+```ts
+import { fetchComments, countComments } from 'astro-standard-site';
+
+// Fetch from a Bluesky post thread
+const comments = await fetchComments({
+  bskyPostUri: 'at://did:plc:xxx/app.bsky.feed.post/abc123',
+  canonicalUrl: 'https://yourblog.com/post',  // Also searches for mentions
+  maxDepth: 3,
+});
+
+console.log(`${countComments(comments)} comments found`);
+
+// Comments are returned as a tree structure
+for (const comment of comments) {
+  console.log(`${comment.author.handle}: ${comment.text}`);
+  for (const reply of comment.replies || []) {
+    console.log(`  ↳ ${reply.author.handle}: ${reply.text}`);
+  }
+}
+```
+
+### Loader (Fetch from ATProto)
+
+```ts
+// src/content/config.ts
+import { defineCollection } from 'astro:content';
+import { standardSiteLoader } from 'astro-standard-site';
+
+// Load documents from any ATProto account
+const externalBlog = defineCollection({
+  loader: standardSiteLoader({ 
+    repo: 'someone.bsky.social',
+    // publication: 'at://...',  // Optional: filter by publication
+    // limit: 50,                 // Optional: max documents
+  }),
+});
+
+export const collections = { externalBlog };
+```
+
+### Verification
+
+```ts
+import { 
+  generatePublicationWellKnown,
+  generateDocumentLinkTag,
+} from 'astro-standard-site';
+
+// For /.well-known/site.standard.publication
+const wellKnown = generatePublicationWellKnown({
+  did: 'did:plc:xxx',
+  publicationRkey: 'my-blog',
+});
+// Returns: "at://did:plc:xxx/site.standard.publication/my-blog"
+
+// For document <head>
+const linkTag = generateDocumentLinkTag({
+  did: 'did:plc:xxx',
+  documentRkey: 'abc123',
+});
+// Returns: '<link rel="site.standard.document" href="at://did:plc:xxx/site.standard.document/abc123">'
+```
+
+## The standard.site Lexicon
+
+This package implements the full [standard.site](https://standard.site) specification:
+
+### `site.standard.publication`
+Represents your blog/publication:
+- `url` (required) — Base URL
+- `name` (required) — Publication name
+- `description` — Brief description
+- `icon` — Square image (256x256+, max 1MB)
+- `basicTheme` — Color theme for platforms
+- `preferences` — Platform-specific settings
+
+### `site.standard.document`
+Represents a blog post:
+- `site` (required) — Publication URL or AT-URI
+- `title` (required) — Post title
+- `publishedAt` (required) — ISO 8601 datetime
+- `path` — URL path (combines with site)
+- `description` — Excerpt/summary
+- `tags` — Array of tags
+- `updatedAt` — Last modified datetime
+- `coverImage` — Hero image (max 1MB)
+- `textContent` — Plain text for search/indexing
+- `content` — Rich content (open union, platform-specific)
+- `bskyPostRef` — Link to Bluesky announcement post
+
+## Workflow: Full Blog Sync
+
+Here's a complete workflow for syncing your Astro blog:
+
+```ts
+// scripts/sync.ts
+import { getCollection } from 'astro:content';
+import { 
+  StandardSitePublisher, 
+  transformPost,
+} from 'astro-standard-site';
+
+async function sync() {
+  const publisher = new StandardSitePublisher({
+    identifier: process.env.ATPROTO_IDENTIFIER!,
+    password: process.env.ATPROTO_APP_PASSWORD!,
+  });
+  
+  await publisher.login();
+  const did = publisher.getDid();
+  
+  // First, ensure publication exists
+  const pubs = await publisher.listPublications();
+  if (pubs.length === 0) {
+    await publisher.publishPublication({
+      name: 'My Blog',
+      url: 'https://myblog.com',
+      description: 'My thoughts and writings',
+      rkey: 'my-blog',
+    });
+  }
+  
+  // Get existing documents
+  const existing = await publisher.listDocuments();
+  const existingByPath = new Map(
+    existing.map(d => [d.value.path, d])
+  );
+  
+  // Sync all posts
+  const posts = await getCollection('blog');
+  
+  for (const post of posts) {
+    if (post.data.draft) continue;
+    
+    const doc = transformPost(post, { siteUrl: 'https://myblog.com' });
+    const existingDoc = existingByPath.get(doc.path);
+    
+    if (existingDoc) {
+      // Update existing
+      const rkey = existingDoc.uri.split('/').pop()!;
+      await publisher.updateDocument(rkey, doc);
+      console.log(`Updated: ${post.slug}`);
+    } else {
+      // Create new
+      const result = await publisher.publishDocument(doc);
+      console.log(`Created: ${post.slug} → ${result.uri}`);
+    }
+  }
+  
+  console.log('Sync complete!');
+}
+
+sync().catch(console.error);
+```
+
+Run with:
+```bash
+ATPROTO_IDENTIFIER="you.bsky.social" \
+ATPROTO_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
+npx tsx scripts/sync.ts
+```
+
+## Resources
+
+- [standard.site specification](https://standard.site)
+- [ATProto documentation](https://atproto.com)
+- [pdsls.dev](https://pdsls.dev) — Browse ATProto repositories
+
+## License
+
+MIT

package/components/Comments.astro

@@ -0,0 +1,330 @@
+---
+/**
+ * Comments component for displaying federated ATProto comments
+ * 
+ * Fetches and displays comments from Bluesky (and future platforms)
+ * for a blog post. Comments are fetched at build time for static sites,
+ * or can be loaded client-side for dynamic updates.
+ * 
+ * @example
+ * ```astro
+ * ---
+ * import Comments from 'astro-standard-site/components/Comments.astro';
+ * ---
+ * 
+ * <Comments 
+ *   bskyPostUri="at://did:plc:xxx/app.bsky.feed.post/abc123"
+ *   canonicalUrl="https://bryanguffey.com/blog/my-post"
+ * />
+ * ```
+ */
+
+import type { Comment } from '../src/comments';
+import { fetchComments, countComments } from '../src/comments';
+
+interface Props {
+  /** AT-URI of the Bluesky announcement post */
+  bskyPostUri?: string;
+  /** Canonical URL of the blog post */
+  canonicalUrl?: string;
+  /** Maximum depth for nested replies */
+  maxDepth?: number;
+  /** Title for the comments section */
+  title?: string;
+  /** Whether to show the "reply on Bluesky" link */
+  showReplyLink?: boolean;
+  /** Custom class for styling */
+  class?: string;
+}
+
+const { 
+  bskyPostUri, 
+  canonicalUrl,
+  maxDepth = 3,
+  title = 'Comments',
+  showReplyLink = true,
+  class: className = '',
+} = Astro.props;
+
+// Fetch comments at build time
+let comments: Comment[] = [];
+let totalCount = 0;
+let error: string | null = null;
+
+try {
+  comments = await fetchComments({
+    bskyPostUri,
+    canonicalUrl,
+    maxDepth,
+  });
+  totalCount = countComments(comments);
+} catch (e) {
+  error = e instanceof Error ? e.message : 'Failed to load comments';
+  console.error('Comments fetch error:', e);
+}
+
+// Helper to format relative time
+function formatRelativeTime(date: Date): string {
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+  
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  
+  return date.toLocaleDateString('en-US', { 
+    month: 'short', 
+    day: 'numeric',
+    year: date.getFullYear() !== now.getFullYear() ? 'numeric' : undefined,
+  });
+}
+
+// Get reply URL for Bluesky
+function getReplyUrl(): string | null {
+  if (!bskyPostUri) return null;
+  
+  // Parse the AT-URI to get handle and post ID
+  const match = bskyPostUri.match(/at:\/\/([^/]+)\/app\.bsky\.feed\.post\/(.+)/);
+  if (!match) return null;
+  
+  const [, did, postId] = match;
+  // For DIDs, we'd need to resolve to handle, but for now use the intent URL
+  return `https://bsky.app/intent/compose?reply=${encodeURIComponent(bskyPostUri)}`;
+}
+
+const replyUrl = getReplyUrl();
+---
+
+<section class:list={['comments-section', className]}>
+  <header class="comments-header">
+    <h2 class="comments-title">
+      {title}
+      {totalCount > 0 && <span class="comments-count">({totalCount})</span>}
+    </h2>
+    
+    {showReplyLink && replyUrl && (
+      <a href={replyUrl} target="_blank" rel="noopener noreferrer" class="comments-reply-link">
+        Reply on Bluesky →
+      </a>
+    )}
+  </header>
+  
+  {error && (
+    <p class="comments-error">
+      Unable to load comments. <a href={bskyPostUri ? `https://bsky.app` : '#'}>View on Bluesky</a>
+    </p>
+  )}
+  
+  {!error && comments.length === 0 && (
+    <p class="comments-empty">
+      No comments yet. 
+      {replyUrl && (
+        <a href={replyUrl} target="_blank" rel="noopener noreferrer">
+          Be the first to reply on Bluesky!
+        </a>
+      )}
+    </p>
+  )}
+  
+  {!error && comments.length > 0 && (
+    <div class="comments-list">
+      {comments.map(function renderComment(comment: Comment, depth = 0) {
+        return (
+          <article class="comment" style={`--depth: ${depth}`}>
+            <header class="comment-header">
+              <a href={`https://bsky.app/profile/${comment.author.handle}`} 
+                 target="_blank" 
+                 rel="noopener noreferrer"
+                 class="comment-author">
+                {comment.author.avatar && (
+                  <img 
+                    src={comment.author.avatar} 
+                    alt="" 
+                    class="comment-avatar"
+                    loading="lazy"
+                  />
+                )}
+                <span class="comment-author-name">
+                  {comment.author.displayName || comment.author.handle}
+                </span>
+                <span class="comment-author-handle">@{comment.author.handle}</span>
+              </a>
+              
+              <a href={comment.sourceUrl} 
+                 target="_blank" 
+                 rel="noopener noreferrer"
+                 class="comment-time">
+                {formatRelativeTime(comment.createdAt)}
+              </a>
+            </header>
+            
+            <div class="comment-body">
+              <p>{comment.text}</p>
+            </div>
+            
+            {comment.likeCount !== undefined && comment.likeCount > 0 && (
+              <footer class="comment-footer">
+                <span class="comment-likes">♥ {comment.likeCount}</span>
+              </footer>
+            )}
+            
+            {comment.replies && comment.replies.length > 0 && (
+              <div class="comment-replies">
+                {comment.replies.map((reply: Comment) => renderComment(reply, depth + 1))}
+              </div>
+            )}
+          </article>
+        );
+      })}
+    </div>
+  )}
+  
+  <footer class="comments-footer">
+    <p class="comments-attribution">
+      Comments powered by <a href="https://bsky.app" target="_blank" rel="noopener noreferrer">Bluesky</a>
+      {' '}via <a href="https://standard.site" target="_blank" rel="noopener noreferrer">standard.site</a>
+    </p>
+  </footer>
+</section>
+
+<style>
+  .comments-section {
+    margin-top: var(--space-2xl, 3rem);
+    padding-top: var(--space-xl, 2rem);
+    border-top: 1px solid var(--color-border-soft, #30363d);
+  }
+  
+  .comments-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: var(--space-lg, 1.5rem);
+    flex-wrap: wrap;
+    gap: var(--space-md, 1rem);
+  }
+  
+  .comments-title {
+    font-size: 1.5rem;
+    margin: 0;
+  }
+  
+  .comments-count {
+    font-weight: normal;
+    color: var(--color-text-muted, #7d8590);
+  }
+  
+  .comments-reply-link {
+    font-size: 0.875rem;
+    color: var(--color-text-link, #7eb8da);
+  }
+  
+  .comments-error,
+  .comments-empty {
+    color: var(--color-text-secondary, #a8b2bd);
+    font-style: italic;
+  }
+  
+  .comments-list {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg, 1.5rem);
+  }
+  
+  .comment {
+    padding-left: calc(var(--depth, 0) * var(--space-lg, 1.5rem));
+  }
+  
+  .comment-header {
+    display: flex;
+    align-items: center;
+    gap: var(--space-md, 1rem);
+    margin-bottom: var(--space-sm, 0.5rem);
+    flex-wrap: wrap;
+  }
+  
+  .comment-author {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm, 0.5rem);
+    text-decoration: none;
+    color: inherit;
+  }
+  
+  .comment-author:hover .comment-author-name {
+    color: var(--color-text-link, #7eb8da);
+  }
+  
+  .comment-avatar {
+    width: 32px;
+    height: 32px;
+    border-radius: 50%;
+    object-fit: cover;
+  }
+  
+  .comment-author-name {
+    font-weight: 600;
+    color: var(--color-text-primary, #e6edf3);
+  }
+  
+  .comment-author-handle {
+    font-size: 0.875rem;
+    color: var(--color-text-muted, #7d8590);
+  }
+  
+  .comment-time {
+    font-size: 0.875rem;
+    color: var(--color-text-muted, #7d8590);
+    margin-left: auto;
+  }
+  
+  .comment-body {
+    color: var(--color-text-secondary, #a8b2bd);
+    line-height: 1.6;
+  }
+  
+  .comment-body p {
+    margin: 0;
+    white-space: pre-wrap;
+  }
+  
+  .comment-footer {
+    margin-top: var(--space-sm, 0.5rem);
+  }
+  
+  .comment-likes {
+    font-size: 0.875rem;
+    color: var(--color-text-muted, #7d8590);
+  }
+  
+  .comment-replies {
+    margin-top: var(--space-md, 1rem);
+    padding-left: var(--space-md, 1rem);
+    border-left: 2px solid var(--color-border-soft, #30363d);
+  }
+  
+  .comments-footer {
+    margin-top: var(--space-xl, 2rem);
+    padding-top: var(--space-md, 1rem);
+    border-top: 1px solid var(--color-border-soft, #30363d);
+  }
+  
+  .comments-attribution {
+    font-size: 0.75rem;
+    color: var(--color-text-muted, #7d8590);
+  }
+  
+  @media (max-width: 640px) {
+    .comment-header {
+      flex-direction: column;
+      align-items: flex-start;
+    }
+    
+    .comment-time {
+      margin-left: 0;
+    }
+  }
+</style>