idcmd 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rusty.wtf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# idcmd
+# idcmd (Markdown Site CLI, Bun + SSR)
 
-Placeholder package to reserve the name on npm. API and usage will be added later.
+## Create A Site
+
+```bash
+bunx idcmd@latest init my-docs
+cd my-docs
+bun install
+bun run dev
+```
+
+Everything you edit lives in `site/`.
+
+## CLI
+
+```bash
+idcmd init [dir]   # scaffold a new site
+idcmd dev          # tailwind watch + SSR dev server
+idcmd build        # static dist/
+idcmd preview      # serve dist/ locally
+idcmd deploy       # build + validate Vercel static deploy config
+```
+
+## Layout (V1)
+
+- `site/content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
+- `site/styles/tailwind.css` -> `site/public/styles.css` (dev) / `dist/styles.css` (build)
+- `site/public/` static assets
+- `site/server/routes/**` file-based server routes (dev/server-host only)
+- `site/site.jsonc` site config
+
+## Example: Add A Page
+
+Create `site/content/hello.md`:
+
+```md
+---
+title: Hello
+group: main
+order: 99
+icon: file
+---
+
+# Hello
+
+This is a new page.
+```
+
+It renders at `/hello/`.
+
+## Custom Server Routes (V1)
+
+Add `site/server/routes/api/hello.ts`:
+
+```ts
+export const GET = (): Response => Response.json({ ok: true });
+```
+
+It responds at `/api/hello`.
+
+## V1 Definition Of Done
+
+`tickets/ROADMAP.md` is the source of truth. For V1, we explicitly target:
+
+- Content routes ship `0` bytes of JavaScript by default (both SSR output and built HTML).
+- Search index size `<= 5 MB` for `<= 2,000` pages.
+- Build completes in `<= 60s` for `<= 2,000` pages on a typical laptop.
+
+## URL Policy
+
+- HTML pages are canonicalized to trailing-slash paths (example: `/about/`), except `/`.
+- File-like paths (example: `/styles.css`, `/robots.txt`, `/index.md`) are not forced to trailing slash.
+
+## Invariants
+
+### Slug and path rules
+
+- Content lives at `site/content/<slug>.md` (or legacy `content/<slug>.md`).
+- `slug="index"` is the home page.
+- Canonical HTML paths are `/` for index and `/<slug>/` otherwise.
+- Markdown download paths exist in two forms:
+  - Flat: `/index.md` and `/<slug>.md`
+  - Flat: `/index.md` and `/<slug>.md`
+
+### baseUrl vs origin
+
+- `site.baseUrl` is normalized to an origin (protocol + host + optional port). Any path/query/hash in config is stripped.
+- Dev server canonicals always use the request `origin` (localhost should not emit production canonicals).
+- Non-dev/server canonicals prefer `site.baseUrl` and fall back to request `origin`.
+
+### JS policy
+
+- Content routes ship `0` bytes of JavaScript by default.
+- Allowed scripts:
+  - Dev only: `/_idcmd/live-reload.js`
+  - Optional: `/_idcmd/right-rail-scrollspy.js` only when scrollspy is enabled and the computed TOC is non-empty
+- Search page is SSR-only by default (no client JS).

package/package.json

@@ -1,11 +1,58 @@
 {
   "name": "idcmd",
-  "version": "0.0.1",
-  "description": "",
-  "license": "MIT",
-  "main": "index.js",
+  "version": "0.0.3",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rustydotwtf/idcmd"
+  },
+  "bin": {
+    "idcmd": "src/cli.ts"
+  },
   "files": [
-    "index.js",
+    "src",
+    "templates",
+    "public",
+    "LICENSE",
     "README.md"
-  ]
+  ],
+  "type": "module",
+  "module": "src/server.ts",
+  "exports": {
+    "./client": "./src/client/index.ts"
+  },
+  "scripts": {
+    "dev": "concurrently -k -n css,server -c blue,green \"bun run dev:css\" \"bun run dev:server\"",
+    "dev:css": "bunx @tailwindcss/cli -i content/styles.css -o public/styles.css --watch",
+    "dev:server": "bun --hot src/server.ts",
+    "build:css": "bunx @tailwindcss/cli -i content/styles.css -o dist/styles.css --minify",
+    "build": "bun run build:css && bun src/build.ts",
+    "preview": "bunx serve dist",
+    "start": "bun src/server.ts",
+    "check": "ultracite check && bun run typecheck && bun run test",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "fix": "ultracite fix",
+    "prepare": "lefthook install"
+  },
+  "dependencies": {
+    "preact": "^10.28.3",
+    "preact-render-to-string": "^6.6.5",
+    "shiki": "^3.22.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.1.18",
+    "@types/bun": "latest",
+    "@typescript/native-preview": "latest",
+    "concurrently": "^9.2.1",
+    "lefthook": "^2.1.0",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5",
+    "ultracite": "7.1.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
 }

package/public/_idcmd/live-reload.js

@@ -0,0 +1,18 @@
+(() => {
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  const socket = new WebSocket(
+    `${protocol}//${location.host}/_idcmd/live-reload`
+  );
+
+  socket.addEventListener("message", (event) => {
+    if (event.data === "reload") {
+      location.reload();
+    }
+  });
+
+  socket.addEventListener("close", () => {
+    setTimeout(() => {
+      location.reload();
+    }, 1000);
+  });
+})();

package/public/_idcmd/llm-menu.js

@@ -0,0 +1,153 @@
+const COPY_SELECTOR = 'a[data-copy-markdown="1"]';
+const LABEL_SELECTOR = '[data-copy-markdown-label="1"]';
+const RESET_DELAY_MS = 2000;
+
+const setLinkDisabled = (link, disabled) => {
+  if (disabled) {
+    link.setAttribute("aria-disabled", "true");
+    link.style.pointerEvents = "none";
+    link.style.opacity = "0.8";
+    return;
+  }
+
+  link.removeAttribute("aria-disabled");
+  link.style.pointerEvents = "";
+  link.style.opacity = "";
+};
+
+const setLinkLabel = (link, next) => {
+  const label = link.querySelector(LABEL_SELECTOR);
+  if (label) {
+    label.textContent = next;
+  }
+};
+
+const toAbsoluteUrl = (href) => {
+  try {
+    return new URL(href, window.location.href).toString();
+  } catch {
+    return href;
+  }
+};
+
+const createHiddenTextarea = (text) => {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "true");
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+  textarea.style.top = "0";
+  return textarea;
+};
+
+const safeExecCommandCopy = () => {
+  try {
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  }
+};
+
+const copyViaExecCommand = (text) => {
+  const textarea = createHiddenTextarea(text);
+  document.body.append(textarea);
+  textarea.focus();
+  textarea.select();
+  const ok = safeExecCommandCopy();
+  textarea.remove();
+  return ok;
+};
+
+const copyText = async (text) => {
+  const { clipboard } = navigator;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall back below.
+    }
+  }
+
+  return copyViaExecCommand(text);
+};
+
+const closeMenuIfPresent = (link) => {
+  const details = link.closest("details");
+  if (details instanceof HTMLDetailsElement) {
+    details.open = false;
+  }
+};
+
+const getOriginalLabel = (link) =>
+  link.querySelector(LABEL_SELECTOR)?.textContent ??
+  "Copy Markdown to Clipboard";
+
+const fetchMarkdownText = async (href) => {
+  const res = await fetch(toAbsoluteUrl(href), { credentials: "same-origin" });
+  if (!res.ok) {
+    return null;
+  }
+  return res.text();
+};
+
+const copyMarkdownFromHref = async (href) => {
+  try {
+    const text = await fetchMarkdownText(href);
+    if (!text) {
+      return false;
+    }
+    return copyText(text);
+  } catch {
+    return false;
+  }
+};
+
+const startCopyOperation = (link) => {
+  setLinkDisabled(link, true);
+  setLinkLabel(link, "Copying...");
+};
+
+const finishCopyOperation = (link, ok) => {
+  setLinkLabel(link, ok ? "Copied" : "Copy failed");
+  closeMenuIfPresent(link);
+};
+
+const scheduleResetOperation = (link, originalLabel) => {
+  window.setTimeout(() => {
+    setLinkLabel(link, originalLabel);
+    setLinkDisabled(link, false);
+  }, RESET_DELAY_MS);
+};
+
+const handleCopyClick = async (link, originalLabel) => {
+  const href = link.getAttribute("href");
+  if (!href) {
+    return;
+  }
+
+  startCopyOperation(link);
+  const ok = await copyMarkdownFromHref(href);
+  finishCopyOperation(link, ok);
+  scheduleResetOperation(link, originalLabel);
+};
+
+const attachCopyHandler = (link) => {
+  const originalLabel = getOriginalLabel(link);
+  link.addEventListener("click", async (event) => {
+    event.preventDefault();
+    if (link.getAttribute("aria-disabled") === "true") {
+      return;
+    }
+    await handleCopyClick(link, originalLabel);
+  });
+};
+
+const initCopyMarkdownButtons = () => {
+  const links = [...document.querySelectorAll(COPY_SELECTOR)];
+  for (const link of links) {
+    attachCopyHandler(link);
+  }
+};
+
+initCopyMarkdownButtons();

package/public/_idcmd/nav-prefetch.js

@@ -0,0 +1,30 @@
+(() => {
+  const selector = 'a[data-prefetch="hover"][href]';
+  const prefetched = new Set();
+
+  const prefetch = (href) => {
+    if (!href || prefetched.has(href)) {
+      return;
+    }
+    prefetched.add(href);
+
+    const link = document.createElement("link");
+    link.rel = "prefetch";
+    link.href = href;
+    document.head.append(link);
+  };
+
+  const onOver = (event) => {
+    const { target } = event;
+    if (!(target instanceof Element)) {
+      return;
+    }
+    const link = target.closest(selector);
+    if (!(link instanceof HTMLAnchorElement)) {
+      return;
+    }
+    prefetch(link.href);
+  };
+
+  document.addEventListener("mouseover", onOver, { passive: true });
+})();

package/public/_idcmd/right-rail-scrollspy.js

@@ -0,0 +1,262 @@
+const TOC_ROOT_SELECTOR = '[data-toc-root="1"]';
+const TOC_LINK_SELECTOR = 'a[data-toc-link="1"][href^="#"]';
+const TOC_SCROLL_CONTAINER_SELECTOR = '[data-toc-scroll-container="1"]';
+
+const NAVBAR_GAP_PX = 16;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+
+const getTopOffset = () => {
+  const header = document.querySelector("header");
+  const headerHeight = header?.getBoundingClientRect().height ?? 0;
+  return Math.ceil(headerHeight + NAVBAR_GAP_PX);
+};
+
+const decodeAnchorId = (href) => {
+  if (!href?.startsWith("#")) {
+    return null;
+  }
+
+  const raw = href.slice(1);
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+};
+
+const toEntry = (link) => {
+  const id = decodeAnchorId(link.getAttribute("href"));
+  if (!id) {
+    return null;
+  }
+
+  // ids like "11-overview" are valid HTML ids but invalid CSS selectors unless escaped.
+  // eslint-disable-next-line unicorn/prefer-query-selector
+  const heading = document.getElementById(id);
+  if (!heading) {
+    return null;
+  }
+
+  return { heading, link, y: 0 };
+};
+
+const buildEntries = (tocRoot) =>
+  [...tocRoot.querySelectorAll(TOC_LINK_SELECTOR)]
+    .map(toEntry)
+    .filter((entry) => entry !== null);
+
+const measureEntries = (entries) => {
+  for (const entry of entries) {
+    entry.y = entry.heading.getBoundingClientRect().top + window.scrollY;
+  }
+};
+
+const setScrollMarginTop = (topOffset) => {
+  document.documentElement.style.setProperty(
+    "--scroll-margin-top",
+    `${topOffset}px`
+  );
+};
+
+const binarySearchLastAtOrAbove = (entries, anchorLine) => {
+  let lo = 0;
+  let hi = entries.length;
+
+  // Find the first entry with y > anchorLine, then step back one.
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (entries[mid].y <= anchorLine) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+
+  return lo - 1;
+};
+
+const findActiveIndex = (entries, topOffset) => {
+  const anchorLine = window.scrollY + topOffset + 1;
+  const best = binarySearchLastAtOrAbove(entries, anchorLine);
+  return Math.max(0, best);
+};
+
+const parseTransformValues = (transform, prefix) =>
+  transform
+    .slice(prefix.length, -1)
+    .split(",")
+    .map((value) => Number.parseFloat(value.trim()));
+
+const getNumberAtIndex = (values, index) => {
+  const [value] = values.slice(index, index + 1);
+  return Number.isFinite(value) ? value : 0;
+};
+
+const getMatrix3dTranslateY = (values) => getNumberAtIndex(values, 13);
+
+const getMatrixTranslateY = (values) => getNumberAtIndex(values, 5);
+
+const getComputedTranslateY = (element) => {
+  const { transform } = window.getComputedStyle(element);
+  if (!transform || transform === "none") {
+    return 0;
+  }
+
+  if (transform.startsWith("matrix3d(")) {
+    const values = parseTransformValues(transform, "matrix3d(");
+    return getMatrix3dTranslateY(values);
+  }
+
+  if (transform.startsWith("matrix(")) {
+    const values = parseTransformValues(transform, "matrix(");
+    return getMatrixTranslateY(values);
+  }
+
+  return 0;
+};
+
+const setTranslateY = (element, next) => {
+  element.style.transform = `translate3d(0, ${next}px, 0)`;
+};
+
+const getElementCenterY = (element) => {
+  const rect = element.getBoundingClientRect();
+  return rect.top + rect.height / 2;
+};
+
+const getCenteredTranslateY = (scrollContainer, list, link) => {
+  const containerHeight = scrollContainer.clientHeight;
+  const listHeight = list.scrollHeight;
+
+  if (listHeight <= containerHeight + 1) {
+    return 0;
+  }
+
+  const delta = getElementCenterY(scrollContainer) - getElementCenterY(link);
+  const currentTranslate = getComputedTranslateY(list);
+  const minTranslate = containerHeight - listHeight;
+  return clamp(currentTranslate + delta, minTranslate, 0);
+};
+
+const centerLinkIfNeeded = (state, link) => {
+  const { scrollContainer, tocList } = state;
+  if (!scrollContainer || !tocList) {
+    return;
+  }
+
+  const next = getCenteredTranslateY(scrollContainer, tocList, link);
+  const current = getComputedTranslateY(tocList);
+  if (Math.abs(current - next) < 0.5) {
+    return;
+  }
+
+  setTranslateY(tocList, next);
+};
+
+const setActiveLink = (state, index) => {
+  if (index === state.activeIndex) {
+    return;
+  }
+
+  const previous = state.entries[state.activeIndex];
+  previous?.link.removeAttribute("aria-current");
+
+  state.activeIndex = index;
+  const current = state.entries[state.activeIndex];
+  current.link.setAttribute("aria-current", "location");
+
+  if (state.centerActiveItem) {
+    centerLinkIfNeeded(state, current.link);
+  }
+};
+
+const updateActive = (state) => {
+  setActiveLink(state, findActiveIndex(state.entries, state.topOffset));
+};
+
+const scheduleUpdate = (state) => {
+  if (state.isTicking) {
+    return;
+  }
+
+  state.isTicking = true;
+  requestAnimationFrame(() => {
+    state.isTicking = false;
+    updateActive(state);
+  });
+};
+
+const refreshLayout = (state) => {
+  state.topOffset = getTopOffset();
+  setScrollMarginTop(state.topOffset);
+  measureEntries(state.entries);
+  updateActive(state);
+
+  if (state.centerActiveItem) {
+    const current = state.entries[state.activeIndex];
+    if (current) {
+      centerLinkIfNeeded(state, current.link);
+    }
+  }
+};
+
+const createState = () => {
+  const { body } = document;
+  const tocRoot = document.querySelector(TOC_ROOT_SELECTOR);
+  const entries = tocRoot ? buildEntries(tocRoot) : [];
+  if (
+    !body ||
+    body.dataset.scrollspy !== "1" ||
+    !tocRoot ||
+    entries.length === 0
+  ) {
+    return null;
+  }
+
+  const centerActiveItem = body.dataset.scrollspyCenter === "1";
+  const scrollContainer = tocRoot.querySelector(TOC_SCROLL_CONTAINER_SELECTOR);
+  const tocList = scrollContainer?.querySelector("ul") ?? null;
+
+  return {
+    activeIndex: -1,
+    centerActiveItem,
+    entries,
+    isTicking: false,
+    scrollContainer,
+    tocList,
+    topOffset: getTopOffset(),
+  };
+};
+
+const start = (state) => {
+  // Disable independent TOC scrolling whenever scrollspy is active.
+  // The TOC list position is controlled by JS (either centered or left as-is).
+  document.body.dataset.tocFollow = "1";
+
+  window.addEventListener("scroll", () => scheduleUpdate(state), {
+    passive: true,
+  });
+  window.addEventListener("resize", () => refreshLayout(state));
+  window.addEventListener("load", () => {
+    refreshLayout(state);
+    setTimeout(() => refreshLayout(state), 250);
+    setTimeout(() => refreshLayout(state), 1000);
+  });
+
+  refreshLayout(state);
+};
+
+const init = () => {
+  const state = createState();
+  if (!state) {
+    return;
+  }
+
+  start(state);
+};
+
+init();

package/public/anthropic-black.svg

@@ -0,0 +1,16 @@
+<svg version="1.1" id="Layer_1" xmlns:x="ns_extend;" xmlns:i="ns_ai;" xmlns:graph="ns_graphs;" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 92.2 65" style="enable-background:new 0 0 92.2 65;" xml:space="preserve">
+ <style type="text/css">
+  .st0{fill:#181818;}
+ </style>
+ <metadata>
+  <sfw xmlns="ns_sfw;">
+   <slices>
+   </slices>
+   <sliceSourceBounds bottomLeftOrigin="true" height="65" width="92.2" x="-43.7" y="-98">
+   </sliceSourceBounds>
+  </sfw>
+ </metadata>
+ <path class="st0" d="M66.5,0H52.4l25.7,65h14.1L66.5,0z M25.7,0L0,65h14.4l5.3-13.6h26.9L51.8,65h14.4L40.5,0C40.5,0,25.7,0,25.7,0z
+	 M24.3,39.3l8.8-22.8l8.8,22.8H24.3z">
+ </path>
+</svg>

package/public/anthropic-white.svg

@@ -0,0 +1,16 @@
+<svg version="1.1" id="Layer_1" xmlns:x="ns_extend;" xmlns:i="ns_ai;" xmlns:graph="ns_graphs;" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 92.2 65" style="enable-background:new 0 0 92.2 65;" xml:space="preserve">
+ <style type="text/css">
+  .st0{fill:#FFFFFF;}
+ </style>
+ <metadata>
+  <sfw xmlns="ns_sfw;">
+   <slices>
+   </slices>
+   <sliceSourceBounds bottomLeftOrigin="true" height="65" width="92.2" x="-43.7" y="-98">
+   </sliceSourceBounds>
+  </sfw>
+ </metadata>
+ <path class="st0" d="M66.5,0H52.4l25.7,65h14.1L66.5,0z M25.7,0L0,65h14.4l5.3-13.6h26.9L51.8,65h14.4L40.5,0C40.5,0,25.7,0,25.7,0z
+	 M24.3,39.3l8.8-22.8l8.8,22.8H24.3z">
+ </path>
+</svg>

package/public/favicon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="IDC favicon">
+  <rect width="64" height="64" rx="12" fill="#0B0B0B" />
+  <text
+    x="32"
+    y="40"
+    font-family="JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace"
+    font-size="22"
+    text-anchor="middle"
+    fill="#F9FAFB"
+  >
+    idc
+  </text>
+</svg>