shartifacts 0.1.0

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli.js

@@ -0,0 +1,328 @@
+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 { spawn } from 'node:child_process';
+export const DEFAULT_HOST = 'https://shartifacts.vercel.app';
+export const RULES = `## shartifacts
+
+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.
+- Update the same page: \`shartifacts publish page.html --id <id>\`.
+- Read feedback: \`shartifacts comments <id>\`.
+- 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.
+- One self-contained file. Pick the smallest visual that makes the point.
+`;
+const START = '<!-- shartifacts:start -->';
+const END = '<!-- shartifacts:end -->';
+export function initBlock(existing) {
+    const block = `${START}\n${RULES.trim()}\n${END}\n`;
+    const s = existing.indexOf(START);
+    const e = existing.indexOf(END);
+    if (s !== -1 && e !== -1 && e > s) {
+        return existing.slice(0, s) + block + existing.slice(e + END.length).replace(/^\n/, '');
+    }
+    const sep = existing === '' || existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    return existing + sep + block;
+}
+export function pickAgentsFile(dir) {
+    const agents = join(dir, 'AGENTS.md');
+    const claude = join(dir, 'CLAUDE.md');
+    if (existsSync(agents))
+        return agents;
+    if (existsSync(claude))
+        return claude;
+    return agents;
+}
+export function configPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME || join(env.HOME ?? '', '.config');
+    return join(base, 'shartifacts', 'config.json');
+}
+export async function readConfig(env = process.env) {
+    if (env.SHARTIFACTS_TOKEN) {
+        return {
+            host: (env.SHARTIFACTS_HOST || DEFAULT_HOST).replace(/\/$/, ''),
+            token: env.SHARTIFACTS_TOKEN,
+            login: '',
+        };
+    }
+    let config;
+    try {
+        config = JSON.parse(await readFile(configPath(env), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    config.host = (env.SHARTIFACTS_HOST || config.host).replace(/\/$/, '');
+    return config;
+}
+export async function writeConfig(config, env = process.env) {
+    const path = configPath(env);
+    await mkdir(join(path, '..'), { recursive: true, mode: 0o700 });
+    await writeFile(path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    // writeFile's mode only applies when it creates the file; force it on overwrite too.
+    await chmod(path, 0o600);
+}
+export function format(obj, json) {
+    if (json)
+        return JSON.stringify(obj);
+    return Object.entries(obj)
+        .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join('\n');
+}
+export function titleFromHtml(html, fallback) {
+    const m = /<title[^>]*>([^<]*)<\/title>/i.exec(html);
+    const t = m?.[1].trim();
+    return t || fallback;
+}
+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.
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+async function api(config, method, path, body) {
+    let res;
+    try {
+        res = await fetch(config.host + path, {
+            method,
+            headers: {
+                authorization: `Bearer ${config.token}`,
+                'content-type': 'application/json',
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new CliError(`cannot reach ${config.host}: ${err.message}`, 3);
+    }
+    const data = (res.status === 204 ? {} : await res.json().catch(() => ({})));
+    if (res.status === 401)
+        throw new CliError('not logged in. Run: shartifacts login', 2);
+    if (!res.ok)
+        throw new CliError(data.error ?? `${res.status} ${res.statusText}`, 3);
+    return { status: res.status, data };
+}
+function openBrowser(url) {
+    const cmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform() === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+    }
+    catch {
+        // Headless machine: the printed url is the fallback.
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function requireConfig(env) {
+    const config = await readConfig(env);
+    if (!config)
+        throw new CliError('not logged in. Run: shartifacts login', 2);
+    return config;
+}
+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
+  list                               my pages
+  delete <id>                        delete one of my pages
+  comments <id> [--since ISO]        read comments on one of my pages
+  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`;
+export async function main(argv, env = process.env) {
+    const out = (s) => process.stdout.write(s + '\n');
+    const err = (s) => process.stderr.write(s + '\n');
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                json: { type: 'boolean', default: false },
+                host: { type: 'string' },
+                title: { type: 'string' },
+                id: { type: 'string' },
+                since: { type: 'string' },
+                help: { type: 'boolean', short: 'h', default: false },
+            },
+        });
+    }
+    catch (e) {
+        err(e.message);
+        err(USAGE);
+        return 1;
+    }
+    const { values, positionals } = parsed;
+    const [command, arg] = positionals;
+    const json = values.json === true;
+    try {
+        switch (command) {
+            case 'login': {
+                const host = (values.host || env.SHARTIFACTS_HOST || DEFAULT_HOST).replace(/\/$/, '');
+                const startRes = await fetch(`${host}/api/device/start`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ label: hostname() }),
+                }).catch((e) => {
+                    throw new CliError(`cannot reach ${host}: ${e.message}`, 3);
+                });
+                const start = (await startRes.json().catch(() => ({})));
+                if (!startRes.ok)
+                    throw new CliError(start.error ?? `${startRes.status}`, 3);
+                err(`Open ${start.verify_url}`);
+                err(`and confirm the code: ${start.user_code}`);
+                // Only hand the OS a url the host we asked actually owns.
+                if (start.verify_url?.startsWith(host + '/'))
+                    openBrowser(start.verify_url);
+                const deadline = Date.now() + start.expires_in * 1000;
+                while (Date.now() < deadline) {
+                    await sleep(start.interval * 1000);
+                    const poll = await fetch(`${host}/api/device/poll`, {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json' },
+                        body: JSON.stringify({ poll_secret: start.poll_secret }),
+                    }).catch(() => null);
+                    if (!poll)
+                        continue;
+                    if (poll.status === 202)
+                        continue;
+                    if (poll.status === 410)
+                        throw new CliError('login expired, run `shartifacts login` again', 2);
+                    const data = (await poll.json());
+                    if (!poll.ok || !data.token || !data.login)
+                        throw new CliError(data.error ?? `${poll.status}`, 3);
+                    await writeConfig({ host, token: data.token, login: data.login }, env);
+                    out(json ? JSON.stringify({ login: data.login, host }) : `logged in as ${data.login}`);
+                    return 0;
+                }
+                throw new CliError('login expired, run `shartifacts login` again', 2);
+            }
+            case 'logout': {
+                await rm(configPath(env), { force: true });
+                out(format({ loggedOut: true }, json));
+                return 0;
+            }
+            case 'whoami': {
+                const config = await requireConfig(env);
+                const { data } = await api(config, 'GET', '/api/me');
+                out(format({ login: data.login, artifacts: data.artifacts, host: config.host }, json));
+                return 0;
+            }
+            case 'publish': {
+                if (!arg)
+                    throw new CliError('usage: shartifacts publish <file.html> [--title T] [--id ID]', 1);
+                const config = await requireConfig(env);
+                const html = await readFile(arg, 'utf8').catch(() => {
+                    throw new CliError(`cannot read ${arg}`, 1);
+                });
+                // An update sends a title only when one was asked for; otherwise the
+                // server keeps the title the page already has.
+                const body = { html };
+                if (values.id)
+                    body.id = values.id;
+                if (values.title)
+                    body.title = values.title;
+                else if (!values.id)
+                    body.title = titleFromHtml(html, basename(arg));
+                const { data } = await api(config, 'POST', '/api/publish', body);
+                out(format(data, json));
+                return 0;
+            }
+            case 'list': {
+                const config = await requireConfig(env);
+                const { data } = await api(config, 'GET', '/api/artifacts');
+                if (json)
+                    out(JSON.stringify(data));
+                else if (data.artifacts.length === 0)
+                    out('no artifacts yet');
+                else
+                    for (const a of data.artifacts)
+                        out(`${a.id}  ${a.title}  ${a.url}  ${a.comments} comments`);
+                return 0;
+            }
+            case 'delete': {
+                if (!arg)
+                    throw new CliError('usage: shartifacts delete <id>', 1);
+                const config = await requireConfig(env);
+                await api(config, 'DELETE', `/api/artifacts/${encodeURIComponent(arg)}`);
+                out(format({ deleted: arg }, json));
+                return 0;
+            }
+            case 'comments': {
+                if (!arg)
+                    throw new CliError('usage: shartifacts comments <id> [--since ISO]', 1);
+                const config = await requireConfig(env);
+                let query = '';
+                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}`;
+                }
+                const { data } = await api(config, 'GET', `/api/c/${encodeURIComponent(arg)}${query}`);
+                if (json) {
+                    out(JSON.stringify(data));
+                    return 0;
+                }
+                if (data.threads.length === 0) {
+                    out('no comments');
+                    return 0;
+                }
+                const when = (t) => new Date(t * 1000).toISOString();
+                for (const t of data.threads) {
+                    out(`#${t.id} ${t.author} ${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('');
+                }
+                return 0;
+            }
+            case 'rules':
+                out(json ? JSON.stringify({ rules: RULES.trim() }) : RULES.trimEnd());
+                return 0;
+            case 'init': {
+                const file = pickAgentsFile(process.cwd());
+                const existing = existsSync(file) ? await readFile(file, 'utf8') : '';
+                const next = initBlock(existing);
+                if (next === existing) {
+                    out(json ? JSON.stringify({ file, status: 'already present' }) : 'already present');
+                    return 0;
+                }
+                await writeFile(file, next);
+                out(format({ wrote: file }, json));
+                return 0;
+            }
+            default:
+                if (values.help) {
+                    out(USAGE);
+                    return 0;
+                }
+                err(USAGE);
+                return 1;
+        }
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            err(e.message);
+            return e.code;
+        }
+        err(e.message);
+        return 3;
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "shartifacts",
+  "version": "0.1.0",
+  "description": "Publish an HTML page to shartifacts from any agent's shell.",
+  "type": "module",
+  "bin": { "shartifacts": "dist/bin.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test src/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT"
+}