@vegastack/design 0.8.33 → 0.8.35

package/bin/owned-files.mjs

@@ -0,0 +1,332 @@
+// `vegastack-design owned-files` — list the registry-owned files installed in a consuming project.
+//
+// A consumer keeps registry copies out of its own gates: lint ignores, the unused-code scan, the
+// design audit, the drift check. Kept by hand, those lists drift from each other and from what is
+// installed (the Regent app had three, each missing a different `@lib` file). This prints the one
+// list they can all read, derived from what is actually on disk.
+//
+// A file is registry-owned when the registry index names its install target and the file exists
+// there — an `@ui/`, `@lib/`, `@hooks/` or `@components/` target resolved through components.json
+// `aliases`, or a block's project-relative target — or when it carries the provenance header the
+// registry stamps (`// @vegastack <name>@<version> sha256-…`). `shadcn add` strips that header on
+// install, so the index is what finds most copies; `--offline` (or `--index <file>`) avoids the
+// network. The index is fetched exactly the way `check-updates` fetches it: same config, same
+// credential headers, same trusted-origin and no-redirect rules.
+//
+// Read-only: it never writes, installs or edits.
+
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+} from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import {
+  fetchRegistryIndex,
+  ITEM_NAME_RE,
+  PROVENANCE_RE,
+  terminalText,
+} from "./check-updates.mjs";
+
+const USAGE = `vegastack-design owned-files — list the registry-owned files installed in this project
+
+Usage: vegastack-design owned-files [options]
+
+Prints the project-relative path of every file the VegaStack registry installed here, one per
+line, so lint ignores, knip and drift checks can read one generated list.
+
+A file is registry-owned when the registry index names its install target (resolved through
+components.json aliases) and the file exists, or when it carries the registry's provenance
+header (// @vegastack <name>@<version> sha256-…). shadcn add strips that header, so the index
+finds most copies; --offline reports header-carrying files only.
+
+Options:
+  --dir <path>      Project root holding components.json (default: the current directory)
+  --json            Print { files: string[], items: { name, type, version, files[] }[] }
+  --offline         Do not read the registry index; report header-carrying files only
+  --index <file>    Read the registry index from a local registry.json instead of fetching it
+  --registry <url>  Override the registry URL template (…/{name}.json)
+  -h, --help        Show this help
+
+Read-only. Exit codes: 0 = listed · 2 = bad usage, no components.json, or no readable index`;
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".turbo",
+  "coverage",
+]);
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|css)$/;
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const opts = {
+    dir: ".",
+    json: false,
+    offline: false,
+    index: null,
+    registry: null,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--offline") opts.offline = true;
+    else if (a === "--dir" || a === "--index" || a === "--registry") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-"))
+        throw new UsageError(`${a} requires a value`);
+      i += 1;
+      if (a === "--dir") opts.dir = value;
+      else if (a === "--index") opts.index = value;
+      else opts.registry = value;
+    } else throw new UsageError(`unknown option: ${a}`);
+  }
+  if (opts.offline && (opts.index || opts.registry))
+    throw new UsageError("--offline reads no index; drop --index/--registry");
+  return opts;
+}
+
+/** `@/components/ui` → `<root>/components/ui`, or `<root>/src/components/ui` when only that exists. */
+function aliasDir(root, alias) {
+  if (typeof alias !== "string" || alias.length === 0) return null;
+  const rel = alias.replace(/^(?:@|~)\//, "");
+  const direct = resolve(root, rel);
+  if (existsSync(direct)) return direct;
+  const src = resolve(root, "src", rel);
+  return existsSync(src) ? src : direct;
+}
+
+const inside = (dir, path) => path === dir || path.startsWith(dir + sep);
+
+/** Whether `path` is under `root` once every symlink on the way is resolved. */
+function reallyInside(root, path) {
+  try {
+    return inside(realpathSync(root), realpathSync(path));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where a registry file's `target` lands in this project: `@ui/…`, `@lib/…`, `@hooks/…` and
+ * `@components/…` through components.json aliases; a block's bare target (`components/email/x.ts`)
+ * under `src/` when the project has one, else under the root — shadcn's own placement.
+ */
+export function resolveTarget(root, aliases, target) {
+  if (typeof target !== "string" || target.length === 0) return null;
+  const placeholder = /^@(ui|lib|hooks|components)\/(.+)$/.exec(target);
+  let candidates;
+  if (placeholder) {
+    const dir = aliasDir(
+      root,
+      aliases?.[placeholder[1]] ??
+        { ui: "@/components/ui", lib: "@/lib", hooks: "@/hooks" }[
+          placeholder[1]
+        ],
+    );
+    if (!dir) return null;
+    candidates = [resolve(dir, placeholder[2])];
+  } else if (target.startsWith("@")) {
+    return null; // a placeholder this command does not know (`@utils/…`)
+  } else {
+    const rel = target.replace(/^~\//, "");
+    candidates = [resolve(root, "src", rel), resolve(root, rel)];
+  }
+  for (const path of candidates) {
+    // Lexically AND physically inside the project: a `..` in a target, or a symlinked alias dir
+    // or ancestor pointing elsewhere, never lists (or reads) a file outside it. A symlinked file
+    // itself is not a registry copy either.
+    if (!inside(root, path) || !reallyInside(root, path)) continue;
+    try {
+      if (lstatSync(path).isFile()) return path;
+    } catch {
+      // not installed here
+    }
+  }
+  return null;
+}
+
+/** Every source file under `dir` (no symlinks, no build output) whose first line is a provenance header. */
+function headeredFiles(dir, out = new Map()) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e.name) || e.isSymbolicLink()) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) headeredFiles(full, out);
+    else if (e.isFile() && SOURCE_FILE.test(e.name)) {
+      let first;
+      try {
+        first = readFileSync(full, "utf8").split("\n", 1)[0].replace(/\r$/, "");
+      } catch {
+        continue;
+      }
+      const m = PROVENANCE_RE.exec(first);
+      if (m) out.set(full, { name: m[1], version: m[2] });
+    }
+  }
+  return out;
+}
+
+/**
+ * The registry-owned files under `root`: `{ files, items }`, every path project-relative with `/`.
+ * `index` is the registry index's `items` (or null for headers only).
+ */
+export function ownedFiles(root, componentsJson, index) {
+  const aliases = componentsJson?.aliases ?? {};
+  const owners = new Map(); // absolute path → { name, type, version }
+
+  // Headers first: they name the item and the version that was installed.
+  const roots = ["ui", "lib", "hooks", "components"]
+    .map((kind) => aliasDir(root, aliases[kind]))
+    .filter(
+      (d) =>
+        d &&
+        existsSync(d) &&
+        inside(root, d) &&
+        reallyInside(root, d) &&
+        !lstatSync(d).isSymbolicLink(),
+    );
+  const searched = roots.filter(
+    (d, i) => !roots.some((o, j) => j !== i && d !== o && inside(o, d)),
+  );
+  for (const d of [...new Set(searched)])
+    for (const [path, header] of headeredFiles(d))
+      owners.set(path, { ...header, type: null });
+
+  for (const item of index ?? []) {
+    if (
+      !item ||
+      typeof item !== "object" ||
+      !ITEM_NAME_RE.test(item.name ?? "") ||
+      !Array.isArray(item.files)
+    )
+      continue;
+    for (const file of item.files) {
+      const path = resolveTarget(root, aliases, file?.target);
+      if (!path) continue;
+      const known = owners.get(path);
+      if (known && known.name !== item.name) continue; // the header (or an earlier item) wins
+      owners.set(path, {
+        name: item.name,
+        type: typeof item.type === "string" ? item.type : null,
+        version: known?.version ?? null,
+      });
+    }
+  }
+
+  const items = new Map();
+  for (const [path, owner] of owners) {
+    const rel = relative(root, path).split(sep).join("/");
+    const entry = items.get(owner.name) ?? {
+      name: owner.name,
+      type: owner.type,
+      version: null,
+      files: [],
+    };
+    entry.type ??= owner.type;
+    entry.version ??= owner.version;
+    entry.files.push(rel);
+    items.set(owner.name, entry);
+  }
+  const sorted = [...items.values()]
+    .map((item) => ({ ...item, files: item.files.sort() }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return { files: sorted.flatMap((i) => i.files).sort(), items: sorted };
+}
+
+export async function main(argv = []) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    console.error(`owned-files: ${terminalText(err.message)}\n`);
+    console.error(USAGE);
+    return 2;
+  }
+  if (opts.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  const root = resolve(opts.dir);
+  const cjPath = join(root, "components.json");
+  // JSON errors are reported without the parser's message: it quotes a prefix of the file, and
+  // components.json (or a saved index) may hold a credential where a quote went missing.
+  const readJsonFile = (path, what) => {
+    let text;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch (err) {
+      throw new Error(
+        `could not read ${what}: ${terminalText(err.code ?? "error")}`,
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new Error(`${what} is not valid JSON`);
+    }
+  };
+  let componentsJson;
+  try {
+    componentsJson = readJsonFile(cjPath, terminalText(cjPath));
+  } catch (err) {
+    console.error(
+      `✗ ${err.message} — owned-files resolves install targets through its aliases`,
+    );
+    return 2;
+  }
+
+  let index = null;
+  let source = "headers";
+  if (opts.index) {
+    try {
+      const what = `the index ${terminalText(opts.index)}`;
+      index = readJsonFile(resolve(opts.index), what)?.items;
+      if (!Array.isArray(index)) throw new Error(`${what} has no items array`);
+      source = terminalText(opts.index);
+    } catch (err) {
+      console.error(`✗ ${err.message}`);
+      return 2;
+    }
+  } else if (!opts.offline) {
+    try {
+      const fetched = await fetchRegistryIndex({
+        cwd: root,
+        registry: opts.registry,
+        componentsJson,
+      });
+      index = fetched.items;
+      source = fetched.url;
+    } catch (err) {
+      console.error(`✗ ${terminalText(err.message)}`);
+      console.error(
+        "  pass --offline to list header-carrying files only, or --index <registry.json>",
+      );
+      return 2;
+    }
+  }
+
+  const result = ownedFiles(root, componentsJson, index);
+  if (opts.json) {
+    console.log(JSON.stringify({ source, ...result }, null, 2));
+    return 0;
+  }
+  for (const file of result.files) console.log(file);
+  if (result.files.length === 0)
+    console.error(`no registry-owned files found (index: ${source})`);
+  return 0;
+}

package/bin/vegastack-design.mjs

@@ -6,7 +6,8 @@
 //   verify          Verify a registry item's integrity before/after `shadcn add` (Sigstore + hash).
 //   skills          Install the bundled VegaStack agent skills into the consuming project.
 //   doctor          Check a consuming project's setup (PostCSS plugin, preset import, registry,
-//                   retired design-system vocabulary in its own source).
+//                   retired design-system vocabulary and DS composition in its own source).
+//   owned-files     List the registry-owned files installed in the project (read-only).
 //
 // The bin is named `vegastack-design` (NOT `vegastack`) so it never collides with a platform CLI.
 // `check-updates` is imported in-process; `verify` is spawned (it's the standalone, hash-parity-tested
@@ -26,6 +27,7 @@ Commands:
   verify            Verify a registry item's integrity (pre/post \`shadcn add\`)
   skills            Install the VegaStack agent skills (Claude Code + Codex)
   doctor            Check this project's setup and report what is wrong
+  owned-files       List the registry-owned files installed in this project
 
 Run \`vegastack-design <command> --help\` for command options.
   -v, --version     Print version
@@ -70,6 +72,12 @@ if (cmd === "doctor") {
   process.exit(main(rest));
 }
 
+if (cmd === "owned-files") {
+  // imported in-process (our own code, read-only; reads the registry index like check-updates)
+  const { main } = await import(new URL("./owned-files.mjs", HERE).href);
+  process.exit(await main(rest));
+}
+
 if (cmd === "verify") {
   // spawn the standalone verifier untouched; mark the dispatch so it skips its deprecation notice.
   const verifier = fileURLToPath(new URL("./verify-registry-item.mjs", HERE));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design",
-  "version": "0.8.33",
+  "version": "0.8.35",
   "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
   "license": "MIT",
   "repository": {
@@ -70,7 +70,7 @@
     "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs && node test/doctor.test.mjs && node --test test/merge-refs.test.mjs test/registry-credentials.test.mjs"
   },
   "dependencies": {
-    "@vegastack/design-tokens": "^0.8.17",
+    "@vegastack/design-tokens": "^0.8.35",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0",
     "tsconfig-paths": "^4.2.0",

package/skills/vegastack-design-system/references/components.md

@@ -3,7 +3,7 @@
 <!-- GENERATED — do not hand-edit. Regenerated from the design system's component contract,
      which is the authority for membership and counts. -->
 
-**168 components**, plus 467 animated-icon items, 16 hooks (`use-animation-replay`, `use-announcer`, `use-async-search`, `use-drag-reorder`, `use-file-drop`, `use-grid-selection`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-optimistic-action`, `use-overflow`, `use-platform`, `use-tabs-swipe`, `use-view-transition`), 15 starter blocks (`app-shell-01`, `board-01`, `issue-detail-01`, `page-editor-01`, `command-search-01`, `list-page-01`, `library-01`, `login-01`, `notifications-01`, `review-split-01`, `settings-01`, `settings-02`, `status-pages-01`, `email-kit`, `share-01`), 68 chart blocks across 7 families, and 21 data libs (`code-highlight`, `date-time`, `grid-clipboard`, `geo-data`, `emoji-data`, `drag-item`, `text-anchor`, `text-anchor-doc`, `text-edit-grammar`, `embed-providers`, `text-edit-schema`, `text-edit-markdown`, `file-kind`, `upload-progress`, `media-probe`, `page-layout`, `tile-overlay`, `icon-data`, `icon-components`, `picker-search`, `picker-preferences`) — 755 registry items in total.
+**171 components**, plus 467 animated-icon items, 16 hooks (`use-animation-replay`, `use-announcer`, `use-async-search`, `use-drag-reorder`, `use-file-drop`, `use-grid-selection`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-optimistic-action`, `use-overflow`, `use-platform`, `use-tabs-swipe`, `use-view-transition`), 15 starter blocks (`app-shell-01`, `board-01`, `issue-detail-01`, `page-editor-01`, `command-search-01`, `list-page-01`, `library-01`, `login-01`, `notifications-01`, `review-split-01`, `settings-01`, `settings-02`, `status-pages-01`, `email-kit`, `share-01`), 68 chart blocks across 7 families, and 21 data libs (`code-highlight`, `date-time`, `grid-clipboard`, `geo-data`, `emoji-data`, `drag-item`, `text-anchor`, `text-anchor-doc`, `text-edit-grammar`, `embed-providers`, `text-edit-schema`, `text-edit-markdown`, `file-kind`, `upload-progress`, `media-probe`, `page-layout`, `tile-overlay`, `icon-data`, `icon-components`, `picker-search`, `picker-preferences`) — 758 registry items in total.
 
 Install any of them with `shadcn add @vegastack/<name>`. Animated icons install as
 `@vegastack/icon-<name>`; the bare name is reserved for components, so a component whose name
@@ -55,7 +55,7 @@ starts with `icon-` is a component and never an icon.
 
 ## Display
 
-- **`activity-feed`** — A record's history, Linear style: comment threads and activity events ("Priya changed status from Open to Done · 2h") in one list, with an All / Comments / Activity filter, an order toggle, collapsible event groups, a New divider, a floating Jump to latest, J/K/X keyboard navigation and a skeleton.
+- **`activity-feed`** — A record's history, Linear style: comment threads and activity events ("Priya changed status from Open to Done · 2h") in one list, with an All / Comments / Activity filter, an order toggle, one actor's runs of changes as one line (a chain of one field's values, or "made 3 changes" expanding), collapsible event groups, a New divider, a floating Jump to latest, J/K/X keyboard navigation and a skeleton.
 - **`block-view`** — The frame TextEdit and MarkdownView draw a fenced block in when a blockViews entry renders its language: label, Preview / Code, split on a wide editable block, Expand with pan and pinch, and a ⋯ menu.
 - **`chip`** — The one labelled pill primitive — 10 decorative hues, two tiers, an optional selection rung, and a real 24x24 remove control. Behind Tag and FilterChip; ComboboxChip is Base UI's own chip, not this primitive.
 - **`code-block`** — A code panel with a language header and copy affordance — the shared code surface for chat transcripts, docs, and examples.
@@ -63,8 +63,10 @@ starts with `icon-` is a component and never an icon.
 - **`comments`** — A record's comments, Linear style: thread cards (first comment, Show N more replies, indented replies over hairlines, a flat reply row with the viewer's avatar), a bordered composer with a toolbar row and file drop, day labels, a list with a count, order toggle, Load earlier, skeleton and empty states, edit/delete/copy link/copy text, emoji reactions and an attachments slot.
 - **`diff-view`** — What changed between two texts — changed lines, then the words inside them, removed struck through and added tinted — with the sanctioned diff engine in its own lazily loaded chunk; line-only above 200 KB.
 - **`entry-list`** — A short, compact list of plain entries in a sheet, dialog or popover: a line of text, its muted details and small actions at its end.
+- **`member-list`** — The people in a team, a space or a share list — an add row (picker · optional role · Add) and 36px rows (avatar · name over a muted sub line · role chip menu or text · ⋯ with Remove) that scroll after eight.
 - **`mermaid-block`** — A mermaid diagram drawn in the browser with the engine loaded lazily and its configuration pinned (strict security, SVG labels, dagre), in token colours for light and dark, keeping the last diagram that worked on an error — plus renderMermaid, useMermaidSvg and the ready blockViews entry for TextEdit and MarkdownView.
 - **`meta-line`** — An icon + text meta line under a record title: wrapping facts such as type, date and time, duration and owner, in the muted ink.
+- **`qr-code`** — A QR code for a value, drawn as one crisp SVG path — dark modules on a light rounded tile in both themes, with the standard quiet zone — encoded during render (server or client) by uqr; an empty or unencodable value draws the empty tile.
 - **`reactions`** — Slack-style emoji reactions: pills with counts that toggle, a hover card naming who reacted, and an add-reaction button with quick reactions.
 - **`stat`** — A labelled value block — muted label over a value, honest faint empty state, optional delta line. Two scales.
 - **`tag-group`** — Hue-tinted label chips on the 10-hue tag palette, with +N overflow collapsing and removable tags.
@@ -176,7 +178,8 @@ starts with `icon-` is a component and never an icon.
 - **`resizable`** — Accessible resizable panel groups and layouts with keyboard support — horizontal or vertical, nestable, with an optional visible grip.
 - **`scroll-area`** — Augments native scroll functionality for custom, cross-browser styling — a viewport, an auto-hiding scrollbar, and a corner.
 - **`separator`** — A thin rule dividing content — horizontal or vertical, built on Base UI.
-- **`settings-row`** — A borders-only settings layout — titled sections, bordered cards, and label-plus-control rows.
+- **`settings-layout`** — The two-pane Settings frame — a 220px sticky section nav with current-page marking and counts, and one 960px content column where forms cap at 720px left-aligned and lists fill; on a phone the nav is the first screen and pages push in with a back link.
+- **`settings-row`** — A borders-only settings layout — titled sections, bordered cards, label-plus-control rows whose controls share one width and right edge (controlSize), and a settings × channels switch matrix with its column names once.
 
 ## Media
 
@@ -184,7 +187,7 @@ starts with `icon-` is a component and never an icon.
 - **`file-card`** — One file as a card row: thumbnail or type icon, name, description lines and a ⋯ actions menu — opening the file viewer, or the whole card a link (download, navigate); with UploadCard for a file uploading into the same list.
 - **`file-viewer`** — A full-screen dark overlay for stored files — images with a blur-up, zoom and pan; PDFs rendered page by page with a lazily loaded pdf.js over range requests; video and audio in the system players; the first megabyte of text, CSV (as a table) and Markdown; app-parsed previews through loadPreview; a file card with a thumbnail and Download for everything else — paged with arrows, side buttons or a swipe.
 - **`image`** — A presentational framed image with aspect-ratio, rounding, a loading skeleton, and an error fallback.
-- **`inbox`** — The notification Inbox: frame with header actions, All | Unread chips, sticky day groups, full-bleed rows with avatar or icon and an unread tint (no dot), rich titles, action chips, a fixed right column with the time over the hover actions (read toggle and menu), and empty, loading and error states.
+- **`inbox`** — The notification Inbox: frame with header actions, For you · Updates · Archived tabs with an Unread toggle, sticky day groups, full-bleed rows grouped per record (stacked actors, a count that expands to the events), inline Allow / Decline or an answered line, J / K triage with an active row driving a peek, a fixed right column with the time over the hover actions (read toggle and menu), and empty, loading and error states.
 - **`level-meter`** — A segmented live input-level meter for a recording — Web Audio RMS from a MediaStream, or a level you drive — with warning and clipping zones.
 - **`media-player-controls`** — The shared media transport — play/pause, skip, seek, elapsed/duration, mute + volume, playback speed, and one keyboard shortcut map (useMediaShortcuts) — composed by Audio Player and Video Player.
 - **`notification-bell`** — A bell icon button with an unread-count badge overlay, plus the shared NotificationDot unread marker. Presentational — the app supplies the count.