@gbti/ryker 0.1.1-rc.1 → 0.2.2

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 CHANGED
@@ -1,12 +1,61 @@
1
1
  # Ryker
2
2
 
3
- Ryker adds inline editing to authored HTML and produces prompt-ready,
4
- machine-readable change requests.
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@next insert ./report.html
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.2`, 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
- This package is not published yet. The `@next` command above becomes available
35
- after the first release candidate is published. The `@latest` tag is reserved
36
- for a release that has passed public-package acceptance testing.
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, rmSync, writeFileSync } from 'node:fs';
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.1.1-rc.1';
7
+ const VERSION = '0.2.2';
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[++i];
23
- else if (argv[i] === '--asset-dir') out.assetDir = argv[++i];
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 cwd = resolve(process.cwd());
34
- const file = resolve(cwd, options.target);
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 (rel.startsWith('..') || resolve(cwd, rel) !== file) throw new Error('Target must be inside the current working directory.');
37
- if (!['.html', '.htm'].includes(extname(file).toLowerCase())) throw new Error('Target must be an .html or .htm file.');
38
- if (!existsSync(file)) throw new Error('Target does not exist: ' + file);
39
- if (!options.assetDir || resolve(dirname(file), options.assetDir).startsWith(dirname(file)) === false) throw new Error('Asset directory must stay beside or below the target.');
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, '&amp;').replace(/"/g, '&quot;')
147
+ .replace(/</g, '&lt;').replace(/>/g, '&gt;');
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">', JSON.stringify({ RYKER_DOCUMENT_ID: id, RYKER_DOCUMENT_PATH: relative(info.cwd, info.file).replace(/\\/g, '/') }), '</script>', `<script src="${src}" data-ryker></script>`, END].join(newline);
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.search(/<\/body\s*>/i);
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) && hash(readFileSync(info.asset)) === hash(readFileSync(shippedBundle))) rmSync(info.asset);
204
+ if (existsSync(info.asset)) console.log(' bundle: retained because another document may share it');
97
205
  }
98
206
 
99
207
  try {