slingit 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,13 @@ npx slingit shot analysis.md
 cat analysis.md | npx slingit shot
 
 # Send the link by email (the email contains the full working link)
-npx slingit shot analysis.md --tomail someone@company.com
+npx slingit shot analysis.md --mailto someone@company.com
+
+# Add a short message visible only in the email
+npx slingit shot analysis.md --mailto someone@company.com --mailmessage "Context before you open this"
+
+# Add a sender signature to the note page and email
+npx slingit shot analysis.md --from "Marcin"
 
 # Public note: no encryption, server-side render, SEO
 npx slingit shot analysis.md --public
@@ -20,8 +26,14 @@ 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...
+
 # Skill for Claude Code ("send these findings to X's email")
 npx slingit install-skill
+
+# Skill for Codex
+npx slingit install-skill --target codex
 ```
 
 ## Configuration
@@ -42,17 +54,45 @@ Env takes precedence over the file; the file takes precedence over the built-in
 | Flag | Description | Default |
 |---|---|---|
 | `--public` | Disables encryption, enables server-side render (SEO/preview) | off (encrypted) |
-| `--tomail [email]` | Send the link by email; without a value, uses `defaultToMail` | off |
+| `--mailto [email]` | Send the link by email; without a value, uses `defaultToMail` | off |
+| `--mailmessage <text>` | Add an optional message/comment to the email body; requires `--mailto` | off |
 | `--expire <days>` | Delete the note after X days (1-365) | no TTL |
 | `--title <text>` | Title (with `--public`, used for preview/SEO) | first `# H1` |
+| `--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>
+```
+
+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.
+
+## Skill installation
+
+```bash
+npx slingit install-skill                    # Claude Code, user profile
+npx slingit install-skill --project          # Claude Code, current repo
+npx slingit install-skill --target codex     # Codex, user profile
+npx slingit install-skill --target all       # Claude Code + Codex
+```
+
+Claude Code installs to `~/.claude/skills/slingit/` or `./.claude/skills/slingit/`.
+Codex installs to `~/.agents/skills/slingit/` or `./.agents/skills/slingit/`.
+
 ## Privacy model
 
 - **Default (encrypted):** content is encrypted with AES-256-GCM locally; only the
   ciphertext goes to the server. The key in the `#` URL fragment is never sent by the
   browser — full zero-knowledge.
-- **`--tomail` + encrypted:** the key passes through the server (in transit, not stored)
+- **`--mailto` + encrypted:** the key passes through the server (in transit, not stored)
   and the mail — a deliberate decision: since the recipient needs the key anyway, they
   get the full link. Security model: capability URL — whoever has the link can read it.
 - **`--public`:** a deliberate opt-out from encryption (plaintext, SEO, nice preview).

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "slingit",
-  "version": "0.1.0",
-  "description": "Fire-and-forget: share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
+  "version": "0.2.0",
+  "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",

package/skill/SKILL.md

@@ -1,57 +1,128 @@
 ---
 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.
 
-## Steps
+## Loading a note into the session (`pull`)
 
-1. Collect the session's findings into a `.md` file (in a temp/scratchpad directory).
-   Format it properly: `##` headings, code blocks with a language tag (```php, ```ts etc.),
-   first line as `# Title`.
-2. Run the CLI (works out of the box — no token or configuration required):
-   ```bash
-   npx slingit shot <file.md> [flags]
-   ```
-3. Return the full link from stdout to the user in chat (for an encrypted note the link
-   contains the key after `#` — without it the content cannot be decrypted).
+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.
+
+## Choose the input method first
+
+Use the method that matches the user's request:
+
+1. **Conversation/session content**: if the user asks to send findings, a summary, details
+   from this conversation, or anything you are about to compose, pipe Markdown directly to
+   `npx slingit shot`. Do **not** create a temporary `.md` file just to pass generated
+   conversation content.
+2. **Existing Markdown file**: if the user gives a specific `.md` file or asks to publish
+   a file from the workspace, pass that file path to `npx slingit shot <file.md>`.
+
+Always format the Markdown properly: first line as `# Title`, `##` headings, and code
+blocks with language tags (```php, ```ts, ```bash, etc.).
+
+## Commands
+
+For generated conversation content, use stdin/pipe:
+
+```bash
+cat <<'EOF' | npx slingit shot [flags]
+# Title
+
+Markdown content from the conversation.
+EOF
+```
+
+In PowerShell, use a here-string:
+
+```powershell
+@'
+# Title
+
+Markdown content from the conversation.
+'@ | npx slingit shot [flags]
+```
+
+For an existing Markdown file, use the file path:
+
+```bash
+npx slingit shot <file.md> [flags]
+```
+
+Return the full link from stdout to the user in chat. For an encrypted note the link
+contains the key after `#`; without it the content cannot be decrypted.
 
 ## Choosing flags based on the user's intent
 
 | Intent | Flags |
 |---|---|
-| "send it to X's email" | `--tomail X` (the email contains the full working link) |
-| "maximum privacy" | **no** `--tomail` — the default; the link with the key stays in chat only, the user shares it themselves |
+| "send it to X's email" | `--mailto X` (the email contains the full working link) |
+| "include this message/comment in the email" | `--mailmessage "..."` (only together with `--mailto`) |
+| "maximum privacy" | **no** `--mailto` — the default; the link with the key stays in chat only, the user shares it themselves |
 | "public link" (for a PR, docs, SEO) | `--public` (no encryption, server-side render) |
 | "make it disappear after X days" | `--expire X` |
+| "send from X", "signed by X", "from me/Marcin/team name" | `--from "X"` |
 | title different from the H1 | `--title "..."` |
 
-Flags can be combined, e.g. `--public --tomail x@y.z --expire 7`.
+Flags can be combined, e.g. `--public --mailto x@y.z --mailmessage "Read the summary first" --from "Marcin" --expire 7`.
 
 ## Rules (do not break these)
 
 - Encryption is the **default** — there is no `--encrypt` flag; `--public` is a deliberate
   opt-out (use it only when the user explicitly wants a public/indexable note).
-- The encryption key must **never** end up in files, logs, or storage. With `--tomail`,
+- The encryption key must **never** end up in files, logs, or storage. With `--mailto`,
   the CLI passes it to the server only in the `mailFragment` field, used solely to compose
   the link inside the email (transit only, never stored). Do not print the key separately —
   only as part of the full link.
-- When the user asks for "maximum privacy", skip `--tomail` even if you know the address —
+- When the user asks for "maximum privacy", skip `--mailto` even if you know the address —
   zero-knowledge only holds when the key never leaves the terminal/chat.
 - No token is required — the CLI ships with a built-in one. `SLINGIT_TOKEN` (env) or
   `"token"` in `~/.slingit/config.json` are optional overrides (e.g. a self-hosted
   instance) — never invent a token.
+- Use `--from` only when the user explicitly gives a sender/signature. If it is not
+  provided, do not invent one.
+- Use `--mailmessage` only when the user explicitly asks to add a message/comment to
+  the email. It requires `--mailto` and is not part of the note page.
 
 ## Example
 
+Conversation content:
+
 ```
-> /slingit boss@company.com
-1. Save the findings to analysis.md (with a # Title and language-tagged code blocks)
-2. npx slingit shot analysis.md --tomail boss@company.com
+User asks: "Send these findings to boss@company.com from Marcin."
+1. Compose Markdown directly from the conversation.
+2. Pipe it to:
+   cat <<'EOF' | npx slingit shot --mailto boss@company.com --mailmessage "Please read the recommendation first." --from "Marcin"
+   # Title
+
+   ...
+   EOF
 3. Reply: "Sent. Link (contains the decryption key): https://slingit.dev/aX7k2mQp9f#Hk3..."
 ```
+
+Existing file:
+
+```
+User asks: "Send docs/review.md to boss@company.com."
+1. Use the file directly:
+   npx slingit shot docs/review.md --mailto boss@company.com
+2. Reply with the full link from stdout.
+```

package/src/cli.js

@@ -1,23 +1,32 @@
 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 install-skill [--project]  install the Claude Code skill
+  slingit pull <url>                 fetch a note by link, print its Markdown to stdout
+  slingit install-skill [flags]      install the agent skill
   slingit help                       this help
 
 Flags (shot):
   --public           disable encryption: plaintext, server-side render, SEO
-  --tomail [email]   send the link by email (Resend); if omitted, uses
+  --mailto [email]   send the link by email (Resend); if omitted, uses
                      defaultToMail from ~/.slingit/config.json
+  --mailmessage <text>
+                     optional message included in the email only; requires --mailto
   --expire <days>    delete the note after X days (1-365)
   --title <text>     note title (with --public, used for preview/SEO)
+  --from <text>      optional sender/signature shown on the note page and email
   --copy             copy the link to the clipboard
 
+Flags (install-skill):
+  --target <name>     claude (default), codex, or all
+  --project           install into this repository instead of your user profile
+
 Configuration (optional — the CLI works out of the box, no config needed):
   SLINGIT_TOKEN      override the built-in bearer token (e.g. self-hosted instance)
   SLINGIT_URL        server address (defaults to the official SlingIt instance)
@@ -26,6 +35,10 @@ 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 #.
 `;
 
 export async function main(argv) {
@@ -34,6 +47,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/install-skill.js

@@ -3,22 +3,53 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-/**
- * Copies SKILL.md to ~/.claude/skills/slingit/ (default)
- * or ./.claude/skills/slingit/ with --project.
- */
 export async function installSkill(args) {
-  const project = args.includes('--project');
+  const opts = parseArgs(args);
   const source = fileURLToPath(new URL('../skill/SKILL.md', import.meta.url));
-  const targetDir = project
-    ? join(process.cwd(), '.claude', 'skills', 'slingit')
-    : join(homedir(), '.claude', 'skills', 'slingit');
+  const targets = opts.target === 'all' ? ['claude', 'codex'] : [opts.target];
 
-  await mkdir(targetDir, { recursive: true });
-  const target = join(targetDir, 'SKILL.md');
-  await copyFile(source, target);
+  for (const targetName of targets) {
+    const targetDir = targetPath(targetName, opts.project);
+    await mkdir(targetDir, { recursive: true });
+    const target = join(targetDir, 'SKILL.md');
+    await copyFile(source, target);
+    console.log(`✔ Skill installed (${targetName}): ${target}`);
+  }
 
-  console.log(`✔ Skill installed: ${target}`);
-  console.log('  In a Claude Code session, ask e.g.: "send these findings to X\'s email" or "/slingit".');
+  console.log('  Ask e.g.: "send these findings to X\'s email" or invoke the slingit skill directly.');
   console.log('  Works out of the box — no token or configuration needed.');
 }
+
+function parseArgs(args) {
+  const opts = { project: false, target: 'claude' };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--project':
+        opts.project = true;
+        break;
+      case '--target': {
+        const target = args[++i];
+        if (!['claude', 'codex', 'all'].includes(target)) {
+          throw new Error('--target must be one of: claude, codex, all');
+        }
+        opts.target = target;
+        break;
+      }
+      default:
+        throw new Error(`unknown flag "${a}". See: slingit help`);
+    }
+  }
+  return opts;
+}
+
+function targetPath(target, project) {
+  if (target === 'claude') {
+    return project
+      ? join(process.cwd(), '.claude', 'skills', 'slingit')
+      : join(homedir(), '.claude', 'skills', 'slingit');
+  }
+  return project
+    ? join(process.cwd(), '.agents', 'skills', 'slingit')
+    : join(homedir(), '.agents', 'skills', 'slingit');
+}

package/src/pull.js

@@ -0,0 +1,109 @@
+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 } = 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'
+      );
+    }
+  }
+
+  process.stdout.write(markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+}
+
+function parseArgs(args) {
+  let url = null;
+  for (const a of args) {
+    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 };
+}
+
+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();
+}
+
+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})`);
+  }
+}

package/src/shot.js

@@ -10,23 +10,29 @@ export async function shot(args) {
   const config = await loadConfig();
 
   let sentTo = null;
-  if (opts.tomail !== undefined) {
-    sentTo = opts.tomail || config.defaultToMail;
+  if (opts.mailto !== undefined) {
+    sentTo = opts.mailto || config.defaultToMail;
     if (!sentTo) {
-      throw new Error('--tomail given without an address and no defaultToMail in ~/.slingit/config.json');
+      throw new Error('--mailto given without an address and no defaultToMail in ~/.slingit/config.json');
     }
     if (!EMAIL_RE.test(sentTo)) throw new Error(`invalid email address: ${sentTo}`);
   }
+  if (opts.mailmessage && !sentTo) {
+    throw new Error('--mailmessage can only be used together with --mailto');
+  }
 
   const markdown = await readInput(opts.file);
   if (!markdown.trim()) throw new Error('empty note — nothing to publish');
 
   const title = opts.title || extractTitle(markdown);
+  const signature = opts.from ? opts.from.trim().slice(0, 120) : '';
 
   const body = {
     mode: opts.public ? 'public' : 'encrypted',
     expireDays: opts.expire ?? null,
     sentTo,
+    mailMessage: opts.mailmessage ? opts.mailmessage.trim().slice(0, 1000) : '',
+    signature,
     sourceSession: process.env.CLAUDE_SESSION_ID || null,
     sourceCwd: process.cwd(),
   };
@@ -70,7 +76,16 @@ export async function shot(args) {
 }
 
 function parseArgs(args) {
-  const opts = { file: null, public: false, copy: false, tomail: undefined, expire: null, title: null };
+  const opts = {
+    file: null,
+    public: false,
+    copy: false,
+    mailto: undefined,
+    mailmessage: null,
+    expire: null,
+    title: null,
+    from: null,
+  };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     switch (a) {
@@ -80,11 +95,17 @@ function parseArgs(args) {
       case '--copy':
         opts.copy = true;
         break;
-      case '--tomail':
+      case '--mailto':
         if (args[i + 1] && !args[i + 1].startsWith('-')) {
-          opts.tomail = args[++i];
+          opts.mailto = args[++i];
         } else {
-          opts.tomail = null; // use defaultToMail from the config
+          opts.mailto = null; // use defaultToMail from the config
+        }
+        break;
+      case '--mailmessage':
+        opts.mailmessage = args[++i];
+        if (opts.mailmessage === undefined || opts.mailmessage.startsWith('-')) {
+          throw new Error('--mailmessage requires a value');
         }
         break;
       case '--expire': {
@@ -99,6 +120,10 @@ function parseArgs(args) {
         opts.title = args[++i];
         if (opts.title === undefined) throw new Error('--title requires a value');
         break;
+      case '--from':
+        opts.from = args[++i];
+        if (opts.from === undefined || opts.from.startsWith('-')) throw new Error('--from requires a value');
+        break;
       default:
         if (a.startsWith('-')) throw new Error(`unknown flag "${a}". See: slingit help`);
         if (opts.file) throw new Error('only one file can be given');