slingit 0.1.1 → 0.2.1

package/README.md

@@ -26,6 +26,12 @@ npx slingit shot analysis.md --public
 # Delete after 7 days
 npx slingit shot analysis.md --expire 7
 
+# Load a note back — prints its Markdown to stdout (decrypts locally, key from #)
+npx slingit pull https://slingit.dev/aX7k2mQp9f#Hk3...
+
+# Also pull back any reader comments left on the note (feedback loop)
+npx slingit pull https://slingit.dev/aX7k2mQp9f#Hk3... --comments
+
 # Skill for Claude Code ("send these findings to X's email")
 npx slingit install-skill
 
@@ -58,6 +64,30 @@ Env takes precedence over the file; the file takes precedence over the built-in
 | `--from <text>` | Optional sender/signature shown on the note page and email | hidden |
 | `--copy` | Copy the link to the clipboard | off |
 
+## Loading a note (`pull`)
+
+```bash
+npx slingit pull <url> [--comments]
+```
+
+Fetches a published note and prints its Markdown to stdout — handy for pulling an
+analysis another agent slung straight into a session. The note id is read from the URL
+path and, for encrypted notes, the AES key from the `#` fragment: the ciphertext is
+fetched by id alone and decrypted locally, so the key is never sent to the server (same
+zero-knowledge model as the browser reader). Pass the **full link including the part
+after `#`**; `--public` links have no fragment and pull just as well. Expired or missing
+notes produce a clear error and a non-zero exit code.
+
+With `--comments`, any reader comments left on the note are fetched too and appended as
+a `## Comments` section after the body — closing the feedback loop when someone reviews a
+note you shared. Comments on encrypted notes are decrypted locally with the same key. If
+the comments cannot be fetched, the note body still prints and a one-line notice goes to
+stderr.
+
+| Flag | Description | Default |
+|---|---|---|
+| `--comments` | Also fetch reader comments and append them after the note body | off |
+
 ## Skill installation
 
 ```bash

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "slingit",
-  "version": "0.1.1",
-  "description": "Fire-and-forget: share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
+  "version": "0.2.1",
+  "description": "Share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
   "type": "module",
   "bin": {
     "slingit": "bin/slingit.js"
   },
+  "scripts": {
+    "test": "node test/unit.mjs"
+  },
   "files": [
     "bin",
     "src",
@@ -26,4 +29,4 @@
   ],
   "author": "BTA Systems",
   "license": "MIT"
-}
+}

package/skill/SKILL.md

@@ -1,14 +1,46 @@
 ---
 name: slingit
-description: Share formatted Markdown notes/analyses via a link (SlingIt). Use when the user asks to send session findings to an email, share an analysis as a link, "slingit this to X", "send these conclusions to Y's email", or "give me a link to this analysis".
+description: Share formatted Markdown notes/analyses via a link (SlingIt), or load one back into the session. Use when the user asks to send session findings to an email, share an analysis as a link, "slingit this to X", "send these conclusions to Y's email", "give me a link to this analysis", or to read/load/pull an existing SlingIt link ("load this slingit note", "pull https://slingit.dev/...").
 ---
 
 # SlingIt — publish notes from the session
 
-You publish formatted Markdown notes with `npx slingit shot`. Each note gets a short
-link `https://slingit.dev/{id}`; by default it is **end-to-end encrypted** — the AES-256
+You publish formatted Markdown notes with `npx slingit shot`, and load published
+notes back with `npx slingit pull <url>`. Each note gets a short link
+`https://slingit.dev/{id}`; by default it is **end-to-end encrypted** — the AES-256
 key lives only in the `#` fragment of the URL, so the server cannot read the content.
 
+## Loading a note into the session (`pull`)
+
+When the user gives you a SlingIt link and asks to "load", "read", "pull", or "open"
+the note (e.g. another agent slung an analysis to review), fetch it with:
+
+```bash
+npx slingit pull <url>
+```
+
+It prints the note's Markdown to stdout so you can read it into your context. Pass the
+**full link including the part after `#`** — for encrypted notes the key lives in the
+fragment and decryption happens locally in the CLI (the key is never sent to the
+server). Public links (`--public`) have no key and pull just as well. If the note has
+expired or the link is wrong, `pull` prints a clear error and exits non-zero.
+
+### Reader feedback (`--comments`)
+
+Add `--comments` to also fetch any reader comments left on the note and append them as
+a `## Comments` section after the body:
+
+```bash
+npx slingit pull <url> --comments
+```
+
+Use this to **check for reviewer feedback on a note you shared earlier**: sling an
+analysis to a human, and once they have read it and left comments in the browser reader,
+pull it back with `--comments` to bring their feedback into the session. Comments on
+encrypted notes are decrypted locally with the same key from the `#` fragment. If a note
+has no comments yet, the section reads `## Comments (0)`; if the comments cannot be
+fetched, the note body still prints and a one-line notice goes to stderr.
+
 ## Choose the input method first
 
 Use the method that matches the user's request:

package/src/cli.js

@@ -1,12 +1,14 @@
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { shot } from './shot.js';
+import { pull } from './pull.js';
 import { installSkill } from './install-skill.js';
 
 const HELP = `slingit — share Markdown notes via link (encrypted by default)
 
 Usage:
   slingit shot [file.md] [flags]     publish a note (file or stdin)
+  slingit pull <url> [--comments]    fetch a note by link, print its Markdown to stdout
   slingit install-skill [flags]      install the agent skill
   slingit help                       this help
 
@@ -33,6 +35,11 @@ Configuration (optional — the CLI works out of the box, no config needed):
 
 By default: the note is encrypted with AES-256-GCM locally, the key only ends up
 in the #URL fragment (the server never sees it). --public is a deliberate opt-out.
+
+pull decrypts locally too: it reads the note id from the URL path and the key from
+the #fragment, fetches the ciphertext by id alone, and prints the Markdown. The key
+is never sent to the server. Pass the full link, including the part after #.
+Add --comments to also fetch reader feedback and append it as a Comments section.
 `;
 
 export async function main(argv) {
@@ -41,6 +48,8 @@ export async function main(argv) {
   switch (command) {
     case 'shot':
       return shot(rest);
+    case 'pull':
+      return pull(rest);
     case 'install-skill':
       return installSkill(rest);
     case '--version':

package/src/crypto.js

@@ -20,3 +20,21 @@ export async function encryptNote(plaintext) {
     keyB64url: Buffer.from(keyBytes).toString('base64url'),
   };
 }
+
+/**
+ * Decrypts a note fetched from the server. Mirrors the browser reader:
+ * the AES-256-GCM key comes from the URL #fragment (base64url) and never
+ * touches the server; the IV lives in the note's public metadata (base64).
+ *
+ * @param {ArrayBuffer|Uint8Array} ciphertext raw bytes from GET /{id}.blob
+ * @param {string} keyB64url  32-byte key, base64url, from the #fragment
+ * @param {string} ivB64      12-byte IV, base64, from meta.encryption.iv
+ * @returns {Promise<string>} the decrypted Markdown
+ */
+export async function decryptNote(ciphertext, keyB64url, ivB64) {
+  const keyBytes = Buffer.from(keyB64url, 'base64url');
+  const iv = Buffer.from(ivB64, 'base64');
+  const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['decrypt']);
+  const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+  return new TextDecoder().decode(plaintext);
+}

package/src/pull.js

@@ -0,0 +1,200 @@
+import { decryptNote } from './crypto.js';
+
+// Same id shape the Worker route accepts (10–14 url-safe chars).
+const ID_RE = /^[A-Za-z0-9_-]{10,14}$/;
+
+/**
+ * `slingit pull <url>` — fetch a published note and print its Markdown to stdout.
+ *
+ * The note id comes from the URL path and the AES key from the #fragment. The
+ * blob is fetched by id alone (public read, no token) exactly like the browser
+ * reader, so the key never reaches the server — the iron rule stays intact.
+ */
+export async function pull(args) {
+  const { url, comments: wantComments } = parseArgs(args);
+  const { id, origin, key } = parseUrl(url);
+
+  const meta = await fetchMeta(origin, id);
+  const blob = await fetchBlob(origin, id);
+
+  let markdown;
+  if (meta.mode === 'public') {
+    // Public notes store plaintext Markdown — nothing to decrypt.
+    markdown = Buffer.from(blob).toString('utf8');
+  } else {
+    if (!key) {
+      throw new Error(
+        'this note is encrypted but the link has no key after "#" — you need the full link (including the #fragment) to read it'
+      );
+    }
+    if (!meta.encryption?.iv) {
+      throw new Error('note metadata is missing encryption parameters — cannot decrypt');
+    }
+    try {
+      markdown = await decryptNote(blob, key, meta.encryption.iv);
+    } catch {
+      throw new Error(
+        'could not decrypt the note — the key in the link is wrong or the content is corrupted'
+      );
+    }
+  }
+
+  let output = markdown.endsWith('\n') ? markdown : `${markdown}\n`;
+
+  if (wantComments) {
+    // The note itself already loaded — a comments hiccup must not fail the pull.
+    try {
+      const raw = await fetchComments(origin, id);
+      const normalized = await decryptComments(raw, meta, key);
+      output += formatCommentsSection(normalized);
+    } catch (err) {
+      process.stderr.write(`slingit: could not load comments (${err.message}); skipping\n`);
+    }
+  }
+
+  process.stdout.write(output);
+}
+
+function parseArgs(args) {
+  let url = null;
+  let comments = false;
+  for (const a of args) {
+    if (a === '--comments') {
+      comments = true;
+      continue;
+    }
+    if (a.startsWith('-')) throw new Error(`unknown flag "${a}". See: slingit help`);
+    if (url) throw new Error('only one URL can be given');
+    url = a;
+  }
+  if (!url) throw new Error('usage: slingit pull <url> [--comments]');
+  return { url, comments };
+}
+
+function parseUrl(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`not a valid URL: ${input}`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`unsupported URL scheme "${url.protocol}" — expected http(s)`);
+  }
+  const segment = url.pathname.split('/').filter(Boolean).pop() || '';
+  const id = segment.replace(/\.(blob|json|raw)$/, '');
+  if (!ID_RE.test(id)) {
+    throw new Error(`could not find a note id in the URL: ${input}`);
+  }
+  // The key is the whole #fragment, matching the reader's location.hash.slice(1).
+  const key = url.hash ? url.hash.slice(1) : '';
+  return { id, origin: url.origin, key };
+}
+
+async function fetchMeta(origin, id) {
+  const res = await httpGet(`${origin}/${id}.json`);
+  assertNotExpired(res);
+  if (!res.ok) throw new Error(`server returned HTTP ${res.status} for the note metadata`);
+  try {
+    return await res.json();
+  } catch {
+    throw new Error('unexpected response from the server (invalid note metadata)');
+  }
+}
+
+async function fetchBlob(origin, id) {
+  const res = await httpGet(`${origin}/${id}.blob`);
+  assertNotExpired(res);
+  if (!res.ok) throw new Error(`server returned HTTP ${res.status} for the note content`);
+  return res.arrayBuffer();
+}
+
+/** Fetch the reader comments for a note. Returns the raw `comments` array. */
+async function fetchComments(origin, id) {
+  const res = await httpGet(`${origin}/${id}/comments`);
+  if (!res.ok) throw new Error(`server returned HTTP ${res.status}`);
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    throw new Error('invalid comments response');
+  }
+  return Array.isArray(data?.comments) ? data.comments : [];
+}
+
+/**
+ * Normalize raw comments into `{ author, createdAt, scope, text, quote }`.
+ * For encrypted notes each comment carries its own ciphertext + fresh IV and is
+ * decrypted with the note's key (same in-memory key, never logged or stored — the
+ * iron rule holds exactly like the note-body path). A comment that fails to
+ * decrypt or parse is skipped rather than aborting the whole pull.
+ */
+async function decryptComments(raw, meta, key) {
+  if (meta.mode === 'public') {
+    // Public comments are already plaintext.
+    return raw.map((c) => ({
+      author: c.author,
+      createdAt: c.createdAt,
+      scope: c.scope,
+      text: c.text,
+      quote: c.quote ?? null,
+    }));
+  }
+  const out = [];
+  for (const c of raw) {
+    try {
+      const ciphertext = Buffer.from(c.ciphertext, 'base64');
+      const { text, quote } = JSON.parse(await decryptNote(ciphertext, key, c.iv));
+      out.push({
+        author: c.author,
+        createdAt: c.createdAt,
+        scope: c.scope,
+        text,
+        quote: quote ?? null,
+      });
+    } catch {
+      // Corrupted or tampered comment — skip it.
+    }
+  }
+  return out;
+}
+
+/**
+ * Render a normalized comments array as a Markdown section appended after the
+ * note body. Pure and self-contained so it can be unit-tested without a server.
+ */
+export function formatCommentsSection(comments) {
+  let out = `\n---\n\n## Comments (${comments.length})\n\n`;
+  if (comments.length === 0) {
+    return `${out}_No comments yet._\n`;
+  }
+  out += comments.map(formatComment).join('\n\n');
+  return out.endsWith('\n') ? out : `${out}\n`;
+}
+
+function formatComment(c) {
+  const date = typeof c.createdAt === 'string' ? c.createdAt.slice(0, 10) : '';
+  const lines = [`**${c.author}** — ${date}`];
+  if (c.scope === 'selection' && c.quote != null && c.quote !== '') {
+    lines.push(`> ${c.quote}`);
+  }
+  lines.push('', c.text ?? '');
+  return lines.join('\n');
+}
+
+function assertNotExpired(res) {
+  if (res.status === 410) {
+    throw new Error('this note has expired and is no longer available');
+  }
+  if (res.status === 404) {
+    throw new Error('note not found — the link may be wrong or the note has expired');
+  }
+}
+
+async function httpGet(target) {
+  try {
+    return await fetch(target);
+  } catch (err) {
+    throw new Error(`could not connect to ${new URL(target).origin} (${err.cause?.code || err.message})`);
+  }
+}