@gbti/ryker 0.1.1-rc.1 → 0.2.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/README.md +93 -9
- package/bin/ryker.js +125 -17
- package/drop-in/dist/ryker.js +4213 -885
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,12 +1,61 @@
|
|
|
1
1
|
# Ryker
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Inline editing for HTML and Markdown. Export your corrections as agent-ready
|
|
4
|
+
instructions a model can learn from.
|
|
5
|
+
|
|
6
|
+
Ryker is a Chrome extension for editing a document in place and recording every
|
|
7
|
+
change you make as a prompt-ready change request. A model can draft a report in
|
|
8
|
+
seconds. What it cannot do is know that the third section should have come
|
|
9
|
+
first, or that a summary buries its own conclusion. Those corrections are
|
|
10
|
+
structural and they are yours, and the usual place to make them is back in the
|
|
11
|
+
prompt, describing a document you are looking at but cannot touch.
|
|
12
|
+
|
|
13
|
+
## Why inline
|
|
14
|
+
|
|
15
|
+
HTML has become a useful format for delivering rich content when working with
|
|
16
|
+
large language models: complete reports, tables, figures, layouts and styled
|
|
17
|
+
documents, in a form that renders immediately in a browser. Markdown has
|
|
18
|
+
likewise become a common format for structured content.
|
|
19
|
+
|
|
20
|
+
Both are easy for a model to generate and awkward to edit at the source.
|
|
21
|
+
Markdown means switching between source and preview. HTML source separates the
|
|
22
|
+
author from the rendered document the reader will actually see. Inline editing
|
|
23
|
+
lets you work against the rendered result instead, and Ryker keeps a record of
|
|
24
|
+
what you changed while you do it.
|
|
25
|
+
|
|
26
|
+
## Two ways to use it
|
|
27
|
+
|
|
28
|
+
**As a Chrome extension.** Click the toolbar button on any HTML page to edit
|
|
29
|
+
that document in place. Or open the Ryker workspace and load a Markdown or HTML
|
|
30
|
+
file from your own disk. On a tab Chrome will not let it touch, a new tab or a
|
|
31
|
+
`chrome://` page, the button opens the workspace instead of failing.
|
|
32
|
+
|
|
33
|
+
Ryker is not on the Chrome Web Store yet. Until it is listed, load it unpacked
|
|
34
|
+
from [`extension/`](extension/README.md).
|
|
35
|
+
|
|
36
|
+
**As a drop-in.** Add Ryker to an HTML document with npx and it travels with the
|
|
37
|
+
file. A reader or reviewer can then edit the page and produce a change request
|
|
38
|
+
without installing anything.
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx --yes @gbti/ryker insert ./report.html
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Features
|
|
45
|
+
|
|
46
|
+
- Inline visual editing for HTML and Markdown
|
|
47
|
+
- Export content changes as a machine-readable prompt
|
|
48
|
+
- An outline built from the document's real heading structure
|
|
49
|
+
- Move or delete whole sections from that outline, recorded as moves rather than
|
|
50
|
+
as character diffs
|
|
51
|
+
- Revision history tracked per document
|
|
52
|
+
- Markdown with nested lists, tables and code fences, returned as the file it came from
|
|
53
|
+
- Save the edited document back over the file you opened, or as a new file beside it
|
|
5
54
|
|
|
6
55
|
## Install into an HTML document
|
|
7
56
|
|
|
8
57
|
```bash
|
|
9
|
-
npx --yes @gbti/ryker
|
|
58
|
+
npx --yes @gbti/ryker insert ./report.html
|
|
10
59
|
```
|
|
11
60
|
|
|
12
61
|
Preview first with `--dry-run`. The installer creates a recoverable
|
|
@@ -14,14 +63,38 @@ Preview first with `--dry-run`. The installer creates a recoverable
|
|
|
14
63
|
document, and adds one identifiable managed block before `</body>`.
|
|
15
64
|
|
|
16
65
|
```bash
|
|
17
|
-
npx ryker doctor ./report.html
|
|
18
|
-
npx ryker sync ./report.html
|
|
19
|
-
npx ryker remove ./report.html
|
|
66
|
+
npx --yes @gbti/ryker doctor ./report.html
|
|
67
|
+
npx --yes @gbti/ryker sync ./report.html
|
|
68
|
+
npx --yes @gbti/ryker remove ./report.html
|
|
20
69
|
```
|
|
21
70
|
|
|
71
|
+
`insert` writes Ryker into the document. `doctor` checks an existing install and
|
|
72
|
+
writes nothing: it verifies the managed block is present and correctly placed,
|
|
73
|
+
and that the bundle matches this version of the package. `sync` updates an
|
|
74
|
+
existing install. `remove` deletes the managed block from that document and
|
|
75
|
+
retains the browser bundle, because other documents in the same folder may share
|
|
76
|
+
it.
|
|
77
|
+
|
|
22
78
|
Ryker requires Node.js 20 or newer for installation. The resulting HTML and
|
|
23
79
|
classic browser script work offline and from `file://` without Node.js.
|
|
24
80
|
|
|
81
|
+
This repository is at version `0.2.1`, and the npm `latest` tag serves it, so
|
|
82
|
+
every `npx` command above installs this code.
|
|
83
|
+
|
|
84
|
+
## Privacy
|
|
85
|
+
|
|
86
|
+
Ryker keeps its editing history in your own browser and sends nothing anywhere:
|
|
87
|
+
no server, no account, no sync, no telemetry. The page cannot read it. You can
|
|
88
|
+
export the record whenever you like and clear it per document.
|
|
89
|
+
|
|
90
|
+
The extension asks for no standing access to your browsing. It has no host
|
|
91
|
+
permissions, registers no content scripts, and injects nothing until you click
|
|
92
|
+
its button. The permission it uses, `activeTab`, grants access to one tab for one
|
|
93
|
+
gesture and expires with it.
|
|
94
|
+
|
|
95
|
+
[privacy.md](privacy.md) is the full policy, and is the URL the Chrome Web Store
|
|
96
|
+
listing points at.
|
|
97
|
+
|
|
25
98
|
## License
|
|
26
99
|
|
|
27
100
|
Ryker is source-available under the custom license included with the package.
|
|
@@ -31,6 +104,17 @@ sold or shipped or featured as part of a commercial product or software as a
|
|
|
31
104
|
service offering without prior written permission from GETHSEMANE LLC. The
|
|
32
105
|
license and copyright notice must remain intact.
|
|
33
106
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
107
|
+
Bugs and issues: <https://github.com/gbti-network/ryker/issues>
|
|
108
|
+
|
|
109
|
+
## Credits
|
|
110
|
+
|
|
111
|
+
Wing icon by [prasong tadoungsorn](https://thenounproject.com/creator/layersky/) from
|
|
112
|
+
[Noun Project](https://thenounproject.com/icon/wing-1382909/), licensed
|
|
113
|
+
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
|
|
114
|
+
|
|
115
|
+
This credit lives here and in the Chrome Web Store listing, and deliberately
|
|
116
|
+
nowhere else. Earlier commits placed it more widely and were narrowed later, so
|
|
117
|
+
a commit message asking for it in other files has been superseded by this line
|
|
118
|
+
rather than by an oversight. CC BY attribution attaches to distribution, and
|
|
119
|
+
both places it appears are distributed: this file ships in the npm package, and
|
|
120
|
+
the listing is public.
|
package/bin/ryker.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { createHash } from 'node:crypto';
|
|
3
|
-
import { copyFileSync, existsSync, mkdirSync, readFileSync,
|
|
4
|
-
import { dirname, extname, relative, resolve } from 'node:path';
|
|
3
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
|
|
5
5
|
import { fileURLToPath } from 'node:url';
|
|
6
6
|
|
|
7
|
-
const VERSION = '0.
|
|
7
|
+
const VERSION = '0.2.1';
|
|
8
8
|
const BEGIN = '<!-- ryker:begin -->';
|
|
9
9
|
const END = '<!-- ryker:end -->';
|
|
10
10
|
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
@@ -15,53 +15,153 @@ function hash(buffer) { return createHash('sha256').update(buffer).digest('hex')
|
|
|
15
15
|
function slug(value) {
|
|
16
16
|
return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'untitled';
|
|
17
17
|
}
|
|
18
|
+
function optionValue(argv, index, name) {
|
|
19
|
+
const value = argv[index + 1];
|
|
20
|
+
if (!value || value.startsWith('--')) throw new Error(name + ' requires a value.');
|
|
21
|
+
return value;
|
|
22
|
+
}
|
|
18
23
|
function parse(argv) {
|
|
19
24
|
const out = { command: argv[0], target: argv[1], dryRun: false, documentId: null, assetDir: 'ryker' };
|
|
20
25
|
for (let i = 2; i < argv.length; i++) {
|
|
21
26
|
if (argv[i] === '--dry-run') out.dryRun = true;
|
|
22
|
-
else if (argv[i] === '--document-id') out.documentId = argv
|
|
23
|
-
else if (argv[i] === '--asset-dir') out.assetDir = argv
|
|
27
|
+
else if (argv[i] === '--document-id') { out.documentId = optionValue(argv, i, '--document-id'); i++; }
|
|
28
|
+
else if (argv[i] === '--asset-dir') { out.assetDir = optionValue(argv, i, '--asset-dir'); i++; }
|
|
24
29
|
else throw new Error('Unknown option: ' + argv[i]);
|
|
25
30
|
}
|
|
26
31
|
return out;
|
|
27
32
|
}
|
|
28
33
|
function usage() {
|
|
29
|
-
console.log(`Ryker ${VERSION}\n\nUsage:\n ryker insert <file.html> [--dry-run] [--document-id id] [--asset-dir dir]\n ryker sync <file.html> [--dry-run] [--asset-dir dir]\n ryker doctor <file.html> [--asset-dir dir]\n ryker remove <file.html> [--dry-run] [--asset-dir dir]\n ryker --version`);
|
|
34
|
+
console.log(`Ryker ${VERSION}\n\nUsage:\n ryker insert <file.html> [--dry-run] [--document-id id] [--asset-dir dir]\n ryker sync <file.html> [--dry-run] [--document-id id] [--asset-dir dir]\n ryker doctor <file.html> [--asset-dir dir]\n ryker remove <file.html> [--dry-run] [--asset-dir dir]\n ryker --version`);
|
|
35
|
+
}
|
|
36
|
+
function contained(base, target) {
|
|
37
|
+
const rel = relative(base, target);
|
|
38
|
+
return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('..' + sep));
|
|
39
|
+
}
|
|
40
|
+
function physical(path) {
|
|
41
|
+
let cursor = path;
|
|
42
|
+
const suffix = [];
|
|
43
|
+
while (!existsSync(cursor)) {
|
|
44
|
+
const parent = dirname(cursor);
|
|
45
|
+
if (parent === cursor) break;
|
|
46
|
+
suffix.unshift(basename(cursor));
|
|
47
|
+
cursor = parent;
|
|
48
|
+
}
|
|
49
|
+
return resolve(realpathSync(cursor), ...suffix);
|
|
30
50
|
}
|
|
31
51
|
function targetInfo(options) {
|
|
32
52
|
if (!options.target) throw new Error('Name an HTML file.');
|
|
33
|
-
const
|
|
34
|
-
const
|
|
53
|
+
const requestedCwd = resolve(process.cwd());
|
|
54
|
+
const requestedFile = resolve(requestedCwd, options.target);
|
|
55
|
+
if (!contained(requestedCwd, requestedFile)) throw new Error('Target must be inside the current working directory.');
|
|
56
|
+
if (!['.html', '.htm'].includes(extname(requestedFile).toLowerCase())) throw new Error('Target must be an .html or .htm file.');
|
|
57
|
+
if (!existsSync(requestedFile)) throw new Error('Target does not exist: ' + requestedFile);
|
|
58
|
+
const cwd = realpathSync(requestedCwd);
|
|
59
|
+
const file = realpathSync(requestedFile);
|
|
35
60
|
const rel = relative(cwd, file);
|
|
36
|
-
if (
|
|
37
|
-
|
|
38
|
-
if (!
|
|
39
|
-
|
|
40
|
-
const asset = resolve(dirname(file), options.assetDir, 'dist', 'ryker.js');
|
|
61
|
+
if (!contained(cwd, file)) throw new Error('Target must be inside the current working directory.');
|
|
62
|
+
const assetRoot = options.assetDir ? physical(resolve(dirname(file), options.assetDir)) : null;
|
|
63
|
+
if (!assetRoot || !contained(dirname(file), assetRoot)) throw new Error('Asset directory must stay beside or below the target.');
|
|
64
|
+
const asset = resolve(assetRoot, 'dist', 'ryker.js');
|
|
41
65
|
return { cwd, file, rel, asset, html: readFileSync(file, 'utf8') };
|
|
42
66
|
}
|
|
43
67
|
function managedRange(html) {
|
|
44
68
|
const start = html.indexOf(BEGIN), end = html.indexOf(END);
|
|
45
69
|
if ((start < 0) !== (end < 0)) throw new Error('Found an incomplete managed Ryker block.');
|
|
46
70
|
if (start < 0) return null;
|
|
71
|
+
if (end < start) throw new Error('Found Ryker managed markers in the wrong order.');
|
|
47
72
|
if (html.indexOf(BEGIN, start + 1) >= 0 || html.indexOf(END, end + 1) >= 0) throw new Error('Found multiple managed Ryker blocks.');
|
|
48
73
|
return { start, end: end + END.length };
|
|
49
74
|
}
|
|
75
|
+
function tagEnd(html, start) {
|
|
76
|
+
let quote = null;
|
|
77
|
+
for (let i = start + 1; i < html.length; i++) {
|
|
78
|
+
const char = html[i];
|
|
79
|
+
if (quote) {
|
|
80
|
+
if (char === quote) quote = null;
|
|
81
|
+
} else if (char === '"' || char === "'") quote = char;
|
|
82
|
+
else if (char === '>') return i;
|
|
83
|
+
}
|
|
84
|
+
return html.length - 1;
|
|
85
|
+
}
|
|
86
|
+
function opaqueRanges(html) {
|
|
87
|
+
const ranges = [];
|
|
88
|
+
for (let i = 0; i < html.length;) {
|
|
89
|
+
if (html.startsWith(BEGIN, i) || html.startsWith(END, i)) {
|
|
90
|
+
i += html.startsWith(BEGIN, i) ? BEGIN.length : END.length;
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
if (html.startsWith('<!--', i)) {
|
|
94
|
+
const end = html.indexOf('-->', i + 4);
|
|
95
|
+
ranges.push([i, end < 0 ? html.length : end + 3]);
|
|
96
|
+
i = ranges[ranges.length - 1][1];
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
if (html[i] !== '<') { i++; continue; }
|
|
100
|
+
const end = tagEnd(html, i);
|
|
101
|
+
const tag = /^<\s*(script|style|template|pre|textarea)\b/i.exec(html.slice(i, end + 1));
|
|
102
|
+
if (!tag) { i = end + 1; continue; }
|
|
103
|
+
const close = new RegExp('<\\/\\s*' + tag[1] + '\\s*>', 'ig');
|
|
104
|
+
close.lastIndex = end + 1;
|
|
105
|
+
const match = close.exec(html);
|
|
106
|
+
const stop = match ? match.index + match[0].length : html.length;
|
|
107
|
+
ranges.push([i, stop]);
|
|
108
|
+
i = stop;
|
|
109
|
+
}
|
|
110
|
+
return ranges;
|
|
111
|
+
}
|
|
112
|
+
function covered(index, ranges) {
|
|
113
|
+
return ranges.some(([start, end]) => index >= start && index < end);
|
|
114
|
+
}
|
|
115
|
+
function bodyClose(html, ranges = opaqueRanges(html)) {
|
|
116
|
+
const close = /<\/body\s*>/ig;
|
|
117
|
+
let found = -1;
|
|
118
|
+
for (let match; (match = close.exec(html));) {
|
|
119
|
+
if (!covered(match.index, ranges)) found = match.index;
|
|
120
|
+
}
|
|
121
|
+
if (found < 0) throw new Error('No top-level closing body element was found.');
|
|
122
|
+
return found;
|
|
123
|
+
}
|
|
124
|
+
function managedAtTopLevel(html, range) {
|
|
125
|
+
const ranges = opaqueRanges(html);
|
|
126
|
+
if (covered(range.start, ranges) || covered(range.end, ranges)) return false;
|
|
127
|
+
const body = bodyClose(html, ranges);
|
|
128
|
+
return range.start < body && html.slice(range.end, body).trim() === '';
|
|
129
|
+
}
|
|
130
|
+
function managedDocumentId(html, range) {
|
|
131
|
+
const managed = html.slice(range.start, range.end);
|
|
132
|
+
const config = /<script\b[^>]*\sid=["']ryker-config["'][^>]*>([\s\S]*?)<\/script\s*>/i.exec(managed);
|
|
133
|
+
if (!config) throw new Error('The managed Ryker block has no readable config element.');
|
|
134
|
+
try {
|
|
135
|
+
const parsed = JSON.parse(config[1]);
|
|
136
|
+
if (!parsed.RYKER_DOCUMENT_ID) throw new Error('missing document id');
|
|
137
|
+
return parsed.RYKER_DOCUMENT_ID;
|
|
138
|
+
} catch (error) {
|
|
139
|
+
throw new Error('The managed Ryker block has invalid configuration: ' + error.message);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
function scriptJson(value) {
|
|
143
|
+
return JSON.stringify(value).replace(/</g, '\\u003c');
|
|
144
|
+
}
|
|
145
|
+
function attribute(value) {
|
|
146
|
+
return String(value).replace(/&/g, '&').replace(/"/g, '"')
|
|
147
|
+
.replace(/</g, '<').replace(/>/g, '>');
|
|
148
|
+
}
|
|
50
149
|
function block(info, options, newline) {
|
|
51
150
|
const id = options.documentId || slug(relative(info.cwd, info.file).replace(/\\/g, '/'));
|
|
52
151
|
const src = relative(dirname(info.file), info.asset).replace(/\\/g, '/');
|
|
53
|
-
return [BEGIN, '<script type="application/json" id="ryker-config">',
|
|
152
|
+
return [BEGIN, '<script type="application/json" id="ryker-config">', scriptJson({ RYKER_DOCUMENT_ID: id, RYKER_DOCUMENT_PATH: relative(info.cwd, info.file).replace(/\\/g, '/') }), '</script>', `<script src="${attribute(src)}" data-ryker></script>`, END].join(newline);
|
|
54
153
|
}
|
|
55
154
|
function install(options) {
|
|
56
155
|
const info = targetInfo(options), range = managedRange(info.html);
|
|
57
156
|
if (!range && /<script\b[^>]*\bdata-ryker\b/i.test(info.html)) throw new Error('An unmanaged Ryker insert already exists; refusing to overwrite it.');
|
|
157
|
+
if (range && !managedAtTopLevel(info.html, range)) throw new Error('The managed Ryker block is not directly inside the document body.');
|
|
158
|
+
if (range && !options.documentId) options.documentId = managedDocumentId(info.html, range);
|
|
58
159
|
const newline = info.html.includes('\r\n') ? '\r\n' : '\n';
|
|
59
160
|
const insertion = block(info, options, newline);
|
|
60
161
|
let next;
|
|
61
162
|
if (range) next = info.html.slice(0, range.start) + insertion + info.html.slice(range.end);
|
|
62
163
|
else {
|
|
63
|
-
const body = info.html
|
|
64
|
-
if (body < 0) throw new Error('No closing body element was found.');
|
|
164
|
+
const body = bodyClose(info.html);
|
|
65
165
|
next = info.html.slice(0, body) + insertion + newline + info.html.slice(body);
|
|
66
166
|
}
|
|
67
167
|
const packaged = readFileSync(shippedBundle);
|
|
@@ -81,6 +181,12 @@ function doctor(options) {
|
|
|
81
181
|
const info = targetInfo(options), range = managedRange(info.html);
|
|
82
182
|
const problems = [];
|
|
83
183
|
if (!range) problems.push('managed insert is missing');
|
|
184
|
+
else {
|
|
185
|
+
try {
|
|
186
|
+
if (!managedAtTopLevel(info.html, range)) problems.push('managed insert is not directly inside the document body');
|
|
187
|
+
managedDocumentId(info.html, range);
|
|
188
|
+
} catch (error) { problems.push(error.message); }
|
|
189
|
+
}
|
|
84
190
|
if (!existsSync(info.asset)) problems.push('bundle is missing: ' + info.asset);
|
|
85
191
|
else if (hash(readFileSync(info.asset)) !== hash(readFileSync(shippedBundle))) problems.push('bundle does not match this package version');
|
|
86
192
|
if (problems.length) { problems.forEach((p) => console.error('FAIL ' + p)); process.exitCode = 1; }
|
|
@@ -89,11 +195,13 @@ function doctor(options) {
|
|
|
89
195
|
function remove(options) {
|
|
90
196
|
const info = targetInfo(options), range = managedRange(info.html);
|
|
91
197
|
if (!range) throw new Error('No managed Ryker insert was found.');
|
|
198
|
+
if (!managedAtTopLevel(info.html, range)) throw new Error('The managed Ryker block is not directly inside the document body.');
|
|
199
|
+
managedDocumentId(info.html, range);
|
|
92
200
|
const next = info.html.slice(0, range.start) + info.html.slice(range.end).replace(/^(\r?\n)/, '');
|
|
93
201
|
console.log(`${options.dryRun ? 'Would remove' : 'Removing'} Ryker from ${info.file}`);
|
|
94
202
|
if (options.dryRun) return;
|
|
95
203
|
writeFileSync(info.file, next, 'utf8');
|
|
96
|
-
if (existsSync(info.asset)
|
|
204
|
+
if (existsSync(info.asset)) console.log(' bundle: retained because another document may share it');
|
|
97
205
|
}
|
|
98
206
|
|
|
99
207
|
try {
|