k0-board 0.3.0 → 0.4.0

package/server/index.js

@@ -27,7 +27,7 @@ import * as files from './files.js'
 import * as pdf from './pdf.js'
 import * as machine from './machine.js'
 import * as servers from './servers.js'
-import { report as platformReport } from '../platform/index.js'
+import { report as platformReport, capabilities, why } from '../platform/index.js'
 // The same front-matter reader the viewer uses: the PDF has to be called what the page is
 // called, and two different readings of the same header would give two different names.
 import { matter, titleOf } from '../web/md.js'
@@ -341,6 +341,11 @@ function site(req, res, seg) {
 // is a much smaller loss than that, so the header is gone.
 const SANDBOX = 'sandbox'
 
+// How much a save is allowed to carry. Well under the megabyte the body reader stops at, which
+// would otherwise refuse a large file with a message about requests instead of about the file —
+// and far above anything you would actually edit in a browser tab: k0's own README is 56 KB.
+const MAX_SAVE = 1 << 18
+
 // ── The recap of a window ────────────────────────────────────────────────────
 // Held for a minute, and not as a saved result: the page asks for the facts, then asks for the
 // write-up to start, then asks every second whether it is done. Reading every repository's git
@@ -540,8 +545,11 @@ async function api(req, res, url) {
     const card = Number.isInteger(cardId) && cardId > 0 ? db.getCard(cardId) : null
     // Searching inside the files: the page asks for it as you type, and it needs neither the
     // listing nor git's state.
+    // `nerd` is the switch in the page: with it on, the configuration files are listed, so the
+    // search inside the text has to look in them too.
+    const nerd = url.searchParams.get('nerd') === '1'
     if (url.searchParams.get('only') === 'text') {
-      return send(res, 200, { hits: await files.grep(root, url.searchParams.get('q') || '') })
+      return send(res, 200, { hits: await files.grep(root, url.searchParams.get('q') || '', nerd) })
     }
     const changed = await files.changed(root, card?.head_at_start)
     if (url.searchParams.get('only') === 'changed') return send(res, 200, { changed, now: Date.now() })
@@ -554,6 +562,13 @@ async function api(req, res, url) {
       truncated: all.truncated,
       changed,
       files: all.files,
+      // What this machine can do about a file, so the viewer greys the buttons out and says why
+      // rather than offering something that would quietly do nothing.
+      can: {
+        reveal: capabilities.revealInFileManager,
+        open: capabilities.openInFileManager,
+        whyNot: why('revealInFileManager') || why('openInFileManager'),
+      },
       now: Date.now(),
     })
   }
@@ -609,10 +624,27 @@ async function api(req, res, url) {
       return res.end(out)
     }
 
+    // One button, two neighbouring things: a file is pointed at inside its folder, a folder is
+    // opened. Which of the two is decided here rather than in the page, because the page would
+    // have to guess and the disk already knows.
     if (idRaw === 'reveal' && req.method === 'POST') {
-      await files.reveal(abs)
+      if (fs.statSync(abs).isDirectory()) await files.openFolder(abs)
+      else await files.reveal(abs)
       return send(res, 200, { ok: true })
     }
+
+    // The first thing k0 writes into one of your repositories. Only configuration and notes, only
+    // a file that is already there, and only if nobody has touched it since the page read it.
+    if (idRaw === 'save' && req.method === 'POST') {
+      if (!files.isEditable(rel)) return send(res, 400, { error: 'This kind of file is not edited here' })
+      if (typeof body.text !== 'string') return send(res, 400, { error: 'Nothing to save' })
+      if (Buffer.byteLength(body.text) > MAX_SAVE) return send(res, 400, { error: 'That is too big to save from here' })
+      try {
+        return send(res, 200, files.write(abs, body.text, Number(body.mtime)))
+      } catch (e) {
+        return send(res, e.conflict ? 409 : 500, { error: e.message })
+      }
+    }
     if (!idRaw && req.method === 'GET') return send(res, 200, { path: rel, ...files.read(abs) })
   }
 

package/web/board.css

@@ -387,10 +387,18 @@ body {
   gap: 7px;
   margin-bottom: 3px;
 }
+/* The repository's name takes the room that is left, so everything after it — the git mark, the
+   memory chip — sits against the right edge of the note. The same shape as the heading of a
+   column, and for the same reason: hanging off the end of the name those marks landed in a
+   different place on every note, and a row of notes had no line to read down. */
 .postit .tag {
+  flex: 1;
   font: 500 1.05rem/1 var(--hand);
   color: rgba(0, 0, 0, .5);
   min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 /* The name is the session's: it is in monospace like the k0 mark at the top.
    Monospace is heavier at the same size, which is why it drops to .94rem. */

package/web/conf.js

@@ -0,0 +1,118 @@
+// ── Configuration files, laid out ─────────────────────────────────────────────
+// An `.env` is a table pretending to be a text file: two columns, one per line, and the reason
+// you opened it is always to compare a name with a value. Shown as text, the values start in a
+// different place on every line and the eye has to walk each one to the `=`. Shown as a table,
+// you read the column.
+//
+// The rest — YAML, TOML, INI — is not a table: nesting matters, and a table would flatten the one
+// thing that carries the meaning. Those keep their shape and only get their keys, their values
+// and their comments told apart by colour.
+//
+// Like the tree next door, this knows nothing about the page: text in, a string of HTML out.
+
+/** Written again here for the same reason as in `json.js`: the tests run in Node. */
+const esc = (s) =>
+  String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
+
+/**
+ * An `.env` read line by line, keeping everything — the comments and the blank lines included.
+ *
+ * They are kept because they are the file: a comment above a key says what the key is for, and a
+ * view that dropped it would be a different file that happens to have the same values. Anything
+ * this does not understand comes back as it was written rather than being guessed at.
+ *
+ * Returns rows of `{ kind: 'pair' | 'comment' | 'blank' | 'raw' }`.
+ */
+export function envRows(text) {
+  const rows = []
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    const trimmed = line.trim()
+    if (!trimmed) {
+      rows.push({ kind: 'blank' })
+      continue
+    }
+    if (trimmed.startsWith('#')) {
+      rows.push({ kind: 'comment', text: trimmed.replace(/^#\s?/, '') })
+      continue
+    }
+    // `export FOO=bar` is the same line with a word in front of it: shell files and `.env` files
+    // are copied back and forth, and both spellings turn up in the same repository.
+    const body = trimmed.replace(/^export\s+/, '')
+    const at = body.indexOf('=')
+    if (at <= 0) {
+      rows.push({ kind: 'raw', text: line })
+      continue
+    }
+    const key = body.slice(0, at).trim()
+    rows.push({ kind: 'pair', key, value: unquote(body.slice(at + 1).trim()) })
+  }
+  // A file ends with a newline, and that last empty line is not a blank line in the file: it is
+  // the end of it. Showing it would put a hole at the bottom of every table.
+  if (rows.length && rows[rows.length - 1].kind === 'blank') rows.pop()
+  return rows
+}
+
+/**
+ * The value without the quotes around it, and without the comment after it.
+ *
+ * The comment is only cut off an unquoted value: inside quotes a `#` is a character like any
+ * other, and a password with a hash in it must not lose half of itself on the way to the screen.
+ */
+function unquote(value) {
+  const quoted = /^(['"])([\s\S]*)\1$/.exec(value)
+  if (quoted) return quoted[2]
+  const hash = value.search(/\s#/)
+  return hash === -1 ? value : value.slice(0, hash).trimEnd()
+}
+
+/** The two columns. An empty value is said in words, or the row would look like a mistake. */
+export function envTable(text) {
+  const body = envRows(text)
+    .map((r) => {
+      if (r.kind === 'pair') {
+        const value = r.value
+          ? `<td class="val">${esc(r.value)}</td>`
+          : '<td class="val none">empty</td>'
+        return `<tr><th>${esc(r.key)}</th>${value}</tr>`
+      }
+      if (r.kind === 'comment') return `<tr class="note"><td colspan="2">${esc(r.text)}</td></tr>`
+      if (r.kind === 'raw') return `<tr class="odd"><td colspan="2">${esc(r.text)}</td></tr>`
+      return '<tr class="gap"><td colspan="2"></td></tr>'
+    })
+    .join('')
+  return `<table class="env">${body}</table>`
+}
+
+/**
+ * YAML, TOML and INI: the same file, with the parts told apart.
+ *
+ * No parsing. A YAML parser written here would be a second thing to keep correct, and every one
+ * of its mistakes would show you a file that is not the file. Reading a line at a time never
+ * shows you anything that is not there — at worst it colours something in as though it were
+ * ordinary text, which is what it does with everything it does not recognise.
+ */
+export function highlight(text) {
+  const out = String(text ?? '')
+    .split('\n')
+    .map((raw) => {
+      const line = raw.replace(/\r$/, '')
+      const lead = line.length - line.trimStart().length
+      const indent = esc(line.slice(0, lead))
+      const rest = line.slice(lead)
+      if (!rest) return ''
+      if (rest.startsWith('#') || rest.startsWith(';')) return `${indent}<span class="c">${esc(rest)}</span>`
+      // A TOML or INI heading: the one line that says where you are in the file.
+      if (/^\[.*]$/.test(rest)) return `${indent}<span class="sec">${esc(rest)}</span>`
+      // `- ` is a YAML list, and what follows it may itself be a pair.
+      const dash = /^-\s+/.exec(rest)
+      const item = dash ? rest.slice(dash[0].length) : rest
+      const bullet = dash ? `<span class="dash">${esc(dash[0])}</span>` : ''
+      const pair = /^([^:=#]+?)\s*([:=])\s*([\s\S]*)$/.exec(item)
+      if (!pair) return `${indent}${bullet}<span class="v">${esc(item)}</span>`
+      const value = pair[3] ? `<span class="v">${esc(pair[3])}</span>` : ''
+      return `${indent}${bullet}<span class="key">${esc(pair[1])}</span><span class="sep">${pair[2]}</span> ${value}`
+    })
+    .join('\n')
+  return `<pre class="conf">${out}</pre>`
+}

package/web/files.css

@@ -74,6 +74,28 @@ body {
   width: 100%;
   color: var(--ink);
 }
+/* The switch that lets the configuration through. It was a bare glyph inside the search pill and
+   nobody found it: at that size, in that place, it read as part of the field rather than as
+   something you could press. So it is a button of its own, next to the search, outlined like the
+   ones over a document, and it says what it does in a word. Switched on it fills in, so from
+   across the room you can tell whether you are looking at everything or not. */
+.topbar .nerd {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  padding: 5px 11px;
+  border: 1px solid var(--line);
+  background: #fff;
+  border-radius: 999px;
+  font: inherit;
+  font-size: .74rem;
+  color: var(--muted);
+  cursor: pointer;
+}
+.topbar .nerd svg { width: 14px; height: 14px; display: block; flex: none; }
+.topbar .nerd:hover { color: var(--ink); border-color: #bdb6a5; background: #fff; }
+.topbar .nerd.on, .topbar .nerd.on:hover { background: var(--ink); border-color: var(--ink); color: #fff; }
 
 /* ── The two panes ───────────────────────────────────────────────────── */
 /* The divider is a column of the grid: drag it and the size stays. */
@@ -160,6 +182,16 @@ body {
   overflow: hidden;
 }
 .row q mark { background: #fde68a; color: var(--ink); border-radius: 3px; padding: 0 1px; }
+/* The letters that made this row match, in its name. Underlined and not highlighted, so the two
+   answers stay apart at a glance: yellow means the word was found inside the file, a line under
+   the letters means they are in its name. */
+.row b u {
+  color: var(--ink);
+  text-decoration: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 2px;
+  text-decoration-color: var(--alert);
+}
 .row:hover { background: rgba(0, 0, 0, .035); }
 .row.on { background: var(--WORKING); }
 .row.active { box-shadow: inset 3px 0 0 var(--ink); }
@@ -215,6 +247,26 @@ body {
 .from-text .x:hover { opacity: 1; text-decoration: none; }
 .from-text .x svg { width: 15px; height: 15px; display: block; }
 
+/* The line that says the switch is hiding what you asked for. It sits above everything, in the
+   same green as the other things that say "the listing is not showing you all of it", and it is a
+   button: the answer to "where is my .env" should be one click, not an instruction. */
+.nudge {
+  display: block;
+  width: 100%;
+  border: 0;
+  border-bottom: 1px solid rgba(0, 0, 0, .08);
+  border-radius: 0;
+  background: var(--IDLE);
+  padding: 9px 16px;
+  font: inherit;
+  font-size: .78rem;
+  font-weight: 600;
+  color: var(--ink);
+  text-align: left;
+  cursor: pointer;
+}
+.nudge:hover { background: var(--IDLE); text-decoration: underline; }
+
 /* The heading of a group that opens and closes: the guesses arrive closed. */
 .list h2.fold { cursor: pointer; user-select: none; }
 .list h2.fold::after {
@@ -239,6 +291,45 @@ body {
 .row.fold b::after { content: ' ▸'; opacity: .6; font-weight: 400; }
 .row.fold.open b::after { content: ' ▾'; }
 
+/* ── Folders ──────────────────────────────────────────────────────────
+   A folder is a row like any other, and deliberately so: the arrow keys walk it, ⌘-click opens
+   it in another tab, and nothing about it has to be learnt separately. The only difference is the
+   mark in front of the name and the slash after it, which is how a folder has always been told
+   apart from a file. */
+.row.folder b::before {
+  content: '';
+  display: inline-block;
+  width: 12px;
+  height: 9px;
+  margin-right: 7px;
+  border: 1px solid var(--muted);
+  border-radius: 1px 2px 2px 2px;
+  border-top-width: 3px;
+  vertical-align: middle;
+  opacity: .75;
+}
+.row.folder b::after { content: '/'; opacity: .45; }
+
+/* Where you are, one piece of the path at a time. It sits in the same green strip as the label of
+   a pasted text: both say the listing is a slice, and they must look like the same statement. */
+.from-text.trail { gap: 3px; overflow-x: auto; scrollbar-width: none; }
+.from-text.trail::-webkit-scrollbar { display: none; }
+.from-text a, .from-text b {
+  font: inherit;
+  font-size: .78rem;
+  font-weight: 600;
+  color: var(--ink);
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.from-text a:hover { text-decoration: underline; }
+/* The last piece is where you are: it does not lead anywhere, and it does not pretend to. */
+.from-text b { cursor: default; opacity: .95; }
+.from-text i { font-style: normal; font-size: .72rem; opacity: .4; }
+.from-text .act { margin-left: auto; padding: 2px 7px; background: rgba(255, 255, 255, .7); }
+.from-text .act + .x { margin-left: 4px; }
+
 /* "7 more": it sits under the row it belongs to, off to one side. */
 .more {
   display: block;
@@ -328,6 +419,10 @@ body {
 .crumb b { font: 600 .82rem var(--mono); color: var(--ink); }
 .crumb i { font-style: normal; opacity: .5; }
 .crumb em { margin-left: auto; font-style: normal; }
+/* The path above a document is the way to its neighbours: each piece opens the folder it names,
+   in the list on the left. It stays grey — it is still the path, not a row of buttons. */
+.crumb a.up { color: inherit; text-decoration: none; border-bottom: 1px dotted transparent; }
+.crumb a.up:hover { color: var(--ink); border-bottom-color: var(--muted); }
 
 /* ── What to do with it ───────────────────────────────────────────────
    Print the document, take it away as it is, or have it laid out into a PDF. They sit here at
@@ -350,8 +445,115 @@ body {
 }
 .act:hover { color: var(--ink); border-color: #bdb6a5; }
 .act svg { width: 14px; height: 14px; display: block; flex: none; }
+/* A button this machine cannot honour stays where it is, faint, with the reason in its title. One
+   that vanished would leave you looking for it; one that did nothing would leave you wondering. */
+.act[disabled] { opacity: .3; cursor: default; }
+.act[disabled]:hover { color: var(--muted); border-color: var(--line); }
+/* Save is the one that changes something, so it is the one that is filled in. */
+.act.keep { background: var(--ink); border-color: var(--ink); color: #fff; font-weight: 600; }
+.act.keep:hover { color: #fff; border-color: var(--ink); }
 .cut { padding: 12px 32px; color: var(--muted); font-size: .82rem; font-style: italic; }
 
+/* ── Searching inside one file ────────────────────────────────────────
+   Only where the browser's own find cannot go: a tree is mostly folded, and ⌘F says "not found"
+   for something that is three lines away behind a closed branch. */
+.findin { display: flex; align-items: center; gap: 6px; margin-left: 12px; }
+.findin input {
+  border: 1px solid var(--line);
+  background: #fff;
+  border-radius: 999px;
+  padding: 4px 11px;
+  font: inherit;
+  font-size: .72rem;
+  color: var(--ink);
+  outline: 0;
+  width: 170px;
+}
+.findin input:focus { border-color: #bdb6a5; }
+.findin em {
+  font-style: normal;
+  font-size: .72rem;
+  color: var(--muted);
+  font-variant-numeric: tabular-nums;
+  min-width: 1.4em;
+}
+
+/* ── A JSON file, as a tree ───────────────────────────────────────────
+   The folding is `<details>`: the browser already knows how to do it, so there is no state here
+   and it works before a single line of script has run. The colours are the types — you learn them
+   in one glance and then never read them again, you just see them. */
+.tree { padding: 18px 32px; font: .8rem/1.55 var(--mono); }
+.json .kids { margin-left: 1.05rem; padding-left: .7rem; border-left: 1px solid var(--line); }
+.json summary { cursor: pointer; list-style: none; padding: 1px 0; border-radius: 4px; }
+.json summary::-webkit-details-marker { display: none; }
+.json summary::before {
+  content: '▸';
+  display: inline-block;
+  width: .9em;
+  opacity: .5;
+  transition: transform .12s;
+}
+.json details[open] > summary::before { transform: rotate(90deg); }
+.json summary:hover { background: rgba(0, 0, 0, .04); }
+.json .leaf { padding: 1px 0 1px .9em; }
+.json .key { font-weight: 600; color: #1e40af; }
+.json .key::after { content: ':'; opacity: .45; font-weight: 400; margin-right: .35em; }
+.json .brace { opacity: .45; margin-left: .35em; }
+.json em { font-style: normal; margin-left: .6em; font-size: .9em; color: var(--muted); }
+.json .v.str { color: #15803d; }
+.json .v.str::before, .json .v.str::after { content: '"'; opacity: .4; }
+.json .v.num { color: #b45309; }
+.json .v.bool { color: #7c3aed; }
+.json .v.nil, .json .v.empty { color: var(--muted); font-style: italic; }
+.json mark { background: #fde68a; color: var(--ink); border-radius: 3px; padding: 0 1px; }
+
+/* ── An .env file, as the table it always was ─────────────────────────
+   Two columns and one line each: the reason you open one is to compare a name with a value, and
+   as text the values start in a different place on every line. The comments stay — a comment
+   above a key is what the key is for, and a view that dropped it would be a different file. */
+.env { width: calc(100% - 64px); margin: 20px 32px; border-collapse: collapse; font: .8rem var(--mono); }
+.env th, .env td { padding: 6px 10px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }
+.env th { width: 34%; font-weight: 600; color: #1e40af; overflow-wrap: anywhere; }
+.env .val { color: var(--ink); overflow-wrap: anywhere; }
+.env .val.none { color: var(--muted); font-style: italic; }
+.env .note td { color: var(--muted); font-style: italic; border-bottom: 0; padding-top: 14px; }
+.env .odd td { color: var(--muted); }
+.env .gap td { padding: 0; height: 8px; border-bottom: 0; }
+
+/* ── YAML, TOML, INI ──────────────────────────────────────────────────
+   Not a table: the nesting is the meaning, and flattening it would throw away the one thing you
+   opened the file to see. So the file keeps its shape and only gets its parts told apart. */
+.conf {
+  margin: 0;
+  padding: 20px 32px;
+  font: .82rem/1.6 var(--mono);
+  white-space: pre;
+  overflow-x: auto;
+}
+.conf .key { color: #1e40af; font-weight: 600; }
+.conf .sep, .conf .dash { opacity: .45; }
+.conf .sec { color: #7c3aed; font-weight: 600; }
+.conf .c { color: var(--muted); font-style: italic; }
+
+/* ── Writing a file ───────────────────────────────────────────────────
+   In the pane where the document was, not in a window over it: a dialog is the right size for a
+   title and the wrong size for a README, and here the pane is already as tall as the file. */
+.crumb.editing { background: var(--IDLE); }
+.crumb.editing em { font-style: italic; }
+.edit {
+  display: block;
+  width: 100%;
+  height: calc(100vh - 96px);
+  border: 0;
+  outline: 0;
+  resize: none;
+  padding: 20px 32px;
+  background: #fff;
+  color: var(--ink);
+  font: .82rem/1.6 var(--mono);
+  tab-size: 2;
+}
+
 /* ── The label ────────────────────────────────────────────────────────
    What is written between the two rules at the top of the file. It is not text of the document —
    it is what the document says it is — so it reads as a label: set apart, in a different colour,
@@ -511,7 +713,10 @@ body {
   .split { display: block; }
   .doc { overflow: visible; padding: 0 14mm; background: #fff; }
 
-  .md, .plain { padding: 0; font-size: 10.5pt; line-height: 1.5; }
+  .md, .plain, .tree, .conf { padding: 0; font-size: 10.5pt; line-height: 1.5; }
+  .env { width: 100%; margin: 0; }
+  /* A file half-written is not a document: there is nothing to put on paper. */
+  .edit { display: none !important; }
   /* The label is hidden, but it is still there: the space that held it down is not. */
   .plate + .md { padding-top: 0; }
   .md a { color: #000; }

package/web/files.html

@@ -20,6 +20,16 @@
       </button>
       <input id="q" autocomplete="off" spellcheck="false" placeholder="search a file…">
     </div>
+    <!-- The switch that lets the configuration through. Off by default: in a repository of prose
+         an `.env` is not what you came for, and on the day it is, it is the only thing you came
+         for. It sits beside the search and not inside it, and it says what it is in a word: put
+         in the pill as a bare glyph it read as part of the field's decoration, and nobody found
+         it. -->
+    <button type="button" class="nerd" id="nerd" aria-pressed="false"
+            title="Show configuration files too — .env, JSON, YAML, TOML, INI" aria-label="Show configuration files too">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 6l-5 6 5 6"/><path d="M16 6l5 6-5 6"/></svg>
+      config
+    </button>
     <span class="count" id="count"></span>
   </header>