liveog 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +137 -2
- package/dist/browser.d.ts +6 -0
- package/dist/browser.js +27 -0
- package/dist/check.d.ts +20 -0
- package/dist/check.js +106 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +53 -0
- package/dist/cover.d.ts +38 -0
- package/dist/cover.js +66 -0
- package/dist/draw.d.ts +12 -0
- package/dist/draw.js +43 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +5 -0
- package/dist/install.d.ts +26 -0
- package/dist/install.js +85 -0
- package/dist/links.d.ts +32 -0
- package/dist/links.js +32 -0
- package/dist/mcp.d.ts +18 -0
- package/dist/mcp.js +213 -0
- package/dist/og.d.ts +24 -0
- package/dist/og.js +44 -0
- package/dist/study.d.ts +31 -0
- package/dist/study.js +161 -0
- package/dist/template.d.ts +21 -0
- package/dist/template.js +35 -0
- package/package.json +57 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bilal Abraham
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,138 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
|
|
4
|
+
<img src=".github/logo-light.svg" alt="liveog" width="177" height="40">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<p align="center">
|
|
9
|
+
Link previews that stay current.<br>
|
|
10
|
+
<a href="https://bilal-abraham.github.io/liveog/">Website</a> · <a href="https://www.npmjs.com/package/liveog">npm</a> · MIT
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
When someone pastes your link into iMessage, Slack, X or WhatsApp, the app shows a preview card.
|
|
16
|
+
liveog makes that card show **what is true right now**: who is going, the current bid, how close
|
|
17
|
+
the fundraiser is. And it does it without an image server.
|
|
18
|
+
|
|
19
|
+
- **Covers drawn in a browser**: your Chrome at build time, or your user's open page at run time.
|
|
20
|
+
Your server only stores a PNG.
|
|
21
|
+
- **Always fresh**: every new picture gets a new address, so a link shared again never shows a
|
|
22
|
+
stale, cached image.
|
|
23
|
+
- **Private links stay private**: invite codes and share tokens never show in a preview, and those
|
|
24
|
+
pages stay out of search engines and caches.
|
|
25
|
+
- **Zero dependencies**, ESM. Works on Node 22+, Deno, Bun, Cloudflare Workers and Vercel.
|
|
26
|
+
|
|
27
|
+
## Quick start
|
|
28
|
+
|
|
29
|
+
### Let your agent do it
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
npx liveog mcp add
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
This finds the agent apps on your machine and adds the liveog MCP server to each one: Hermes
|
|
36
|
+
Agent, Claude Code, Codex, Cursor, VS Code, Amp, Windsurf (Devin Desktop), Claude Desktop, OpenCode,
|
|
37
|
+
Kiro and LM Studio. Antigravity, Zed, JetBrains, Cline, Warp, Goose, Continue and Kilo Code work
|
|
38
|
+
too, with one step by hand (see below). Restart the app, then ask:
|
|
39
|
+
|
|
40
|
+
> Set up link previews for this project.
|
|
41
|
+
|
|
42
|
+
The agent studies your project (colours, fonts, logo, routes), asks you which links matter, draws
|
|
43
|
+
two or three cover ideas for you to pick from, wires in the code, and checks the result.
|
|
44
|
+
|
|
45
|
+
### Or do it yourself
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
npm i liveog
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
import { links, originOf } from 'liveog';
|
|
53
|
+
|
|
54
|
+
// 1. Say what kinds of link you have. First match wins; the last argument is the fallback.
|
|
55
|
+
const site = links('yoursite', [
|
|
56
|
+
{ name: 'invite', match: (p) => p.startsWith('/join/'), private: true,
|
|
57
|
+
title: 'Join the team', description: 'On yoursite.', cover: '/og/invite.png' },
|
|
58
|
+
], { name: 'home', title: 'yoursite', description: 'What it does.', cover: '/og/home.png' });
|
|
59
|
+
|
|
60
|
+
// 2. Wherever your server sends an HTML page:
|
|
61
|
+
const origin = originOf(req.headers.host, process.env.SITE); // SITE = your public domain
|
|
62
|
+
for (const [k, v] of Object.entries(site.headers(path))) res.setHeader(k, v);
|
|
63
|
+
res.end(site.page(html, path, origin));
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Then draw the covers once and commit them:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npx liveog cover "yoursite" public/og/home.png # the built-in cover, black and white
|
|
70
|
+
npx liveog draw cover.html public/og/home.png # or your own 1200 x 630 HTML page
|
|
71
|
+
npx liveog check https://yoursite.com/ # see what a chat app will show
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Static site? Call `tags(card)` at build time and paste the result into each page's `<head>`.
|
|
75
|
+
|
|
76
|
+
## Covers that change
|
|
77
|
+
|
|
78
|
+
For links whose picture should change (an invite filling up, a price, a bid), the page that has
|
|
79
|
+
the thing open draws the cover and sends it to your server:
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
// In the browser
|
|
83
|
+
import { drawCover, sendCover } from 'liveog/browser';
|
|
84
|
+
const png = await drawCover((ctx, w, h) => { /* draw on a 1200 x 630 canvas */ });
|
|
85
|
+
await sendCover('/api/invites/42/cover', png);
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
// On your server
|
|
90
|
+
import { isCover, nextCover, coverPath, parseCoverPath, answer } from 'liveog';
|
|
91
|
+
|
|
92
|
+
if (!isCover(bytes)) return reply(400); // must be a 1200 x 630 PNG under 300 KB
|
|
93
|
+
invite.cover = nextCover(invite.cover); // same id, version + 1
|
|
94
|
+
save(bytes); // the link's preview image is coverPath(invite.cover)
|
|
95
|
+
|
|
96
|
+
// GET /c/<id>/<version>.png
|
|
97
|
+
const a = answer(parseCoverPath(path), invite.cover); // 200, a 302 to the newest, or 404
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
If a private link is stopped or replaced, call `nextCover(cover, true)`: it makes a new id, and the
|
|
101
|
+
old picture's address stops working.
|
|
102
|
+
|
|
103
|
+
There is always a fallback: until a link has its own cover, it shows its kind's generic one.
|
|
104
|
+
|
|
105
|
+
## Any other MCP client
|
|
106
|
+
|
|
107
|
+
liveog's MCP server speaks the standard protocol over stdin/stdout. Point your client at:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{ "mcpServers": { "liveog": { "command": "npx", "args": ["-y", "liveog", "mcp"] } } }
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Its tools:
|
|
114
|
+
|
|
115
|
+
| Tool | What it does |
|
|
116
|
+
|---|---|
|
|
117
|
+
| `study_project` | reads your project's colours, fonts, logo files, routes and existing previews |
|
|
118
|
+
| `draw_cover` | draws a 1200 x 630 cover and shows it to the agent |
|
|
119
|
+
| `setup_project` | the code to wire liveog into your server |
|
|
120
|
+
| `check_link` | fetches a live link the way a chat app does and reports what's wrong |
|
|
121
|
+
|
|
122
|
+
## API
|
|
123
|
+
|
|
124
|
+
| Import | |
|
|
125
|
+
|---|---|
|
|
126
|
+
| `tags(card)`, `inject(html, tags)` | the meta tags, and putting them before `</head>` |
|
|
127
|
+
| `links(site, kinds, fallback)` | `.page()`, `.headers()`, `.card()` and `.of()` for a path |
|
|
128
|
+
| `originOf(host, site?)`, `cleanHost(x)` | a safe absolute origin for image addresses |
|
|
129
|
+
| `coverHtml(words, look?)` | the built-in cover as HTML (site, tag, title, line, picture) |
|
|
130
|
+
| `isCover`, `imageSize` | checks a PNG's size without decoding it |
|
|
131
|
+
| `nextCover`, `coverPath`, `parseCoverPath`, `answer` | versioned cover addresses |
|
|
132
|
+
| `check`, `describe`, `readTags` | the link checker |
|
|
133
|
+
| `liveog/draw` | `draw(page, out)` with your local Chrome (Node only) |
|
|
134
|
+
| `liveog/browser` | `drawCover`, `sendCover` for the user's page |
|
|
135
|
+
|
|
136
|
+
## License
|
|
137
|
+
|
|
138
|
+
MIT
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
type Ctx = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
|
|
2
|
+
/** Draw on a 1200 x 630 canvas and get it back as a PNG. */
|
|
3
|
+
export declare function drawCover(draw: (ctx: Ctx, width: number, height: number) => void | Promise<void>): Promise<Blob>;
|
|
4
|
+
/** Send a cover to your server as the raw PNG; its answer is returned as it came. */
|
|
5
|
+
export declare function sendCover(url: string, png: Blob, init?: RequestInit): Promise<Response>;
|
|
6
|
+
export {};
|
package/dist/browser.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// Drawing a cover in a page your user already has open: a 1200 x 630 canvas, as a PNG, sent to
|
|
2
|
+
// your server. The server only checks it (isCover) and keeps it.
|
|
3
|
+
const W = 1200;
|
|
4
|
+
const H = 630;
|
|
5
|
+
/** Draw on a 1200 x 630 canvas and get it back as a PNG. */
|
|
6
|
+
export async function drawCover(draw) {
|
|
7
|
+
if (typeof OffscreenCanvas !== 'undefined') {
|
|
8
|
+
const c = new OffscreenCanvas(W, H);
|
|
9
|
+
const ctx = c.getContext('2d');
|
|
10
|
+
if (!ctx)
|
|
11
|
+
throw new Error('liveog: no 2d canvas here');
|
|
12
|
+
await draw(ctx, W, H);
|
|
13
|
+
return c.convertToBlob({ type: 'image/png' });
|
|
14
|
+
}
|
|
15
|
+
const c = Object.assign(document.createElement('canvas'), { width: W, height: H });
|
|
16
|
+
const ctx = c.getContext('2d');
|
|
17
|
+
if (!ctx)
|
|
18
|
+
throw new Error('liveog: no 2d canvas here');
|
|
19
|
+
await draw(ctx, W, H);
|
|
20
|
+
return new Promise((ok, no) => c.toBlob((b) => (b ? ok(b) : no(new Error('liveog: the canvas gave no PNG'))), 'image/png'));
|
|
21
|
+
}
|
|
22
|
+
/** Send a cover to your server as the raw PNG; its answer is returned as it came. */
|
|
23
|
+
export function sendCover(url, png, init = {}) {
|
|
24
|
+
const headers = new Headers(init.headers);
|
|
25
|
+
headers.set('content-type', 'image/png');
|
|
26
|
+
return fetch(url, { ...init, method: 'POST', headers, body: png });
|
|
27
|
+
}
|
package/dist/check.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** The og: and twitter: tags of a page (the first of each name), read from its <meta>s. */
|
|
2
|
+
export declare function readTags(html: string): Record<string, string>;
|
|
3
|
+
export interface Report {
|
|
4
|
+
url: string;
|
|
5
|
+
status: number;
|
|
6
|
+
tags: Record<string, string>;
|
|
7
|
+
image: {
|
|
8
|
+
url: string;
|
|
9
|
+
status: number;
|
|
10
|
+
type: string | null;
|
|
11
|
+
width?: number;
|
|
12
|
+
height?: number;
|
|
13
|
+
bytes: number;
|
|
14
|
+
} | null;
|
|
15
|
+
problems: string[];
|
|
16
|
+
}
|
|
17
|
+
/** Fetch a link as a preview bot would and say what its preview shows and what is wrong with it. */
|
|
18
|
+
export declare function check(url: string, f?: typeof fetch): Promise<Report>;
|
|
19
|
+
/** A report as plain lines. */
|
|
20
|
+
export declare function describe(r: Report): string;
|
package/dist/check.js
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
// Checking a link's preview as an app would see it: the page's tags, then its image.
|
|
2
|
+
import { imageSize } from './cover.js';
|
|
3
|
+
import { COVER_SIZE } from './og.js';
|
|
4
|
+
const ATTR = /([A-Za-z:_-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g;
|
|
5
|
+
const UNESC = { '&': '&', '<': '<', '>': '>', '"': '"', ''': "'", ''': "'" };
|
|
6
|
+
const unesc = (s) => s.replace(/&(amp|lt|gt|quot|#39|#x27);/g, (e) => UNESC[e] ?? e);
|
|
7
|
+
/** The og: and twitter: tags of a page (the first of each name), read from its <meta>s. */
|
|
8
|
+
export function readTags(html) {
|
|
9
|
+
const out = {};
|
|
10
|
+
for (const [m] of html.matchAll(/<meta\b[^>]*>/gi)) {
|
|
11
|
+
const a = {};
|
|
12
|
+
for (const x of m.matchAll(ATTR))
|
|
13
|
+
if (x[1])
|
|
14
|
+
a[x[1].toLowerCase()] = unesc(x[2] ?? x[3] ?? x[4] ?? '');
|
|
15
|
+
const key = (a.property ?? a.name ?? '').toLowerCase();
|
|
16
|
+
if (/^(og|twitter):/.test(key) && a.content !== undefined && !(key in out))
|
|
17
|
+
out[key] = a.content;
|
|
18
|
+
}
|
|
19
|
+
return out;
|
|
20
|
+
}
|
|
21
|
+
const PAGE_MAX = 2 * 1024 * 1024;
|
|
22
|
+
const IMAGE_MAX = 8 * 1024 * 1024;
|
|
23
|
+
const BIG = 5 * 1024 * 1024;
|
|
24
|
+
// a body read up to max bytes (more is cut off), so a huge answer is never held
|
|
25
|
+
async function body(res, max) {
|
|
26
|
+
const parts = [];
|
|
27
|
+
let n = 0;
|
|
28
|
+
const r = res.body?.getReader();
|
|
29
|
+
while (r) {
|
|
30
|
+
const { done, value } = await r.read();
|
|
31
|
+
if (done)
|
|
32
|
+
break;
|
|
33
|
+
parts.push(value);
|
|
34
|
+
n += value.length;
|
|
35
|
+
if (n > max) {
|
|
36
|
+
await r.cancel();
|
|
37
|
+
break;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
const out = new Uint8Array(n);
|
|
41
|
+
let at = 0;
|
|
42
|
+
for (const p of parts) {
|
|
43
|
+
out.set(p, at);
|
|
44
|
+
at += p.length;
|
|
45
|
+
}
|
|
46
|
+
return out;
|
|
47
|
+
}
|
|
48
|
+
const get = (url, f) => f(url, { redirect: 'follow', signal: AbortSignal.timeout(10_000), headers: { 'user-agent': 'liveog (link preview check)' } });
|
|
49
|
+
/** Fetch a link as a preview bot would and say what its preview shows and what is wrong with it. */
|
|
50
|
+
export async function check(url, f = globalThis.fetch) {
|
|
51
|
+
const problems = [];
|
|
52
|
+
const res = await get(url, f);
|
|
53
|
+
const html = new TextDecoder().decode(await body(res, PAGE_MAX));
|
|
54
|
+
const tags = readTags(html);
|
|
55
|
+
const r = { url, status: res.status, tags, image: null, problems };
|
|
56
|
+
if (!res.ok)
|
|
57
|
+
problems.push(`The page answered ${res.status}.`);
|
|
58
|
+
for (const k of ['og:title', 'og:description', 'og:image'])
|
|
59
|
+
if (!tags[k])
|
|
60
|
+
problems.push(`No ${k}.`);
|
|
61
|
+
const src = tags['og:image'] ?? tags['twitter:image'];
|
|
62
|
+
if (!src)
|
|
63
|
+
return r;
|
|
64
|
+
if (tags['twitter:card'] !== 'summary_large_image')
|
|
65
|
+
problems.push('twitter:card is not summary_large_image, so X shows a small card.');
|
|
66
|
+
let abs;
|
|
67
|
+
try {
|
|
68
|
+
abs = new URL(src);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
problems.push(`The image address is not absolute: ${src}`);
|
|
72
|
+
return r;
|
|
73
|
+
}
|
|
74
|
+
if (abs.protocol !== 'https:')
|
|
75
|
+
problems.push('The image is not on https: some apps will not show it.');
|
|
76
|
+
const ir = await get(abs.href, f);
|
|
77
|
+
const bytes = await body(ir, IMAGE_MAX);
|
|
78
|
+
const size = imageSize(bytes);
|
|
79
|
+
r.image = { url: abs.href, status: ir.status, type: size?.type ?? ir.headers.get('content-type'), bytes: bytes.length, ...(size ? { width: size.width, height: size.height } : {}) };
|
|
80
|
+
if (!ir.ok) {
|
|
81
|
+
problems.push(`The image answered ${ir.status}.`);
|
|
82
|
+
return r;
|
|
83
|
+
}
|
|
84
|
+
if (bytes.length > BIG)
|
|
85
|
+
problems.push('The image is over 5 MB: some apps skip it.');
|
|
86
|
+
if (!size)
|
|
87
|
+
problems.push('The image is not a PNG, JPEG or GIF this could read.');
|
|
88
|
+
else if (size.width !== COVER_SIZE[0] || size.height !== COVER_SIZE[1])
|
|
89
|
+
problems.push(`The image is ${size.width} x ${size.height}, not ${COVER_SIZE.join(' x ')}.`);
|
|
90
|
+
if (size && tags['og:image:width'] && Number(tags['og:image:width']) !== size.width)
|
|
91
|
+
problems.push('og:image:width is not the image\'s width.');
|
|
92
|
+
if (size && tags['og:image:height'] && Number(tags['og:image:height']) !== size.height)
|
|
93
|
+
problems.push('og:image:height is not the image\'s height.');
|
|
94
|
+
return r;
|
|
95
|
+
}
|
|
96
|
+
/** A report as plain lines. */
|
|
97
|
+
export function describe(r) {
|
|
98
|
+
const t = r.tags;
|
|
99
|
+
const lines = [`${r.url} (${r.status})`, ` title ${t['og:title'] ?? '-'}`, ` description ${t['og:description'] ?? '-'}`];
|
|
100
|
+
if (r.image)
|
|
101
|
+
lines.push(` image ${r.image.url} ${r.image.width ? `${r.image.width} x ${r.image.height}` : '?'} ${r.image.type ?? '?'} ${Math.ceil(r.image.bytes / 1024)} KB`);
|
|
102
|
+
else
|
|
103
|
+
lines.push(` image ${t['og:image'] ?? '-'}`);
|
|
104
|
+
lines.push(r.problems.length ? r.problems.map((p) => ` ! ${p}`).join('\n') : ' ok');
|
|
105
|
+
return lines.join('\n');
|
|
106
|
+
}
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { check, describe } from './check.js';
|
|
3
|
+
import { draw } from './draw.js';
|
|
4
|
+
import { addEverywhere, report } from './install.js';
|
|
5
|
+
import { serve } from './mcp.js';
|
|
6
|
+
import { coverHtml } from './template.js';
|
|
7
|
+
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
8
|
+
import { tmpdir } from 'node:os';
|
|
9
|
+
import { join } from 'node:path';
|
|
10
|
+
const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
11
|
+
const USAGE = `liveog ${version}
|
|
12
|
+
liveog draw <page.html|url> <out.png> draw a 1200 x 630 cover with this machine's Chrome
|
|
13
|
+
liveog cover <title> <out.png> [site] the default cover, black, white and grey
|
|
14
|
+
liveog check <url> what a link's preview shows, and what is wrong
|
|
15
|
+
liveog mcp add add the MCP server to every agent app here
|
|
16
|
+
liveog mcp the MCP server, on stdio`;
|
|
17
|
+
const [cmd, a, b, c] = process.argv.slice(2);
|
|
18
|
+
try {
|
|
19
|
+
if (cmd === 'draw' && a && b) {
|
|
20
|
+
const s = draw(a, b);
|
|
21
|
+
console.log(`${b} ${s.width} x ${s.height}`);
|
|
22
|
+
}
|
|
23
|
+
else if (cmd === 'cover' && a && b) {
|
|
24
|
+
const dir = mkdtempSync(join(tmpdir(), 'liveog-'));
|
|
25
|
+
try {
|
|
26
|
+
writeFileSync(join(dir, 'cover.html'), coverHtml(c ? { title: a, site: c } : { title: a }));
|
|
27
|
+
const s = draw(join(dir, 'cover.html'), b);
|
|
28
|
+
console.log(`${b} ${s.width} x ${s.height}`);
|
|
29
|
+
}
|
|
30
|
+
finally {
|
|
31
|
+
rmSync(dir, { recursive: true, force: true });
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
else if (cmd === 'check' && a) {
|
|
35
|
+
const r = await check(a);
|
|
36
|
+
console.log(describe(r));
|
|
37
|
+
process.exitCode = r.problems.length ? 1 : 0;
|
|
38
|
+
}
|
|
39
|
+
else if (cmd === 'mcp' && a === 'add') {
|
|
40
|
+
console.log(report(addEverywhere()));
|
|
41
|
+
}
|
|
42
|
+
else if (cmd === 'mcp' && !a) {
|
|
43
|
+
serve(version);
|
|
44
|
+
}
|
|
45
|
+
else {
|
|
46
|
+
console.log(USAGE);
|
|
47
|
+
process.exitCode = cmd === undefined || cmd === 'help' || cmd === '--help' ? 0 : 2;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
catch (e) {
|
|
51
|
+
console.error(e.message);
|
|
52
|
+
process.exitCode = 1;
|
|
53
|
+
}
|
package/dist/cover.d.ts
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/** The most a cover may weigh. */
|
|
2
|
+
export declare const MAX_BYTES: number;
|
|
3
|
+
/** An image's type and its width and height, read from its header (PNG, JPEG, GIF), or null. */
|
|
4
|
+
export declare function imageSize(b: Uint8Array): {
|
|
5
|
+
type: 'png' | 'jpeg' | 'gif';
|
|
6
|
+
width: number;
|
|
7
|
+
height: number;
|
|
8
|
+
} | null;
|
|
9
|
+
/** A PNG your server may keep as a cover: the signature, IHDR first, 1200 x 630, at most MAX_BYTES. */
|
|
10
|
+
export declare function isCover(b: Uint8Array): boolean;
|
|
11
|
+
/** A cover as you keep it: a random id made for it and nothing else, and its version. */
|
|
12
|
+
export interface Cover {
|
|
13
|
+
id: string;
|
|
14
|
+
v: number;
|
|
15
|
+
}
|
|
16
|
+
export declare const COVER_ID: RegExp;
|
|
17
|
+
export declare function newCoverId(): string;
|
|
18
|
+
export declare const coverPath: (c: Cover) => string;
|
|
19
|
+
/** The cover after a new picture: the same id one version up, or a new id at 1 when fresh (or none before). */
|
|
20
|
+
export declare const nextCover: (prev: Cover | null | undefined, fresh?: boolean) => Cover;
|
|
21
|
+
/** The id and version a cover address names, or null. */
|
|
22
|
+
export declare function parseCoverPath(path: string): Cover | null;
|
|
23
|
+
/** Headers for a cover's picture: a version never changes, but an hour, so a stopped link is not shown for long. */
|
|
24
|
+
export declare const COVER_HEADERS: Readonly<Record<string, string>>;
|
|
25
|
+
export type Answer = {
|
|
26
|
+
status: 200;
|
|
27
|
+
headers: Record<string, string>;
|
|
28
|
+
} | {
|
|
29
|
+
status: 302;
|
|
30
|
+
location: string;
|
|
31
|
+
} | {
|
|
32
|
+
status: 404;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* What to answer at a cover address, given the cover its id is now (null when it is nothing:
|
|
36
|
+
* never made, stopped, replaced, deleted). The newest version is sent, an older one redirected.
|
|
37
|
+
*/
|
|
38
|
+
export declare function answer(asked: Cover | null, now: Cover | null): Answer;
|
package/dist/cover.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// Covers: PNGs a browser drew (yours at build time, your user's at run time), checked and kept by
|
|
2
|
+
// your server, served at versioned addresses: /c/<id>/<v>.png. v goes up with each new picture,
|
|
3
|
+
// so a link pasted again names one no app has cached; an older v is sent to the newest; a new id
|
|
4
|
+
// ends the old picture's address (a share link stopped or replaced).
|
|
5
|
+
import { COVER_SIZE } from './og.js';
|
|
6
|
+
/** The most a cover may weigh. */
|
|
7
|
+
export const MAX_BYTES = 300 * 1024;
|
|
8
|
+
const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
|
|
9
|
+
const u16 = (b, i) => ((b[i] ?? 0) << 8) | (b[i + 1] ?? 0);
|
|
10
|
+
const u32 = (b, i) => ((u16(b, i) << 16) >>> 0) + u16(b, i + 2);
|
|
11
|
+
/** An image's type and its width and height, read from its header (PNG, JPEG, GIF), or null. */
|
|
12
|
+
export function imageSize(b) {
|
|
13
|
+
if (b.length >= 24 && PNG.every((x, i) => b[i] === x) && String.fromCharCode(...b.subarray(12, 16)) === 'IHDR')
|
|
14
|
+
return { type: 'png', width: u32(b, 16), height: u32(b, 20) };
|
|
15
|
+
if (b.length >= 10 && String.fromCharCode(...b.subarray(0, 4)) === 'GIF8')
|
|
16
|
+
return { type: 'gif', width: (b[6] ?? 0) | ((b[7] ?? 0) << 8), height: (b[8] ?? 0) | ((b[9] ?? 0) << 8) };
|
|
17
|
+
if (b[0] === 0xff && b[1] === 0xd8) {
|
|
18
|
+
// walk the segments to the frame header (SOF0..SOF15, not DHT, JPG or DAC)
|
|
19
|
+
let i = 2;
|
|
20
|
+
while (i + 9 < b.length) {
|
|
21
|
+
if (b[i] !== 0xff)
|
|
22
|
+
return null;
|
|
23
|
+
const m = b[i + 1] ?? 0;
|
|
24
|
+
if (m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc)
|
|
25
|
+
return { type: 'jpeg', width: u16(b, i + 7), height: u16(b, i + 5) };
|
|
26
|
+
i += 2 + u16(b, i + 2);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return null;
|
|
30
|
+
}
|
|
31
|
+
/** A PNG your server may keep as a cover: the signature, IHDR first, 1200 x 630, at most MAX_BYTES. */
|
|
32
|
+
export function isCover(b) {
|
|
33
|
+
const s = b.length <= MAX_BYTES ? imageSize(b) : null;
|
|
34
|
+
return s?.type === 'png' && s.width === COVER_SIZE[0] && s.height === COVER_SIZE[1];
|
|
35
|
+
}
|
|
36
|
+
export const COVER_ID = /^[A-Za-z0-9_-]{22}$/;
|
|
37
|
+
// 16 random bytes, base64url: Web Crypto, so it runs in Node, Deno, Bun, workers and browsers alike
|
|
38
|
+
export function newCoverId() {
|
|
39
|
+
const b = crypto.getRandomValues(new Uint8Array(16));
|
|
40
|
+
return btoa(String.fromCharCode(...b)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
|
|
41
|
+
}
|
|
42
|
+
export const coverPath = (c) => `/c/${c.id}/${c.v}.png`;
|
|
43
|
+
/** The cover after a new picture: the same id one version up, or a new id at 1 when fresh (or none before). */
|
|
44
|
+
export const nextCover = (prev, fresh = false) => !prev || fresh || !COVER_ID.test(prev.id) ? { id: newCoverId(), v: 1 } : { id: prev.id, v: prev.v + 1 };
|
|
45
|
+
/** The id and version a cover address names, or null. */
|
|
46
|
+
export function parseCoverPath(path) {
|
|
47
|
+
const m = /^\/c\/([A-Za-z0-9_-]{22})\/([1-9][0-9]{0,8})\.png$/.exec(path);
|
|
48
|
+
return m?.[1] && m[2] ? { id: m[1], v: Number(m[2]) } : null;
|
|
49
|
+
}
|
|
50
|
+
/** Headers for a cover's picture: a version never changes, but an hour, so a stopped link is not shown for long. */
|
|
51
|
+
export const COVER_HEADERS = Object.freeze({
|
|
52
|
+
'content-type': 'image/png',
|
|
53
|
+
'cache-control': 'public, max-age=3600',
|
|
54
|
+
'x-robots-tag': 'noindex',
|
|
55
|
+
});
|
|
56
|
+
/**
|
|
57
|
+
* What to answer at a cover address, given the cover its id is now (null when it is nothing:
|
|
58
|
+
* never made, stopped, replaced, deleted). The newest version is sent, an older one redirected.
|
|
59
|
+
*/
|
|
60
|
+
export function answer(asked, now) {
|
|
61
|
+
if (!asked || !now || asked.id !== now.id)
|
|
62
|
+
return { status: 404 };
|
|
63
|
+
if (asked.v !== now.v)
|
|
64
|
+
return { status: 302, location: coverPath(now) };
|
|
65
|
+
return { status: 200, headers: { ...COVER_HEADERS } };
|
|
66
|
+
}
|
package/dist/draw.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** This machine's Chrome: $CHROME, else the usual places, else null. */
|
|
2
|
+
export declare const findChrome: (env?: NodeJS.ProcessEnv) => string | null;
|
|
3
|
+
export interface DrawOptions {
|
|
4
|
+
chrome?: string;
|
|
5
|
+
width?: number;
|
|
6
|
+
height?: number;
|
|
7
|
+
}
|
|
8
|
+
/** Draw a page (a file or an address) to a PNG at out; throws when it is not the size asked for. */
|
|
9
|
+
export declare function draw(page: string, out: string, o?: DrawOptions): {
|
|
10
|
+
width: number;
|
|
11
|
+
height: number;
|
|
12
|
+
};
|
package/dist/draw.js
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// Drawing a cover with the Chrome already on this machine: headless, its own --screenshot, from a
|
|
2
|
+
// page on disk or an address. Nothing is installed or downloaded.
|
|
3
|
+
import { execFileSync } from 'node:child_process';
|
|
4
|
+
import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
|
|
5
|
+
import { tmpdir } from 'node:os';
|
|
6
|
+
import { join, resolve } from 'node:path';
|
|
7
|
+
import { pathToFileURL } from 'node:url';
|
|
8
|
+
import { imageSize } from './cover.js';
|
|
9
|
+
import { COVER_SIZE } from './og.js';
|
|
10
|
+
const PLACES = [
|
|
11
|
+
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
|
|
12
|
+
'/Applications/Chromium.app/Contents/MacOS/Chromium',
|
|
13
|
+
'/usr/bin/google-chrome',
|
|
14
|
+
'/usr/bin/google-chrome-stable',
|
|
15
|
+
'/usr/bin/chromium',
|
|
16
|
+
'/usr/bin/chromium-browser',
|
|
17
|
+
'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
|
|
18
|
+
];
|
|
19
|
+
/** This machine's Chrome: $CHROME, else the usual places, else null. */
|
|
20
|
+
export const findChrome = (env = process.env) => env.CHROME || PLACES.find((p) => existsSync(p)) || null;
|
|
21
|
+
/** Draw a page (a file or an address) to a PNG at out; throws when it is not the size asked for. */
|
|
22
|
+
export function draw(page, out, o = {}) {
|
|
23
|
+
const chrome = o.chrome ?? findChrome();
|
|
24
|
+
if (!chrome)
|
|
25
|
+
throw new Error('liveog: no Chrome found. Set CHROME to its path.');
|
|
26
|
+
const width = o.width ?? COVER_SIZE[0];
|
|
27
|
+
const height = o.height ?? COVER_SIZE[1];
|
|
28
|
+
const url = /^(https?|file):/i.test(page) ? page : pathToFileURL(resolve(page)).href;
|
|
29
|
+
const file = resolve(out);
|
|
30
|
+
const profile = mkdtempSync(join(tmpdir(), 'liveog-'));
|
|
31
|
+
try {
|
|
32
|
+
execFileSync(chrome, ['--headless=new', `--user-data-dir=${profile}`, '--no-first-run', '--hide-scrollbars',
|
|
33
|
+
'--force-device-scale-factor=1', `--window-size=${width},${height}`, '--virtual-time-budget=1000',
|
|
34
|
+
`--screenshot=${file}`, url], { stdio: 'ignore', timeout: 60_000 });
|
|
35
|
+
}
|
|
36
|
+
finally {
|
|
37
|
+
rmSync(profile, { recursive: true, force: true });
|
|
38
|
+
}
|
|
39
|
+
const got = imageSize(readFileSync(file));
|
|
40
|
+
if (got?.width !== width || got.height !== height)
|
|
41
|
+
throw new Error(`liveog: ${out} came out ${got ? `${got.width} x ${got.height}` : 'unreadable'}, not ${width} x ${height}`);
|
|
42
|
+
return { width, height };
|
|
43
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { COVER_SIZE, cleanHost, esc, inject, originOf, tags, type Card } from './og.js';
|
|
2
|
+
export { PRIVATE_HEADERS, links, type Kind, type Links, type Own } from './links.js';
|
|
3
|
+
export { COVER_HEADERS, COVER_ID, MAX_BYTES, answer, coverPath, imageSize, isCover, newCoverId, nextCover, parseCoverPath, type Answer, type Cover, } from './cover.js';
|
|
4
|
+
export { check, describe, readTags, type Report } from './check.js';
|
|
5
|
+
export { coverHtml, type CoverWords, type Look } from './template.js';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { COVER_SIZE, cleanHost, esc, inject, originOf, tags } from './og.js';
|
|
2
|
+
export { PRIVATE_HEADERS, links } from './links.js';
|
|
3
|
+
export { COVER_HEADERS, COVER_ID, MAX_BYTES, answer, coverPath, imageSize, isCover, newCoverId, nextCover, parseCoverPath, } from './cover.js';
|
|
4
|
+
export { check, describe, readTags } from './check.js';
|
|
5
|
+
export { coverHtml } from './template.js';
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export declare const SERVER: {
|
|
2
|
+
command: string;
|
|
3
|
+
args: string[];
|
|
4
|
+
};
|
|
5
|
+
export type Result = 'added' | 'already' | 'failed';
|
|
6
|
+
/** Add liveog under `key` (mcpServers for most apps) in an app's JSON file; the rest of the file is kept as it was. */
|
|
7
|
+
export declare function addToJson(file: string, key?: string, entry?: object): Result;
|
|
8
|
+
export interface Env {
|
|
9
|
+
home: string;
|
|
10
|
+
platform: NodeJS.Platform;
|
|
11
|
+
/** Is this command on the PATH? */
|
|
12
|
+
has(bin: string): boolean;
|
|
13
|
+
/** Run a command; its output, or a thrown error. */
|
|
14
|
+
run(bin: string, args: string[]): string;
|
|
15
|
+
}
|
|
16
|
+
export declare const realEnv: () => Env;
|
|
17
|
+
/** Each app found, and what happened. */
|
|
18
|
+
export declare function addEverywhere(env?: Env): {
|
|
19
|
+
app: string;
|
|
20
|
+
result: Result;
|
|
21
|
+
}[];
|
|
22
|
+
/** What to tell the person. */
|
|
23
|
+
export declare function report(found: {
|
|
24
|
+
app: string;
|
|
25
|
+
result: Result;
|
|
26
|
+
}[]): string;
|