@lorekit/cli 1.27.0 → 1.28.0

package/README.md

@@ -321,6 +321,7 @@ lorekit link global                       # the Explorer filtered to global scop
 lorekit link repo::owner/repo prefer-guards   # open one lesson's detail sheet
 lorekit link global::prefer-guards --json     # { url, surface, base, params }
 lorekit url --q "flaky test" --owner personal # search + ownership filter
+lorekit link global --tags "perf,ci"          # Explorer filtered to labels
 ```
 
 With no arguments it links to the cwd's **most-specific scope** ("share what I'm
@@ -331,8 +332,9 @@ that lesson's detail sheet. It sets **both** the `lesson` param (which opens the
 sheet) and `scope` — not because scope is needed to find the lesson (the sidebar
 reads one unfiltered recent set), but so the Explorer list *behind* the sheet is
 filtered to the lesson's own scope. Filter flags mirror the Explorer: `--q`
-(search), `--owner <all|personal|orgId>`, `--range`/`--from`/`--to`, `--archived`,
-`--view <scope|time>`.
+(search), `--owner <all|personal|orgId>`, `--tags <a,b,c>` (label filter, AND
+across labels; comma-separated or a JSON array), `--range`/`--from`/`--to`,
+`--archived`, `--view <scope|time>`.
 
 Every param is `encodeURIComponent(JSON.stringify(value))` — the exact inverse of
 how the dashboard's `useUrlState` reads it back (`JSON.parse`, falling back to the

package/bin/lorekit.mjs

@@ -85,8 +85,8 @@ ${c.bold('Commands')}
   link (url)  Print a shareable dashboard deep-link URL for the current context,
               a scope, or a specific lesson (opens its detail sheet). No args
               links to the cwd's most-specific scope. Filter flags mirror the
-              Explorer (--q / --owner / --range / --archived / --view); --base or
-              LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
+              Explorer (--q / --owner / --tags / --range / --archived / --view);
+              --base or LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
               lorekit link | pbcopy.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
@@ -506,6 +506,7 @@ ${c.bold('Options')}
       --scope <scope>     Scope to link to (when no positional scope is given)
       --q <text>          Pre-fill the Explorer search box
       --owner <o>         Ownership filter: all | personal | <orgId>
+      --tags <a,b,c>      Label filter (AND across labels); comma-separated or a JSON array
       --range <json>      Date range as {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}
       --from <date>       Range start (shorthand for --range)
       --to <date>         Range end (shorthand for --range)
@@ -521,6 +522,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli link repo::owner/repo prefer-guards   # open one lesson's detail sheet
   npx @lorekit/cli link global::prefer-guards --json     # { url, surface, base, params }
   npx @lorekit/cli url --q "flaky test" --owner personal # search + ownership filter
+  npx @lorekit/cli link global --tags "perf,ci"          # Explorer filtered to labels
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/deeplink-pure.mjs

@@ -29,14 +29,17 @@ export const LORE_PARAM_DEFAULTS = {
   q: '', // string search query
   range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
   owner: 'all', // 'all' | 'personal' | { orgId }
+  tags: [], // string[] — label filter (AND across labels); [] means "no filter"
   view: 'scope', // 'scope' | 'time'
   archived: false, // boolean
   lesson: null, // { scope, key } | null — opens the detail sheet
 };
 
 // A stable, readable param order (also makes URLs deterministic for tests).
-// `scope` precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'view', 'archived', 'lesson'];
+// Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
+// param last), so `tags` sits between `owner` and `view`. `scope` precedes
+// `lesson` so a lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'tags', 'view', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.
@@ -154,6 +157,44 @@ export function parseViewArg(view) {
   return view === 'time' ? 'time' : 'scope';
 }
 
+// Coerce the `--tags` flag to a normalized `string[]` label filter, mirroring the
+// web app's `normalizeTags` (`packages/web/src/lib/tag-filter.ts`): trim each
+// entry, drop empties, de-duplicate, preserve first-seen order. Accepts either a
+// JSON array string (`'["perf","ci"]'`) or the friendlier comma-separated form
+// (`'perf, ci'`); a malformed JSON array falls back to comma-splitting rather
+// than throwing. Returns `[]` for absent/empty input (the default → omitted from
+// the URL). Pure.
+export function parseTagsArg(tags) {
+  if (Array.isArray(tags)) return normalizeTagList(tags);
+  if (typeof tags !== 'string' || !tags.trim()) return [];
+  const s = tags.trim();
+  if (s.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(s);
+      if (Array.isArray(parsed)) return normalizeTagList(parsed);
+    } catch {
+      /* malformed JSON array → fall through to comma-splitting */
+    }
+  }
+  return normalizeTagList(s.split(','));
+}
+
+// Trim, drop non-string/empty entries, and de-duplicate preserving order. The
+// CLI-side twin of the web's `normalizeTags`; kept inline to keep this module
+// zero-import. Pure.
+function normalizeTagList(list) {
+  const seen = new Set();
+  const out = [];
+  for (const item of list) {
+    if (typeof item !== 'string') continue;
+    const t = item.trim();
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+
 // Coerce the date-range flags to a `{ from, to }` DateRange or null. `--range`
 // (a JSON object string) wins; else `--from`/`--to` shorthand builds one (both
 // keys always present so the shape matches the app's DateRange). A malformed

package/src/link.mjs

@@ -25,6 +25,7 @@ import {
   parseOwnerArg,
   parseViewArg,
   parseRangeArg,
+  parseTagsArg,
   resolveScopeArg,
   surfaceFor,
 } from './deeplink-pure.mjs';
@@ -66,6 +67,7 @@ export async function link(args) {
   const owner = parseOwnerArg(args.owner);
   const view = parseViewArg(args.view);
   const range = parseRangeArg(args);
+  const tags = parseTagsArg(args.tags);
   const archived = Boolean(args.archived);
 
   const gaveAnyInput =
@@ -75,6 +77,7 @@ export async function link(args) {
     owner !== 'all' ||
     view !== 'scope' ||
     range !== null ||
+    tags.length > 0 ||
     archived;
 
   // Bare `lorekit link` (no scope, no lesson, no filters) → the cwd's
@@ -90,6 +93,7 @@ export async function link(args) {
   if (key) params.lesson = { scope, key };
   if (q) params.q = q;
   if (owner !== 'all') params.owner = owner;
+  if (tags.length) params.tags = tags;
   if (view !== 'scope') params.view = view;
   if (range !== null) params.range = range;
   if (archived) params.archived = true;