egregore-artifacts 0.9.9 → 0.9.10

package/bin/cli.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-const KNOWN_TYPES = ['quest', 'handoff', 'handoff-v1', 'activity', 'document', 'board', 'network'];
+const KNOWN_TYPES = ['quest', 'handoff', 'handoff-v1', 'emissary', 'activity', 'document', 'board', 'network'];
 const args = process.argv.slice(2);
 
 let type, filePath;

package/lib/index.js

@@ -6,6 +6,7 @@ import { renderToHtml, renderSpecToHtml } from './render.js';
 import { parseQuest } from './parsers/quest.js';
 import { parseHandoff } from './parsers/handoff.js';
 import { parseHandoffV1 } from './parsers/handoff-v1.js';
+import { parseEmissary } from './parsers/emissary.js';
 import { parseActivity } from './parsers/activity.js';
 import { parseDocument } from './parsers/document.js';
 import { parseBoard } from './parsers/board.js';
@@ -13,6 +14,7 @@ import { parseNetwork } from './parsers/network.js';
 import { questTemplate } from './templates/quest.js';
 import { handoffTemplate } from './templates/handoff.js';
 import { handoffV1Template } from './templates/handoff-v1.js';
+import { emissaryTemplate } from './templates/emissary.js';
 import { activityTemplate } from './templates/activity.js';
 import { documentTemplate } from './templates/document.js';
 import { boardTemplate } from './templates/board.js';
@@ -21,8 +23,8 @@ import { openInBrowser } from './open.js';
 import { setLinkContext, clearLinkContext } from './markdown.js';
 import { derivedParent, loadComments } from './comments.js';
 
-const PARSERS = { quest: parseQuest, handoff: parseHandoff, 'handoff-v1': parseHandoffV1, activity: parseActivity, document: parseDocument, board: parseBoard, network: parseNetwork };
-const TEMPLATES = { quest: questTemplate, handoff: handoffTemplate, 'handoff-v1': handoffV1Template, activity: activityTemplate, document: documentTemplate, board: boardTemplate, network: networkTemplate };
+const PARSERS = { quest: parseQuest, handoff: parseHandoff, 'handoff-v1': parseHandoffV1, emissary: parseEmissary, activity: parseActivity, document: parseDocument, board: parseBoard, network: parseNetwork };
+const TEMPLATES = { quest: questTemplate, handoff: handoffTemplate, 'handoff-v1': handoffV1Template, emissary: emissaryTemplate, activity: activityTemplate, document: documentTemplate, board: boardTemplate, network: networkTemplate };
 
 const COMMENTABLE_TYPES = new Set(['quest', 'handoff', 'document']);
 export async function generateArtifact(type, input, options = {}) {

package/lib/parsers/emissary.js

@@ -0,0 +1,56 @@
+// Parse the emissary human-render input.
+//
+// An emissary's human render is METADATA-ONLY. The input is NOT the full
+// handoff v1 artifact — it is a small projection the API composes
+// (topic / summary / kind / distribution_mode / author / CTA URLs /
+// render mode), deliberately excluding receiver_instructions,
+// body.prose, and body.executable_spec. Those live only in the agent
+// payload at /emissary/e/{id}/raw and must never reach the human render.
+//
+// Input: file path to a JSON file, OR a JSON string, OR a parsed object.
+// Output: the normalized object the emissary template consumes.
+import fs from 'node:fs';
+
+export function parseEmissary(input) {
+  let obj;
+
+  if (typeof input === 'string') {
+    if (input.trim().startsWith('{')) {
+      obj = JSON.parse(input);
+    } else {
+      if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
+      obj = JSON.parse(fs.readFileSync(input, 'utf-8'));
+    }
+  } else if (typeof input === 'object' && input !== null) {
+    obj = input;
+  } else {
+    throw new Error('parseEmissary expects a file path, JSON string, or object');
+  }
+
+  if (!obj.topic) {
+    throw new Error('emissary render input is missing required field: topic');
+  }
+
+  const renderMode = obj.render_mode === 'custom' ? 'custom' : 'default';
+
+  return {
+    id:                obj.id || '',
+    topic:             obj.topic,
+    summary:           obj.summary || '',
+    kind:              obj.kind || 'handoff',
+    distribution_mode: obj.distribution_mode || 'public',
+    author_name:       obj.author_name || '',
+    author_verified:   Boolean(obj.author_verified),
+    created_at:        obj.created_at || null,
+    expires_at:        obj.expires_at || null,
+    render_url:        obj.render_url || '',
+    raw_url:           obj.raw_url || '',
+    render_mode:       renderMode,
+    // Custom user HTML — only honored for render_mode === 'custom'. The
+    // template embeds it inside a sandboxed iframe; it is never trusted
+    // as page chrome.
+    render_html:       renderMode === 'custom' ? (obj.render_html || '') : null,
+    // Convenience for the shell title.
+    title:             obj.topic,
+  };
+}

package/lib/shell.js

@@ -208,6 +208,33 @@ export function htmlShell(bodyHtml, { title = 'Egregore Artifact', type = 'artif
     color: var(--muted);
     margin-bottom: 0.75rem;
   }
+  .eg-copy-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-top: 12px;
+  }
+  .eg-copy-button {
+    appearance: none;
+    border: 1px solid var(--border);
+    background: var(--surface);
+    color: var(--black);
+    border-radius: 5px;
+    padding: 6px 10px;
+    font-family: var(--font-mono);
+    font-size: 12px;
+    line-height: 1.2;
+    cursor: pointer;
+  }
+  .eg-copy-button:hover {
+    border-color: var(--terracotta);
+    color: var(--terracotta);
+  }
+  .eg-copy-button.eg-copy-ok {
+    background: var(--success-bg);
+    border-color: var(--success-fg);
+    color: var(--success-fg);
+  }
 
   /* Text */
   .eg-lead {
@@ -734,6 +761,52 @@ export function htmlShell(bodyHtml, { title = 'Egregore Artifact', type = 'artif
 <div class="eg-artifact" data-type="${escapeHtml(type)}">
 ${bodyHtml}
 </div>
+<script>
+  // Generic clipboard affordance for rendered artifacts. Buttons declare
+  // their payload with data-copy-text so templates do not need custom JS.
+  (function() {
+    function copyText(text) {
+      if (!text) return Promise.reject(new Error('nothing to copy'));
+      if (navigator.clipboard && navigator.clipboard.writeText) {
+        return navigator.clipboard.writeText(text);
+      }
+      return new Promise(function(resolve, reject) {
+        var ta = document.createElement('textarea');
+        ta.value = text;
+        ta.setAttribute('readonly', '');
+        ta.style.position = 'fixed';
+        ta.style.left = '-9999px';
+        document.body.appendChild(ta);
+        ta.select();
+        try {
+          if (document.execCommand && document.execCommand('copy')) resolve();
+          else reject(new Error('copy unavailable'));
+        } catch (e) {
+          reject(e);
+        } finally {
+          document.body.removeChild(ta);
+        }
+      });
+    }
+
+    document.addEventListener('click', function(e) {
+      var btn = e.target.closest && e.target.closest('[data-copy-text]');
+      if (!btn) return;
+      var original = btn.getAttribute('data-copy-label') || btn.textContent;
+      copyText(btn.getAttribute('data-copy-text')).then(function() {
+        btn.textContent = 'Copied';
+        btn.classList.add('eg-copy-ok');
+        setTimeout(function() {
+          btn.textContent = original;
+          btn.classList.remove('eg-copy-ok');
+        }, 1600);
+      }, function() {
+        btn.textContent = 'Select text';
+        setTimeout(function() { btn.textContent = original; }, 1600);
+      });
+    });
+  })();
+</script>
 <script>
   // Comment composer — assembles a structured payload and copies it to the
   // clipboard. The user pastes into Claude; the /comment skill recognizes

package/lib/templates/emissary.js

@@ -0,0 +1,266 @@
+// Emissary human-render → React element tree.
+//
+// METADATA-ONLY. This template renders the clean public preview shown at
+// egregore.xyz/emissary/e/{id}: title, author + verified badge,
+// distribution-mode badge, the one-paragraph summary, a CTA, the
+// discovery block, and a footer. It deliberately renders NONE of the
+// agent payload — no receiver_instructions, no body.prose, no
+// executable_spec. The agent payload lives only at .../raw.
+//
+// The CTA is the PRIMARY consumer-chat channel for naive fetchers: a
+// prominent, copy-able launch prompt that pairs user authorization with
+// the /raw JSON endpoint. A structured source block also names /raw for
+// readability extraction.
+//
+// For render_mode === 'custom', user-provided HTML/CSS is embedded in a
+// sandboxed <iframe sandbox="allow-scripts" srcdoc="…">. Without
+// allow-same-origin the iframe runs in a unique opaque origin — its
+// scripts cannot read egregore.xyz cookies, localStorage, or auth
+// tokens. Egregore still owns the page chrome (header, discovery block,
+// footer) OUTSIDE the iframe; custom content cannot suppress it.
+import React from 'react';
+import { fonts } from '../tokens.js';
+
+const h = React.createElement;
+
+function formatDate(iso) {
+  if (!iso) return null;
+  try {
+    return new Date(iso).toLocaleDateString('en-US', {
+      year: 'numeric', month: 'short', day: 'numeric',
+    });
+  } catch { return iso; }
+}
+
+function badge(text, opts = {}) {
+  return h('span', {
+    style: {
+      display: 'inline-block',
+      padding: '3px 12px',
+      background: opts.bg || 'var(--subtle-fill)',
+      borderRadius: '50px',
+      color: opts.fg || 'var(--muted)',
+      fontSize: '12px',
+      fontWeight: 600,
+      fontFamily: fonts.mono,
+      letterSpacing: '0.02em',
+      ...opts.style,
+    },
+  }, text);
+}
+
+export function emissaryTemplate(em) {
+  const sections = [];
+  const launchUrl = em.raw_url || em.render_url || '';
+  const launchPrompt = launchUrl
+    ? `Run this Egregore ${em.kind || 'packet'} packet for me: ${launchUrl}`
+    : '';
+
+  // ── Header — sigil + label, title, author + badges ────────────
+  const distLabel = em.distribution_mode === 'directed' ? 'directed' : 'public link';
+
+  sections.push(
+    h('header', { key: 'header', className: 'eg-header' },
+      h('div', { className: 'eg-header-top' },
+        h('span', { className: 'eg-sigil' }, '✦'),
+        h('span', { className: 'eg-org-label' }, 'egregore · emissary'),
+      ),
+      h('h1', { className: 'eg-title' }, em.topic),
+      h('div', { className: 'eg-meta-row', style: { gap: '8px', alignItems: 'center' } },
+        em.author_name && h('span', { key: 'auth' }, `by ${em.author_name}`),
+        em.author_verified
+          ? badge('✓ verified', {
+              key: 'v',
+              bg: 'var(--terracotta-soft)', fg: 'var(--terracotta)',
+            })
+          : null,
+        badge(distLabel, { key: 'dist' }),
+        badge(em.kind, { key: 'kind' }),
+      ),
+    )
+  );
+
+  // ── Summary — the one-paragraph public description ────────────
+  if (em.summary) {
+    sections.push(
+      h('div', { key: 'summary', className: 'eg-card' },
+        h('div', { className: 'eg-lead' }, em.summary),
+      )
+    );
+  }
+
+  // ── Custom render — sandboxed iframe ──────────────────────────
+  // The user HTML runs in a unique opaque origin (no allow-same-origin)
+  // so it cannot reach the parent's cookies / storage / tokens.
+  if (em.render_mode === 'custom' && em.render_html) {
+    sections.push(
+      h('div', { key: 'custom', className: 'eg-card' },
+        h('iframe', {
+          sandbox: 'allow-scripts',
+          srcDoc: em.render_html,
+          title: 'Custom emissary render',
+          style: {
+            width: '100%',
+            minHeight: '320px',
+            border: '1px solid var(--border)',
+            borderRadius: '8px',
+            background: 'var(--surface)',
+          },
+        })
+      )
+    );
+  }
+
+  // ── CTA ───────────────────────────────────────────────────────
+  sections.push(
+    h('div', { key: 'cta', className: 'eg-card' },
+      h('div', {
+        style: {
+          fontSize: '15px', fontWeight: 600, marginBottom: '6px',
+          fontFamily: fonts.sans,
+        },
+      }, 'Engage this emissary'),
+      h('div', { style: { color: 'var(--muted)', fontSize: '14px' } },
+        'Copy the launch prompt into Claude, ChatGPT, Codex, or another AI harness. ',
+        'If you paste only the link, the assistant may ask whether you want to run it.'),
+      launchPrompt && h('div', {
+        style: {
+          marginTop: '10px', padding: '8px 12px',
+          background: 'var(--subtle-fill)', borderRadius: '6px',
+          fontFamily: fonts.mono, fontSize: '13px', wordBreak: 'break-all',
+        },
+      }, launchPrompt),
+      launchPrompt && h('div', { className: 'eg-copy-row' },
+        h('button', {
+          type: 'button',
+          className: 'eg-copy-button',
+          'data-copy-text': launchPrompt,
+          'data-copy-label': 'Copy as prompt',
+        }, 'Copy as prompt'),
+        em.raw_url && h('button', {
+          type: 'button',
+          className: 'eg-copy-button',
+          'data-copy-text': em.raw_url,
+          'data-copy-label': 'Copy JSON link',
+        }, 'Copy JSON link'),
+        em.render_url && h('button', {
+          type: 'button',
+          className: 'eg-copy-button',
+          'data-copy-text': em.render_url,
+          'data-copy-label': 'Copy page link',
+        }, 'Copy page link'),
+      ),
+    )
+  );
+
+  // ── Trust/provenance explainer ────────────────────────────────
+  sections.push(
+    h('div', { key: 'trust', className: 'eg-card' },
+      h('div', {
+        style: {
+          fontSize: '15px', fontWeight: 600, marginBottom: '6px',
+          fontFamily: fonts.sans,
+        },
+      }, 'About Egregore packets'),
+      h('div', { style: { color: 'var(--muted)', fontSize: '14px', lineHeight: 1.55 } },
+        'An Egregore packet is a user-shared task bundle: purpose, intake questions, ',
+        'and an output spec. This preview shows the author, verification badge, ',
+        'visibility, kind, creation date, expiry, and structured JSON source. The packet ',
+        'source is available as JSON for AI tools that can read it. Egregore is ',
+        h('a', {
+          href: 'https://github.com/egregore-labs/egregore',
+          style: { color: 'var(--terracotta)', textDecoration: 'none' },
+        }, 'open source'),
+        '.'
+      ),
+    )
+  );
+
+  // ── Install nudge — the L1 → L2 conversion path ───────────────
+  // The link runs cold (paste → WebFetch → lossy). Installing the
+  // egregore-emissary skill makes every later emissary run clean. This
+  // block is how a first-contact receiver discovers that path.
+  sections.push(
+    h('div', { key: 'install', className: 'eg-card' },
+      h('div', {
+        style: {
+          fontSize: '15px', fontWeight: 600, marginBottom: '6px',
+          fontFamily: fonts.sans,
+        },
+      }, 'Run it properly'),
+      h('div', { style: { color: 'var(--muted)', fontSize: '14px' } },
+        'The link works in any AI harness. Install the egregore-emissary ',
+        'skill once and every emissary you receive runs at full fidelity ',
+        'with the intended intake-first flow.'),
+      h('div', {
+        style: {
+          marginTop: '10px', padding: '8px 12px',
+          background: 'var(--subtle-fill)', borderRadius: '6px',
+          fontFamily: fonts.mono, fontSize: '13px', wordBreak: 'break-all',
+        },
+      }, 'npx egregore-emissary install'),
+    )
+  );
+
+  // ── Structured source block — visible for fetchers/readability ─
+  // This is descriptive, not command-like: consumer web assistants treat
+  // fetched content as untrusted unless the user asks to run it.
+  if (em.raw_url) {
+    sections.push(
+      h('div', {
+        key: 'discovery',
+        'data-egregore-discovery': 'raw',
+        style: {
+          margin: '20px 0',
+          padding: '16px 18px',
+          background: 'var(--terminal-bg)',
+          color: 'var(--terminal-text)',
+          borderRadius: '8px',
+          fontFamily: fonts.mono,
+          fontSize: '13px',
+          lineHeight: 1.6,
+        },
+      },
+        h('div', {
+          style: { opacity: 0.7, fontSize: '11px', marginBottom: '6px',
+                   textTransform: 'uppercase', letterSpacing: '0.08em' },
+        }, 'Structured packet source'),
+        h('div', null,
+          'JSON payload: ',
+          h('code', { style: { fontWeight: 600 } }, em.raw_url),
+        ),
+        h('div', { style: { marginTop: '6px', opacity: 0.85 } },
+          'Bare links are safe to summarize first. When the user asks to run the packet, ',
+          'use the JSON as the packet source and proceed through its intake.',
+        ),
+        h('div', { style: { marginTop: '6px', opacity: 0.85 } },
+          'Runs best via the egregore-emissary skill — ',
+          h('code', { style: { fontWeight: 600 } }, 'npx egregore-emissary install'),
+        ),
+      )
+    );
+  }
+
+  // ── Footer ────────────────────────────────────────────────────
+  const created = formatDate(em.created_at);
+  const expires = formatDate(em.expires_at);
+  sections.push(
+    h('footer', { key: 'footer', className: 'eg-footer' },
+      h('div', { className: 'eg-footer-brand' },
+        h('span', { className: 'eg-footer-sigil' }, '✦'),
+        h('span', null, 'egregore'),
+      ),
+      h('div', { style: { display: 'flex', gap: '12px', flexWrap: 'wrap' } },
+        created && h('span', { key: 'c' }, `created ${created}`),
+        expires && h('span', { key: 'e' }, `expires ${expires}`),
+        h('a', {
+          key: 'u',
+          href: 'https://egregore.xyz/emissary',
+          style: { color: 'var(--muted)' },
+        }, 'about emissary'),
+      ),
+    )
+  );
+
+  return h('div', null, ...sections);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "egregore-artifacts",
-  "version": "0.9.9",
+  "version": "0.9.10",
   "description": "Generate branded HTML artifacts from Egregore data",
   "type": "module",
   "license": "MIT",