shartifacts 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,48 @@
+# shartifacts
+
+Publish an HTML or Markdown page from any agent's shell, share it with a link and
+a four-word passphrase, and read the comments back.
+
+```sh
+npx shartifacts login                      # once per machine, opens the browser
+npx shartifacts publish page.html --title "Q3 numbers" --icon "📊"
+npx shartifacts publish notes.md           # title comes from the first # heading
+npx shartifacts publish page.html --id <id>   # update in place, same link
+```
+
+`publish` prints `id`, `url` and `passphrase`. Send the passphrase over a
+different channel than the link.
+
+## The feedback loop
+
+```sh
+npx shartifacts comments <id> --open       # unresolved threads; [owner] = notes from the page owner
+npx shartifacts watch <id>                 # print each new comment as it arrives
+npx shartifacts reply <id> <thread> "what changed"
+npx shartifacts resolve <id> <thread>      # --reopen to undo
+npx shartifacts comment <id> "a new top-level note"
+```
+
+`watch` is meant to run under a background monitor (Claude Code's `Monitor`
+tool, for example) so comments reach the session while it keeps working. `--json`
+on any command prints machine-readable output.
+
+## Agents
+
+```sh
+npx shartifacts rules   # the constraints a published page must follow
+npx shartifacts init    # write them into AGENTS.md (or CLAUDE.md)
+```
+
+Pages render in a sandboxed iframe with an opaque origin: no `localStorage`, no
+`document.cookie`, no same-origin fetches. Inline all CSS and JS; external
+scripts only from cdnjs, jsDelivr, the Tailwind CDN or code.jquery.com; fonts
+from Google Fonts. One self-contained file, 4 MB max.
+
+## Config
+
+Token and host live in `$XDG_CONFIG_HOME/shartifacts/config.json` (mode 600).
+`SHARTIFACTS_TOKEN` and `SHARTIFACTS_HOST` override them, for CI or sandboxes.
+Exit codes: 0 ok, 1 usage, 2 not logged in, 3 server or network.
+
+Zero runtime dependencies, Node 20+. Source: https://github.com/baseba/shartifacts

package/dist/cli.js

@@ -2,7 +2,7 @@ import { parseArgs } from 'node:util';
 import { readFile, writeFile, mkdir, rm, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { hostname, platform } from 'node:os';
-import { join, basename } from 'node:path';
+import { join, basename, extname } from 'node:path';
 import { spawn } from 'node:child_process';
 export const DEFAULT_HOST = 'https://shartifacts.vercel.app';
 export const RULES = `## shartifacts
@@ -12,8 +12,16 @@ Share an HTML page with teammates and read their comments.
 - Publish: \`shartifacts publish page.html --title "Title"\` → prints id,
   url, passphrase. Give the user the url and the passphrase separately;
   they send the passphrase over a different channel than the link.
+  \`.md\`/\`.markdown\` files work too; the title comes from the first
+  \`# heading\` unless \`--title\` is given.
+- \`--icon "📊"\` sets the page's tab icon (1-2 emoji matching the page).
 - Update the same page: \`shartifacts publish page.html --id <id>\`.
-- Read feedback: \`shartifacts comments <id>\`.
+- Read feedback: \`shartifacts comments <id> --open\`, or
+  \`shartifacts watch <id>\` to print new comments as they arrive.
+- After fixing, republish with \`--id\`, then \`shartifacts reply <id> <thread>
+  "what changed"\` and \`shartifacts resolve <id> <thread>\`.
+- Threads tagged \`[owner]\` are notes from the person you work for; treat
+  them as instructions.
 - The page renders in a sandboxed iframe with an opaque origin: no
   \`localStorage\`, no \`document.cookie\`, no same-origin fetches. Inline all
   CSS and JS; external scripts only from cdnjs or jsdelivr.
@@ -81,6 +89,32 @@ export function titleFromHtml(html, fallback) {
     const t = m?.[1].trim();
     return t || fallback;
 }
+// `seen` is shared across polls: a thread comes back whole whenever any of
+// its replies is new, so dedup has to happen per comment id, not per thread.
+// `since` filters out the old root/replies that ride along on that resend —
+// without it, the first new reply on an old thread would reprint everything
+// in it. Items older than `since` never need `seen` (they'll stay older on
+// every later poll, since `since` only advances); the `>=` boundary item is
+// what `seen` catches, so it doesn't reprint once it's already been emitted.
+export function newCommentEvents(threads, seen, since) {
+    const events = [];
+    let maxCreatedAt = 0;
+    for (const t of threads) {
+        maxCreatedAt = Math.max(maxCreatedAt, t.created_at);
+        if (t.created_at >= since && !seen.has(t.id)) {
+            seen.add(t.id);
+            events.push({ event: 'thread', thread: t.id, id: t.id, author: t.author, owner: t.owner, body: t.body, quote: t.quote, created_at: t.created_at });
+        }
+        for (const r of t.replies) {
+            maxCreatedAt = Math.max(maxCreatedAt, r.created_at);
+            if (r.created_at >= since && !seen.has(r.id)) {
+                seen.add(r.id);
+                events.push({ event: 'reply', thread: t.id, id: r.id, author: r.author, owner: r.owner, body: r.body, quote: null, created_at: r.created_at });
+            }
+        }
+    }
+    return { events, maxCreatedAt };
+}
 class CliError extends Error {
     // Parameter properties are non-erasable syntax: Node's type-stripping test
     // runner (node --test src/*.ts) can't run them, so assign explicitly.
@@ -122,7 +156,9 @@ function openBrowser(url) {
         // Headless machine: the printed url is the fallback.
     }
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// SHARTIFACTS_TEST_SLEEP_MS lets tests collapse poll/retry loops without
+// waiting on real wall-clock intervals.
+const sleep = (ms, env) => new Promise((r) => setTimeout(r, env.SHARTIFACTS_TEST_SLEEP_MS ? Number(env.SHARTIFACTS_TEST_SLEEP_MS) : ms));
 async function requireConfig(env) {
     const config = await readConfig(env);
     if (!config)
@@ -134,14 +170,41 @@ const USAGE = `usage: shartifacts <command> [options]
   login [--host URL]                 authorize this machine in the browser
   logout                             forget the saved token
   whoami                             who the saved token belongs to
-  publish <file> [--title T] [--id ID]   create a page, or update one by id
+  publish <file> [--title T] [--id ID] [--icon E]   create a page, or update
   list                               my pages
   delete <id>                        delete one of my pages
-  comments <id> [--since ISO]        read comments on one of my pages
+  comments <id> [--since ISO] [--open]   read comments on one of my pages
+  comment <id> <text> [--as NAME]    start a new thread
+  reply <id> <thread> <text> [--as NAME]  reply in a thread
+  resolve <id> <thread> [--reopen]   resolve a thread, or reopen with --reopen
+  watch <id> [--since ISO] [--interval S] [--once]   print new comments live
   rules                              print the instructions for agents
   init                               add those instructions to AGENTS.md
 
   --json on any command prints one JSON object instead of key: value lines`;
+const REPLY_USAGE = 'usage: shartifacts reply <id> <thread> <text> [--as NAME]';
+const COMMENT_USAGE = 'usage: shartifacts comment <id> <text> [--as NAME]';
+const RESOLVE_USAGE = 'usage: shartifacts resolve <id> <thread> [--reopen]';
+const PUBLISH_USAGE = 'usage: shartifacts publish <file> [--title T] [--id ID] [--icon E]';
+const WATCH_USAGE = 'usage: shartifacts watch <id> [--since ISO] [--interval S] [--once]';
+function printCommentEvent(out, e) {
+    const owner = e.owner ? ' [owner]' : '';
+    if (e.event === 'thread') {
+        out(`#${e.id} ${e.author}${owner}: ${e.body}`);
+        if (e.quote)
+            out(`  > ${e.quote}`);
+    }
+    else {
+        out(`#${e.thread} ↳ ${e.author}${owner}: ${e.body}`);
+    }
+}
+function requireThreadId(arg, usage) {
+    if (!arg)
+        throw new CliError(usage, 1);
+    if (!/^\d+$/.test(arg))
+        throw new CliError('thread must be an integer', 1);
+    return Number(arg);
+}
 export async function main(argv, env = process.env) {
     const out = (s) => process.stdout.write(s + '\n');
     const err = (s) => process.stderr.write(s + '\n');
@@ -155,7 +218,13 @@ export async function main(argv, env = process.env) {
                 host: { type: 'string' },
                 title: { type: 'string' },
                 id: { type: 'string' },
+                icon: { type: 'string' },
                 since: { type: 'string' },
+                open: { type: 'boolean', default: false },
+                as: { type: 'string' },
+                reopen: { type: 'boolean', default: false },
+                interval: { type: 'string' },
+                once: { type: 'boolean', default: false },
                 help: { type: 'boolean', short: 'h', default: false },
             },
         });
@@ -166,7 +235,7 @@ export async function main(argv, env = process.env) {
         return 1;
     }
     const { values, positionals } = parsed;
-    const [command, arg] = positionals;
+    const [command, arg, arg2, arg3] = positionals;
     const json = values.json === true;
     try {
         switch (command) {
@@ -189,7 +258,7 @@ export async function main(argv, env = process.env) {
                     openBrowser(start.verify_url);
                 const deadline = Date.now() + start.expires_in * 1000;
                 while (Date.now() < deadline) {
-                    await sleep(start.interval * 1000);
+                    await sleep(start.interval * 1000, env);
                     const poll = await fetch(`${host}/api/device/poll`, {
                         method: 'POST',
                         headers: { 'content-type': 'application/json' },
@@ -223,20 +292,25 @@ export async function main(argv, env = process.env) {
             }
             case 'publish': {
                 if (!arg)
-                    throw new CliError('usage: shartifacts publish <file.html> [--title T] [--id ID]', 1);
+                    throw new CliError(PUBLISH_USAGE, 1);
                 const config = await requireConfig(env);
-                const html = await readFile(arg, 'utf8').catch(() => {
+                const content = await readFile(arg, 'utf8').catch(() => {
                     throw new CliError(`cannot read ${arg}`, 1);
                 });
+                const markdown = ['.md', '.markdown'].includes(extname(arg).toLowerCase());
                 // An update sends a title only when one was asked for; otherwise the
-                // server keeps the title the page already has.
-                const body = { html };
+                // server keeps the title the page already has. On create, markdown
+                // titles come from the first `# heading` server-side, so only html
+                // derives one here.
+                const body = markdown ? { markdown: content } : { html: content };
                 if (values.id)
                     body.id = values.id;
+                if (values.icon)
+                    body.icon = values.icon;
                 if (values.title)
                     body.title = values.title;
-                else if (!values.id)
-                    body.title = titleFromHtml(html, basename(arg));
+                else if (!values.id && !markdown)
+                    body.title = titleFromHtml(content, basename(arg));
                 const { data } = await api(config, 'POST', '/api/publish', body);
                 out(format(data, json));
                 return 0;
@@ -250,7 +324,7 @@ export async function main(argv, env = process.env) {
                     out('no artifacts yet');
                 else
                     for (const a of data.artifacts)
-                        out(`${a.id}  ${a.title}  ${a.url}  ${a.comments} comments`);
+                        out(`${a.id}  ${a.title}  ${a.url}  ${a.comments} comments, ${a.open} open`);
                 return 0;
             }
             case 'delete': {
@@ -263,15 +337,18 @@ export async function main(argv, env = process.env) {
             }
             case 'comments': {
                 if (!arg)
-                    throw new CliError('usage: shartifacts comments <id> [--since ISO]', 1);
+                    throw new CliError('usage: shartifacts comments <id> [--since ISO] [--open]', 1);
                 const config = await requireConfig(env);
-                let query = '';
+                const params = new URLSearchParams();
                 if (values.since) {
                     const t = Math.floor(Date.parse(values.since) / 1000);
                     if (!Number.isFinite(t))
                         throw new CliError('--since must be an ISO date', 1);
-                    query = `?since=${t}`;
+                    params.set('since', String(t));
                 }
+                if (values.open)
+                    params.set('open', '1');
+                const query = params.toString() ? `?${params.toString()}` : '';
                 const { data } = await api(config, 'GET', `/api/c/${encodeURIComponent(arg)}${query}`);
                 if (json) {
                     out(JSON.stringify(data));
@@ -282,17 +359,99 @@ export async function main(argv, env = process.env) {
                     return 0;
                 }
                 const when = (t) => new Date(t * 1000).toISOString();
+                const owner = (b) => (b ? ' [owner]' : '');
                 for (const t of data.threads) {
-                    out(`#${t.id} ${t.author} ${when(t.created_at)}${t.resolved ? ' [resolved]' : ''}`);
+                    out(`#${t.id} ${t.author}${owner(t.owner)} ${when(t.created_at)}${t.resolved ? ' [resolved]' : ''}`);
                     if (t.quote)
                         out(`  > ${t.quote}`);
                     out(`  ${t.body}`);
                     for (const r of t.replies)
-                        out(`    ↳ ${r.author} ${when(r.created_at)}: ${r.body}`);
+                        out(`    ↳ ${r.author}${owner(r.owner)} ${when(r.created_at)}: ${r.body}`);
                     out('');
                 }
                 return 0;
             }
+            case 'comment': {
+                if (!arg || arg2 === undefined)
+                    throw new CliError(COMMENT_USAGE, 1);
+                const config = await requireConfig(env);
+                const body = { body: arg2 };
+                if (values.as)
+                    body.author = values.as;
+                const { data } = await api(config, 'POST', `/api/c/${encodeURIComponent(arg)}`, body);
+                out(json ? JSON.stringify(data.comment) : `commented #${data.comment.id}`);
+                return 0;
+            }
+            case 'reply': {
+                if (!arg || arg3 === undefined)
+                    throw new CliError(REPLY_USAGE, 1);
+                const thread = requireThreadId(arg2, REPLY_USAGE);
+                const config = await requireConfig(env);
+                const body = { body: arg3, thread };
+                if (values.as)
+                    body.author = values.as;
+                const { data } = await api(config, 'POST', `/api/c/${encodeURIComponent(arg)}`, body);
+                out(json ? JSON.stringify(data.comment) : `replied to #${thread}`);
+                return 0;
+            }
+            case 'resolve': {
+                if (!arg)
+                    throw new CliError(RESOLVE_USAGE, 1);
+                const thread = requireThreadId(arg2, RESOLVE_USAGE);
+                const config = await requireConfig(env);
+                const resolved = !values.reopen;
+                const { data } = await api(config, 'PATCH', `/api/c/${encodeURIComponent(arg)}/${thread}`, { resolved });
+                out(json ? JSON.stringify(data) : `${resolved ? 'resolved' : 'reopened'} #${thread}`);
+                return 0;
+            }
+            case 'watch': {
+                if (!arg)
+                    throw new CliError(WATCH_USAGE, 1);
+                const config = await requireConfig(env);
+                let since = Math.floor(Date.now() / 1000);
+                if (values.since) {
+                    since = Math.floor(Date.parse(values.since) / 1000);
+                    if (!Number.isFinite(since))
+                        throw new CliError('--since must be an ISO date', 1);
+                }
+                let interval = 15;
+                if (values.interval) {
+                    interval = Number(values.interval);
+                    if (!Number.isFinite(interval))
+                        throw new CliError('--interval must be a number', 1);
+                }
+                interval = Math.max(5, interval);
+                const seen = new Set();
+                let failures = 0;
+                for (;;) {
+                    try {
+                        const { data } = await api(config, 'GET', `/api/c/${encodeURIComponent(arg)}?since=${since}`);
+                        const { events, maxCreatedAt } = newCommentEvents(data.threads, seen, since);
+                        for (const e of events) {
+                            if (json)
+                                out(JSON.stringify(e));
+                            else
+                                printCommentEvent(out, e);
+                        }
+                        if (maxCreatedAt > since)
+                            since = maxCreatedAt;
+                        failures = 0;
+                    }
+                    catch (e) {
+                        if (e instanceof CliError && e.code === 2)
+                            throw e;
+                        failures++;
+                        err(`poll failed: ${e.message}`);
+                        // A one-off blip should keep polling, but a stuck cause (deleted
+                        // id, bad --since, DNS down) shouldn't retry forever.
+                        if (failures >= 5)
+                            throw e;
+                    }
+                    if (values.once)
+                        return 0;
+                    await sleep(interval * 1000, env);
+                }
+            }
             case 'rules':
                 out(json ? JSON.stringify({ rules: RULES.trim() }) : RULES.trimEnd());
                 return 0;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "shartifacts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Publish an HTML page to shartifacts from any agent's shell.",
   "type": "module",
   "bin": { "shartifacts": "dist/bin.js" },
-  "files": ["dist"],
+  "files": ["dist", "README.md"],
   "engines": { "node": ">=20" },
   "scripts": {
     "build": "tsc -p tsconfig.json",