slingit 0.2.0 → 0.2.2

package/README.md

@@ -29,6 +29,9 @@ 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
 
@@ -64,7 +67,7 @@ Env takes precedence over the file; the file takes precedence over the built-in
 ## Loading a note (`pull`)
 
 ```bash
-npx slingit pull <url>
+npx slingit pull <url> [--comments|--comments-only]
 ```
 
 Fetches a published note and prints its Markdown to stdout — handy for pulling an
@@ -75,6 +78,21 @@ zero-knowledge model as the browser reader). Pass the **full link including the
 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.
+
+With `--comments-only`, only the comments are fetched and printed — the note body is
+skipped entirely. Unlike `--comments`, a failure to fetch here is a hard error (there's
+nothing else to fall back to).
+
+| Flag | Description | Default |
+|---|---|---|
+| `--comments` | Also fetch reader comments and append them after the note body | off |
+| `--comments-only` | Fetch and print just the comments, skipping the note body | off |
+
 ## Skill installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slingit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -25,6 +25,30 @@ 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.
+
+If you only care about the feedback and not the (already-known) note body — e.g. checking
+in on a note you slung earlier in the same session — use `--comments-only` instead to skip
+re-fetching and re-printing the whole document:
+
+```bash
+npx slingit pull <url> --comments-only
+```
+
 ## Choose the input method first
 
 Use the method that matches the user's request:

package/src/cli.js

@@ -8,7 +8,8 @@ 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>                 fetch a note by link, print its Markdown to stdout
+  slingit pull <url> [--comments|--comments-only]
+                                     fetch a note by link, print its Markdown to stdout
   slingit install-skill [flags]      install the agent skill
   slingit help                       this help
 
@@ -39,6 +40,8 @@ in the #URL fragment (the server never sees it). --public is a deliberate opt-ou
 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.
+Use --comments-only to fetch just the comments, without the note body.
 `;
 
 export async function main(argv) {

package/src/pull.js

@@ -11,10 +11,23 @@ const ID_RE = /^[A-Za-z0-9_-]{10,14}$/;
  * reader, so the key never reaches the server — the iron rule stays intact.
  */
 export async function pull(args) {
-  const { url } = parseArgs(args);
+  const { url, comments: wantComments, commentsOnly } = parseArgs(args);
   const { id, origin, key } = parseUrl(url);
 
   const meta = await fetchMeta(origin, id);
+
+  if (commentsOnly) {
+    if (meta.mode !== 'public' && !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 its comments'
+      );
+    }
+    const raw = await fetchComments(origin, id);
+    const normalized = await decryptComments(raw, meta, key);
+    process.stdout.write(formatCommentsSection(normalized, { standalone: true }));
+    return;
+  }
+
   const blob = await fetchBlob(origin, id);
 
   let markdown;
@@ -39,18 +52,41 @@ export async function pull(args) {
     }
   }
 
-  process.stdout.write(markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+  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;
+  let commentsOnly = false;
   for (const a of args) {
+    if (a === '--comments') {
+      comments = true;
+      continue;
+    }
+    if (a === '--comments-only') {
+      commentsOnly = 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>');
-  return { url };
+  if (!url) throw new Error('usage: slingit pull <url> [--comments|--comments-only]');
+  return { url, comments, commentsOnly };
 }
 
 function parseUrl(input) {
@@ -91,6 +127,84 @@ async function fetchBlob(origin, id) {
   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. By default it's
+ * appended after the note body (so it opens with a `---` separator); pass
+ * `standalone: true` for `--comments-only` output, which has no document above
+ * it to separate from. Pure and self-contained so it can be unit-tested without
+ * a server.
+ */
+export function formatCommentsSection(comments, { standalone = false } = {}) {
+  let out = standalone
+    ? `## Comments (${comments.length})\n\n`
+    : `\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');