npm - @prmichaelsen/acp-visualizer - Versions diffs - 0.1.0 - Mend

@prmichaelsen/acp-visualizer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (180) hide show

package/README.md +68 -0
package/agent/commands/acp.clarification-address.md +417 -0
package/agent/commands/acp.clarification-capture.md +386 -0
package/agent/commands/acp.clarification-create.md +437 -0
package/agent/commands/acp.clarifications-research.md +326 -0
package/agent/commands/acp.command-create.md +432 -0
package/agent/commands/acp.design-create.md +286 -0
package/agent/commands/acp.design-reference.md +355 -0
package/agent/commands/acp.handoff.md +270 -0
package/agent/commands/acp.index.md +423 -0
package/agent/commands/acp.init.md +546 -0
package/agent/commands/acp.package-create.md +895 -0
package/agent/commands/acp.package-info.md +212 -0
package/agent/commands/acp.package-install.md +539 -0
package/agent/commands/acp.package-list.md +280 -0
package/agent/commands/acp.package-publish.md +541 -0
package/agent/commands/acp.package-remove.md +293 -0
package/agent/commands/acp.package-search.md +307 -0
package/agent/commands/acp.package-update.md +361 -0
package/agent/commands/acp.package-validate.md +540 -0
package/agent/commands/acp.pattern-create.md +386 -0
package/agent/commands/acp.plan.md +587 -0
package/agent/commands/acp.proceed.md +882 -0
package/agent/commands/acp.project-create.md +675 -0
package/agent/commands/acp.project-info.md +312 -0
package/agent/commands/acp.project-list.md +226 -0
package/agent/commands/acp.project-remove.md +379 -0
package/agent/commands/acp.project-set.md +227 -0
package/agent/commands/acp.project-update.md +307 -0
package/agent/commands/acp.projects-restore.md +228 -0
package/agent/commands/acp.projects-sync.md +347 -0
package/agent/commands/acp.report.md +407 -0
package/agent/commands/acp.resume.md +239 -0
package/agent/commands/acp.sessions.md +301 -0
package/agent/commands/acp.status.md +293 -0
package/agent/commands/acp.sync.md +364 -0
package/agent/commands/acp.task-create.md +500 -0
package/agent/commands/acp.update.md +302 -0
package/agent/commands/acp.validate.md +466 -0
package/agent/commands/acp.version-check-for-updates.md +276 -0
package/agent/commands/acp.version-check.md +191 -0
package/agent/commands/acp.version-update.md +289 -0
package/agent/commands/command.template.md +339 -0
package/agent/commands/git.commit.md +526 -0
package/agent/commands/git.init.md +514 -0
package/agent/commands/tanstack-cloudflare.deploy.md +272 -0
package/agent/commands/tanstack-cloudflare.tail.md +275 -0
package/agent/design/.gitkeep +0 -0
package/agent/design/design.template.md +154 -0
package/agent/design/local.dashboard-layout-routing.md +288 -0
package/agent/design/local.data-model-yaml-parsing.md +310 -0
package/agent/design/local.search-filtering.md +331 -0
package/agent/design/local.server-api-auto-refresh.md +235 -0
package/agent/design/local.table-tree-views.md +299 -0
package/agent/design/local.visualizer-requirements.md +349 -0
package/agent/design/requirements.template.md +387 -0
package/agent/index/.gitkeep +0 -0
package/agent/index/acp.core.yaml +137 -0
package/agent/index/local.main.template.yaml +37 -0
package/agent/manifest.template.yaml +13 -0
package/agent/manifest.yaml +302 -0
package/agent/milestones/.gitkeep +0 -0
package/agent/milestones/milestone-1-project-scaffold-data-pipeline.md +67 -0
package/agent/milestones/milestone-1-{title}.template.md +206 -0
package/agent/milestones/milestone-2-dashboard-views-interaction.md +79 -0
package/agent/package.template.yaml +86 -0
package/agent/patterns/.gitkeep +0 -0
package/agent/patterns/bootstrap.template.md +1237 -0
package/agent/patterns/pattern.template.md +382 -0
package/agent/patterns/tanstack-cloudflare.acl-permissions.md +332 -0
package/agent/patterns/tanstack-cloudflare.action-bar-item.md +416 -0
package/agent/patterns/tanstack-cloudflare.api-route-handlers.md +401 -0
package/agent/patterns/tanstack-cloudflare.auth-session-management.md +387 -0
package/agent/patterns/tanstack-cloudflare.card-and-list.md +271 -0
package/agent/patterns/tanstack-cloudflare.chat-engine.md +353 -0
package/agent/patterns/tanstack-cloudflare.confirmation-tokens.md +346 -0
package/agent/patterns/tanstack-cloudflare.durable-objects-websocket.md +516 -0
package/agent/patterns/tanstack-cloudflare.email-service.md +431 -0
package/agent/patterns/tanstack-cloudflare.expander.md +98 -0
package/agent/patterns/tanstack-cloudflare.fcm-push.md +115 -0
package/agent/patterns/tanstack-cloudflare.firebase-anonymous-sessions.md +441 -0
package/agent/patterns/tanstack-cloudflare.firebase-auth.md +348 -0
package/agent/patterns/tanstack-cloudflare.firebase-firestore.md +550 -0
package/agent/patterns/tanstack-cloudflare.firebase-storage.md +369 -0
package/agent/patterns/tanstack-cloudflare.form-controls.md +145 -0
package/agent/patterns/tanstack-cloudflare.global-search-context.md +93 -0
package/agent/patterns/tanstack-cloudflare.image-carousel.md +126 -0
package/agent/patterns/tanstack-cloudflare.library-services.md +553 -0
package/agent/patterns/tanstack-cloudflare.lightbox.md +169 -0
package/agent/patterns/tanstack-cloudflare.markdown-content.md +115 -0
package/agent/patterns/tanstack-cloudflare.mention-suggestions.md +98 -0
package/agent/patterns/tanstack-cloudflare.modal.md +156 -0
package/agent/patterns/tanstack-cloudflare.nextjs-to-tanstack-routing.md +461 -0
package/agent/patterns/tanstack-cloudflare.notifications-engine.md +151 -0
package/agent/patterns/tanstack-cloudflare.oauth-token-refresh.md +90 -0
package/agent/patterns/tanstack-cloudflare.og-metadata.md +296 -0
package/agent/patterns/tanstack-cloudflare.pagination.md +442 -0
package/agent/patterns/tanstack-cloudflare.pill-input.md +220 -0
package/agent/patterns/tanstack-cloudflare.provider-adapter.md +401 -0
package/agent/patterns/tanstack-cloudflare.rate-limiting.md +323 -0
package/agent/patterns/tanstack-cloudflare.scheduled-tasks.md +338 -0
package/agent/patterns/tanstack-cloudflare.searchable-settings.md +375 -0
package/agent/patterns/tanstack-cloudflare.slide-over.md +129 -0
package/agent/patterns/tanstack-cloudflare.ssr-preload.md +571 -0
package/agent/patterns/tanstack-cloudflare.third-party-api-integration.md +508 -0
package/agent/patterns/tanstack-cloudflare.toast-system.md +142 -0
package/agent/patterns/tanstack-cloudflare.unified-header.md +280 -0
package/agent/patterns/tanstack-cloudflare.user-scoped-collections.md +628 -0
package/agent/patterns/tanstack-cloudflare.websocket-manager.md +237 -0
package/agent/patterns/tanstack-cloudflare.wrangler-configuration.md +358 -0
package/agent/patterns/tanstack-cloudflare.zod-schema-validation.md +336 -0
package/agent/progress.template.yaml +161 -0
package/agent/progress.yaml +145 -0
package/agent/schemas/package.schema.yaml +276 -0
package/agent/scripts/acp.common.sh +1781 -0
package/agent/scripts/acp.install.sh +333 -0
package/agent/scripts/acp.package-create.sh +924 -0
package/agent/scripts/acp.package-info.sh +288 -0
package/agent/scripts/acp.package-install.sh +893 -0
package/agent/scripts/acp.package-list.sh +311 -0
package/agent/scripts/acp.package-publish.sh +420 -0
package/agent/scripts/acp.package-remove.sh +348 -0
package/agent/scripts/acp.package-search.sh +156 -0
package/agent/scripts/acp.package-update.sh +517 -0
package/agent/scripts/acp.package-validate.sh +1018 -0
package/agent/scripts/acp.uninstall.sh +85 -0
package/agent/scripts/acp.version-check-for-updates.sh +98 -0
package/agent/scripts/acp.version-check.sh +47 -0
package/agent/scripts/acp.version-update.sh +176 -0
package/agent/scripts/acp.yaml-parser.sh +985 -0
package/agent/scripts/acp.yaml-validate.sh +205 -0
package/agent/tasks/.gitkeep +0 -0
package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-1-initialize-tanstack-start-project.md +210 -0
package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-2-implement-data-model-yaml-parser.md +294 -0
package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-3-build-server-api-data-loading.md +193 -0
package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-4-add-auto-refresh-sse.md +262 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-10-polish-integration-testing.md +156 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-5-build-dashboard-layout-routing.md +178 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-6-build-overview-page.md +141 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-7-implement-milestone-table-view.md +153 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-8-implement-milestone-tree-view.md +174 -0
package/agent/tasks/milestone-2-dashboard-views-interaction/task-9-implement-search-filtering.md +233 -0
package/agent/tasks/task-1-{title}.template.md +244 -0
package/bin/visualize.mjs +84 -0
package/package.json +48 -0
package/src/components/ExtraFieldsBadge.tsx +15 -0
package/src/components/FilterBar.tsx +33 -0
package/src/components/Header.tsx +23 -0
package/src/components/MilestoneTable.tsx +167 -0
package/src/components/MilestoneTree.tsx +84 -0
package/src/components/ProgressBar.tsx +20 -0
package/src/components/SearchInput.tsx +22 -0
package/src/components/Sidebar.tsx +54 -0
package/src/components/StatusBadge.tsx +23 -0
package/src/components/StatusDot.tsx +12 -0
package/src/components/TaskList.tsx +36 -0
package/src/components/ViewToggle.tsx +31 -0
package/src/lib/config.ts +8 -0
package/src/lib/file-watcher.ts +43 -0
package/src/lib/search.ts +48 -0
package/src/lib/types.ts +73 -0
package/src/lib/useAutoRefresh.ts +31 -0
package/src/lib/useCollapse.ts +31 -0
package/src/lib/useFilteredData.ts +55 -0
package/src/lib/yaml-loader-real.spec.ts +47 -0
package/src/lib/yaml-loader.spec.ts +201 -0
package/src/lib/yaml-loader.ts +265 -0
package/src/routeTree.gen.ts +140 -0
package/src/router.tsx +10 -0
package/src/routes/__root.tsx +75 -0
package/src/routes/api/watch.ts +29 -0
package/src/routes/index.tsx +115 -0
package/src/routes/milestones.tsx +50 -0
package/src/routes/search.tsx +84 -0
package/src/routes/tasks.tsx +63 -0
package/src/services/progress-database.service.ts +46 -0
package/src/styles.css +25 -0
package/tsconfig.json +24 -0
package/vite.config.ts +16 -0
package/vitest.config.ts +27 -0

package/agent/patterns/tanstack-cloudflare.og-metadata.md ADDED Viewed

@@ -0,0 +1,296 @@
+# OG Metadata Pattern
+**Category**: Code
+**Applicable To**: TanStack Start routes that need social media link previews (Open Graph + Twitter Cards)
+**Status**: Stable
+---
+## Overview
+Every route that can be shared on social media (iMessage, Slack, Discord, Twitter/X, Facebook) needs server-rendered Open Graph and Twitter Card meta tags in the HTML `<head>`. TanStack Start provides a `head()` function on route definitions that runs during SSR — this is the only mechanism that works for social crawlers, which do not execute JavaScript.
+This pattern documents how to add OG metadata to routes, covering static pages, dynamic content pages with SSR loader data, and the global defaults that all routes inherit.
+---
+## When to Use This Pattern
+**Use this pattern when:**
+- Adding a new route that users might share (link previews)
+- Adding SSR data to a route that already has OG tags
+- Creating shareable content pages (memories, profiles, invite links)
+- Debugging why a shared link shows the wrong preview
+**Don't use this pattern when:**
+- The route is behind authentication with no public preview needed
+- The route is an API endpoint (`/api/*`)
+---
+## Core Principles
+1. **SSR-Only**: Social crawlers don't run JS — `head()` runs server-side so tags appear in the initial HTML response
+2. **Route-Level Overrides**: Child route `head()` tags override parent (root) defaults by property
+3. **Graceful Fallback**: If loader data fails, return generic site-level OG tags — never render a page with no OG
+4. **Auth After Meta**: For shareable links (invite codes), check auth in the component, not `beforeLoad`, so crawlers see meta tags without being redirected
+---
+## Implementation
+### Global Defaults (Root Route)
+`src/routes/__root.tsx` defines site-wide fallback OG tags via `createRootRoute({ head() })`:
+```typescript
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1, ...' },
+      { title: 'agentbase — social AI with memory, ghosts, and shared spaces' },
+      { name: 'description', content: 'A social AI platform with persistent memory...' },
+      { property: 'og:type', content: 'website' },
+      { property: 'og:site_name', content: 'agentbase' },
+      { property: 'og:title', content: 'agentbase — social AI with memory, ghosts, and shared spaces' },
+      { property: 'og:description', content: 'A social AI platform with persistent memory...' },
+      { property: 'og:image', content: 'https://agentbase.me/icon-512x512.png' },
+      { name: 'twitter:card', content: 'summary_large_image' },
+      { name: 'twitter:title', content: 'agentbase — ...' },
+      { name: 'twitter:description', content: '...' },
+      { name: 'twitter:image', content: 'https://agentbase.me/icon-512x512.png' },
+    ],
+  }),
+  component: RootComponent,
+})
+```
+The root also renders `<HeadContent />` inside `<head>` to inject these tags into the HTML.
+### Static Page OG
+For pages with fixed content (terms, privacy, homepage, invite links):
+```typescript
+export const Route = createFileRoute('/terms')({
+  head: () => ({
+    meta: [
+      { title: 'Terms of Service — agentbase' },
+      { name: 'description', content: 'Terms of service for agentbase.' },
+      { property: 'og:title', content: 'Terms of Service — agentbase' },
+      { property: 'og:description', content: 'Terms of service for agentbase.' },
+      { property: 'og:type', content: 'website' },
+      { property: 'og:site_name', content: 'agentbase' },
+      { property: 'og:image', content: 'https://agentbase.me/icon-512x512.png' },
+      { name: 'twitter:card', content: 'summary' },
+      { name: 'twitter:title', content: 'Terms of Service — agentbase' },
+      { name: 'twitter:description', content: 'Terms of service for agentbase.' },
+      { name: 'twitter:image', content: 'https://agentbase.me/icon-512x512.png' },
+    ],
+  }),
+  component: TermsPage,
+})
+```
+### Dynamic Content OG (SSR Loader)
+For pages where OG tags depend on data (memory detail, profile), use `createServerFn` + `loader` + `head(loaderData)`:
+```typescript
+// 1. Server function fetches data during SSR
+const fetchMemoryDetail = createServerFn({ method: 'GET' })
+  .inputValidator((data: { memoryId: string }) => data)
+  .handler(async ({ data }) => {
+    // Fetch memory from backend
+    const memory = await svc.memories.get(userId, data.memoryId)
+    return { memory }
+  })
+// 2. Route loader calls server function
+export const Route = createFileRoute('/memories/$memoryId')({
+  loader: async ({ params }) => {
+    const memoryData = await fetchMemoryDetail({ data: { memoryId: params.memoryId } })
+    return { memoryData }
+  },
+  // 3. head() receives loader data and generates dynamic tags
+  head: (({ loaderData }: any) => {
+    const memory = loaderData?.memoryData?.memory
+    if (!memory) {
+      return {
+        meta: [
+          { title: 'Memory — agentbase' },
+          { property: 'og:title', content: 'Memory — agentbase' },
+          { property: 'og:image', content: 'https://agentbase.me/icon-512x512.png' },
+          // ... fallback tags
+        ],
+      }
+    }
+    const rawTitle = memory.title || memory.content?.split('\n')[0] || 'Memory'
+    const title = rawTitle.length > 60 ? rawTitle.substring(0, 57) + '...' : rawTitle
+    const description = (memory.content ?? '').substring(0, 200)
+    return {
+      meta: [
+        { title: `${title} — agentbase` },
+        { name: 'description', content: description },
+        { property: 'og:title', content: title },
+        { property: 'og:description', content: description },
+        { property: 'og:type', content: 'article' },
+        { property: 'og:site_name', content: 'agentbase' },
+        { property: 'og:image', content: 'https://agentbase.me/icon-512x512.png' },
+        { name: 'twitter:card', content: 'summary' },
+        { name: 'twitter:title', content: title },
+        { name: 'twitter:description', content: description },
+        { name: 'twitter:image', content: 'https://agentbase.me/icon-512x512.png' },
+      ],
+    }
+  }) as any,
+  component: MemoryDetailPage,
+})
+```
+### Dynamic OG Image (Profile Pages)
+Profile pages use the `/api/storage/image` proxy to serve user-uploaded profile pictures as OG images:
+```typescript
+head: (({ loaderData }: any) => {
+  const profile = loaderData?.profileForHead
+  if (profile && profile.is_published) {
+    const image = profile.profile_picture_path
+      ? `https://agentbase.me/api/storage/image?path=${encodeURIComponent(profile.profile_picture_path)}&context=profile`
+      : 'https://agentbase.me/icon-512x512.png'
+    return {
+      meta: [
+        { property: 'og:image', content: image },
+        { name: 'twitter:image', content: image },
+        // ... other tags
+      ],
+    }
+  }
+  // fallback for unpublished profiles
+}) as any
+```
+### Shareable Invite Links (Auth After Meta)
+For pages like `/friend-links/$code`, `/group-links/$code`, `/dm-links/$code` — use **static OG** and defer auth to the component:
+```typescript
+export const Route = createFileRoute('/friend-links/$code')({
+  // Static head — no loader needed, crawlers see this immediately
+  head: () => ({
+    meta: [
+      { title: 'Friend Invite — agentbase' },
+      { property: 'og:title', content: 'Friend Invite — agentbase' },
+      { property: 'og:description', content: "You've been invited to connect on agentbase." },
+      // ...
+    ],
+  }),
+  // Auth check happens HERE, not in beforeLoad — crawlers never hit this
+  component: FriendLinkPage,
+})
+```
+---
+## Required Meta Tags Checklist
+Every route with OG metadata should include all of these:
+| Tag | Property | Notes |
+|-----|----------|-------|
+| `<title>` | `{ title: '...' }` | Browser tab title |
+| `description` | `{ name: 'description', content: '...' }` | Search engine description |
+| `og:title` | `{ property: 'og:title', content: '...' }` | Social card title |
+| `og:description` | `{ property: 'og:description', content: '...' }` | Social card description |
+| `og:type` | `{ property: 'og:type', content: '...' }` | `website` or `article` |
+| `og:site_name` | `{ property: 'og:site_name', content: 'agentbase' }` | Always `agentbase` |
+| `og:image` | `{ property: 'og:image', content: '...' }` | Absolute URL, min 200x200 |
+| `twitter:card` | `{ name: 'twitter:card', content: '...' }` | `summary` or `summary_large_image` |
+| `twitter:title` | `{ name: 'twitter:title', content: '...' }` | Same as `og:title` |
+| `twitter:description` | `{ name: 'twitter:description', content: '...' }` | Same as `og:description` |
+| `twitter:image` | `{ name: 'twitter:image', content: '...' }` | Same as `og:image` |
+---
+## OG Type Reference
+| Route Type | `og:type` | `twitter:card` |
+|------------|-----------|----------------|
+| Homepage / static pages | `website` | `summary_large_image` |
+| Memory detail | `article` | `summary` |
+| Profile page | `profile` | `summary` |
+| Space / group pages | `website` | `summary` |
+| Invite links | `website` | `summary` |
+---
+## Anti-Patterns
+### Auth in beforeLoad for shareable pages
+**Description**: Redirecting unauthenticated users in `beforeLoad` before `head()` runs.
+**Why it's bad**: Social crawlers are unauthenticated — they get redirected to login and never see OG tags.
+**Instead**: Check auth in the component, not `beforeLoad`. The `head()` function runs regardless.
+### Missing fallback when loader fails
+**Description**: Not handling the case where `loaderData` is undefined in `head()`.
+**Why it's bad**: A failed fetch produces a page with no OG tags — shared links show a blank preview.
+**Instead**: Always return fallback OG tags when data is missing.
+### Relative OG image URLs
+**Description**: Using `/icon-512x512.png` instead of `https://agentbase.me/icon-512x512.png`.
+**Why it's bad**: Some social crawlers don't resolve relative URLs.
+**Instead**: Always use absolute URLs for `og:image` and `twitter:image`.
+---
+## Implementation References
+- **Root defaults**: `src/routes/__root.tsx` (lines 56-108)
+- **Memory detail (dynamic)**: `src/routes/memories/$memoryId.tsx` (lines 131-160)
+- **Profile (dynamic image)**: `src/routes/profile/$userId.tsx` (lines 90-127)
+- **Spaces (conditional image)**: `src/routes/spaces/$spaceId.tsx` (lines 41-53)
+- **Invite links (static, auth-deferred)**: `src/routes/friend-links/$code.tsx` (lines 15-29)
+- **Image proxy**: `src/routes/api/storage/image.tsx`
+- **Static assets**: `public/icon-512x512.png`, `public/the_void_02-512.png`
+## Related Patterns
+- **[SSR Preload](./ssr-preload.md)**: Server-side data loading that feeds into `head()` for dynamic OG
+- **[Firebase Auth](./tanstack-cloudflare.firebase-auth.md)**: Auth patterns — important to understand which routes gate auth in `beforeLoad` vs component
+- **[Firebase Storage](./tanstack-cloudflare.firebase-storage.md)**: Image proxy endpoint used for dynamic OG images
+---
+## Checklist for Implementation
+- [ ] `head()` function defined on route with all required meta tags
+- [ ] `og:image` and `twitter:image` use absolute URLs
+- [ ] Dynamic pages have server function + loader feeding `head(loaderData)`
+- [ ] `head()` handles missing/failed loader data with fallback tags
+- [ ] Shareable pages defer auth to component (not `beforeLoad`)
+- [ ] Title truncated to 60 chars max, description to 200 chars max
+- [ ] `og:type` is appropriate (`website` vs `article` vs `profile`)
+- [ ] `og:site_name` is `agentbase`
+---
+**Status**: Stable
+**Recommendation**: Follow this pattern for every new route. Verify OG tags by pasting the URL into the Twitter Card Validator or Facebook Sharing Debugger.
+**Last Updated**: 2026-03-14
+**Contributors**: Community