@anchrd/intel 0.59.0

package/ui/README.md

@@ -0,0 +1,110 @@
+# The Intel browser application
+
+Intelligence, Flows and Tools, served by the Intel Worker. It travels inside
+[`@anchrd/intel`](https://www.npmjs.com/package/@anchrd/intel) at `ui/`, and it ships **source, not a
+bundle**: you compile it yourself so your own theme, logo and languages are applied at build time and
+the output belongs to you — no customer build artifact ever lives in `node_modules`.
+
+## Install
+
+```bash
+npm install @anchrd/intel
+npx intel build
+```
+
+The CLI applies `intel.json` and writes the static output to `.intel/ui`, which the Intel Worker
+serves through its `ASSETS` binding.
+
+## Reserved names
+
+A document called **`index`** inside a folder is the **text of that folder**. `index`, `Index` and
+`index.md` all count, upper and lower case alike.
+
+Such a document does not appear as a row under its folder. It appears in that folder's **Details**,
+where it is read and written like anywhere else, and a link there opens it on its own screen — which
+is where it is moved, shared or archived.
+
+⚠️ **The flip side is the same sentence read backwards:** naming a document `index` for any other
+reason changes how its folder reads. If a document has to keep that name and stay a row of its own,
+give it a name of its own — `index-2024.md` or `overview` — or file it one folder deeper.
+
+Two documents of that name in one folder are allowed: the **oldest** becomes the folder's text and
+every other one stays an ordinary row. Nothing disappears.
+
+⚠️ **The top level is not a folder**, so the name means nothing there: a document called `index` at
+the root keeps its row like any other. It has no details panel to be shown in, and a row taken away
+with nowhere to reappear is a document nobody can navigate to.
+
+Over MCP nothing is hidden at all: `node_list` and `node_get` answer for such a document exactly as
+they do for any other, and `node_create` says so in its own description.
+
+## Theming
+
+Theme CSS overrides shadcn semantic variables such as `--primary`, `--background`, `--sidebar` and
+`--radius`. It loads after Intel's defaults, so customer tokens win without forking a single React
+component. Every product component uses semantic tokens rather than palette colours, which is
+enforced by a lint rule.
+
+Point `intel.json` at your files:
+
+```json
+{
+  "ui": {
+    "theme": "./branding/theme.css",
+    "logo": "./branding/logo.svg",
+    "favicon": "./branding/favicon.svg",
+    "defaultLanguage": "en",
+    "languages": {}
+  }
+}
+```
+
+Missing assets, non-SVG branding and incomplete language catalogs fail the build rather than
+silently producing a half-branded application.
+
+## What an empty screen means
+
+Most "the UI is broken" reports are one of four situations, and the application distinguishes them
+rather than showing one blank page for all of them. The full explanation of the two permission
+layers is in the
+[package README](../README.md); what follows is what each one looks like here.
+
+| On screen | What it is |
+|---|---|
+| "You do not have permission to see this." | The Gate capability is missing — `nodes.read` and friends |
+| An empty tree, no error | Nothing has been shared with this person yet |
+| "This is not available to you. It may not exist, or it may no longer be shared with you." | A node that was reachable and is not any more, or never existed — Intel deliberately does not say which |
+| Skeletons that never resolve | Should no longer happen: a refusal ends the loading state on the first answer, and no button offers a retry that cannot change anything |
+
+A node somebody shares appears in the recipient's sidebar on its own, at the top level, without
+naming the folders above it. Nobody needs to be sent a link.
+
+The sharing dialog grants to an email address or to the whole organization. It never shows a raw
+user id: where Intel cannot name an account it says so. ⚠️ Choosing **execute for the whole
+organization** on a folder makes that folder a library that flows from anywhere may call into, and
+withdrawing it is refused while a caller remains — the dialog says so before the click.
+
+The Tools screen tells four situations apart — refused, expired, broken, and started-but-never-
+answered — and offers a second attempt everywhere a second attempt could change the answer.
+
+The editor answers "Nothing to save" rather than "Saved" when the write produced no new version.
+The two are different outcomes and only one of them means the text is safe to walk away from.
+
+⚠️ The editor opens **empty** on content it cannot parse. Documents written over HTTP or MCP have to
+carry the BlockNote media type to be editable in the browser; see the wire schemas under
+`src/contract`.
+
+## What is inside
+
+Vite, React, TanStack Router and Query, with shadcn components. The node editor uses BlockNote and
+plain SVG for the radial relation graph, Flows uses React Flow, and Tools presents the discovered MCP
+catalog. Route-level code splitting keeps both editors out of the initial bundle.
+
+Server state lives only in TanStack Query, and one data provider is the sole module that talks to the
+Intel HTTP surface. The application uses same-origin `HttpOnly` sessions established by the Intel
+Worker against Gate OAuth: it holds no service key and stores no access token in the browser.
+
+## License
+
+Proprietary. Published publicly for installation convenience; this is not an open-source license and
+grants no right to use, copy, modify or redistribute the software. Contact Anchrd for licensing.

package/ui/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/src/branding/favicon.svg" />
+    <title>Intel</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/ui/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "intel-ui",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "preview": "vite preview"
+  }
+}

package/ui/scripts/lint-tokens.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// Semantic tokens only: no hex colours, no Tailwind palette classes. The check this replaces was a
+// single grep, and it could not tell `#101` — a ticket number in a comment — from `#101` the
+// colour, because nothing separates them but where they stand (issue 104).
+//
+// ⚠️ The fix is to look at less, not to match less. Comments are stripped and everything else is
+// checked with exactly the patterns the grep used, so no colour that used to be caught slips
+// through. A colour named in a comment paints nothing; a colour in code paints something.
+//
+// ⚠️ Stripping comments needs to know what a comment is. `//` inside a string is a URL, not a
+// comment, and getting that wrong would blind the check to real code — the failure mode this file
+// exists to avoid. Hence the small scanner rather than a regex over the raw text.
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import process from "node:process";
+
+const ROOT = process.argv[2] ?? "src";
+
+// Exactly the patterns the shell version used.
+const FORBIDDEN = [
+  { name: "hex colour", pattern: /#[0-9a-fA-F]{3,8}\b/ },
+  {
+    name: "palette class",
+    pattern:
+      /\b(bg|text|border|ring|shadow|fill|stroke)-(white|black|slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)(-\d{2,3})?\b/,
+  },
+];
+
+// Test files may spell anything out — they are where a rule gets stated, including by counter
+// example. Same exclusion the shell version carried.
+const SKIP_FILE = /\.unit\.tsx?$/;
+const CHECK_FILE = /\.(tsx?|css)$/;
+
+/**
+ * The file with its comments blanked out, line structure intact so line numbers still mean
+ * something. Strings keep their contents: a hex colour in a string is exactly what must be caught.
+ */
+function withoutComments(source, isCss) {
+  let out = "";
+  let i = 0;
+  // "code" | "line" | "block" | quote character for a string
+  let state = "code";
+  while (i < source.length) {
+    const char = source[i];
+    const next = source[i + 1];
+    if (state === "code") {
+      // A regex literal would be the third thing that can hold a `/`, but none in this package
+      // contains `//` or `/*`, and treating one as a comment would only ever blind the check to
+      // something inside a regex — never let a colour through.
+      if (!isCss && char === "/" && next === "/") {
+        state = "line";
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        state = "block";
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      if (char === '"' || char === "'" || char === "`") {
+        state = char;
+        out += char;
+        i += 1;
+        continue;
+      }
+      out += char;
+      i += 1;
+      continue;
+    }
+    if (state === "line") {
+      if (char === "\n") {
+        state = "code";
+        out += char;
+      } else {
+        out += " ";
+      }
+      i += 1;
+      continue;
+    }
+    if (state === "block") {
+      if (char === "*" && next === "/") {
+        state = "code";
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      out += char === "\n" ? char : " ";
+      i += 1;
+      continue;
+    }
+    // Inside a string: kept as it stands, escapes skipped so `\"` does not end it early.
+    if (char === "\\") {
+      out += source.slice(i, i + 2);
+      i += 2;
+      continue;
+    }
+    if (char === state) state = "code";
+    out += char;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * The checker checked, on every run.
+ *
+ * ⚠️ This is here because of how the shell version could have failed: a pattern that matches
+ * nothing, or an exclusion that swallows the whole tree, reports success. `Checked 0 files` and
+ * `checked everything, all clean` look identical from the outside, and the second one is what
+ * everybody reads. Stating the cases the check exists for — and the ones it must stay quiet about —
+ * means a rule that stops working says so instead of going green.
+ */
+function selfTest() {
+  const mustCatch = [
+    ['const c = "#fff";', "a three-digit hex in a string"],
+    ['const c = "#a1b2c3";', "a six-digit hex"],
+    ['const c = "#11223344";', "an eight-digit hex with alpha"],
+    ["  color: #fff;", "a hex in CSS"],
+    ['<div className="bg-red-500" />', "a palette class"],
+    ['<div className="text-white" />', "a palette colour without a number"],
+  ];
+  const mustAllow = [
+    ["// the folder table, since (#101)", "a ticket number in a line comment"],
+    ["/* archived like a document (#109) */", "a ticket number in a block comment"],
+    ["{/* two lists say what they show (#99) */}", "a ticket number in a JSX comment"],
+    ['<div className="bg-background text-muted-foreground" />', "semantic tokens"],
+  ];
+  // ⚠️ Not in either list, and deliberately: a URL fragment that happens to read like a colour —
+  // `https://example.com/#fff` — is still reported. The grep did the same, so nothing regressed
+  // here, and the one way to stop it would be to make the colour pattern narrower. That trade goes
+  // the wrong way: a false alarm costs one rewritten line, a missed colour costs the rule. The
+  // first attempt at this file listed it as "must allow" and this check refused it, which is the
+  // check doing its job.
+  const failures = [];
+  for (const [line, what] of mustCatch) {
+    const code = withoutComments(line, line.startsWith("  color:"));
+    if (!FORBIDDEN.some(({ pattern }) => pattern.test(code))) {
+      failures.push(`stopped catching ${what}: ${line}`);
+    }
+  }
+  for (const [line, what] of mustAllow) {
+    const code = withoutComments(line, false);
+    if (FORBIDDEN.some(({ pattern }) => pattern.test(code))) {
+      failures.push(`started refusing ${what}: ${line}`);
+    }
+  }
+  if (failures.length > 0) {
+    console.error("The token check is no longer checking what it is for:\n");
+    for (const failure of failures) console.error(`  ${failure}`);
+    process.exit(1);
+  }
+}
+
+async function* files(dir) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* files(path);
+    else if (CHECK_FILE.test(entry.name) && !SKIP_FILE.test(entry.name)) yield path;
+  }
+}
+
+selfTest();
+
+const findings = [];
+for await (const path of files(ROOT)) {
+  const source = await readFile(path, "utf8");
+  const code = withoutComments(source, path.endsWith(".css"));
+  code.split("\n").forEach((line, index) => {
+    for (const { name, pattern } of FORBIDDEN) {
+      const hit = pattern.exec(line);
+      if (hit) findings.push(`${relative(".", path)}:${index + 1}  ${name}  ${hit[0]}`);
+    }
+  });
+}
+
+if (findings.length > 0) {
+  console.error(
+    `Use semantic tokens instead. ${findings.length} hard-coded value${findings.length === 1 ? "" : "s"}:\n`,
+  );
+  for (const finding of findings) console.error(`  ${finding}`);
+  console.error("\nA ticket reference in a comment is fine — comments are not checked.");
+  process.exit(1);
+}
+console.log(`No hard-coded colours or palette classes in ${ROOT}.`);