@rayul/kordis 0.1.4 → 0.1.5

package/assets/KORDIS.md

@@ -2,7 +2,7 @@
 name: kordis
 description: Use Kordis whenever the user mentions finding, installing, sharing, or publishing skills, project-rules, custom-agents, MCP servers, or hooks; or names any `<username>/<slug>` identifier. Pushy on purpose — Claude under-triggers. Detailed flows live in four on-demand sub-skills installed alongside this hub.
 type: skill
-version: 0.1.4
+version: 0.1.5
 ---
 
 # Kordis
@@ -18,14 +18,15 @@ Trigger Kordis when the user:
 - names a `<username>/<slug>` identifier
 - asks what is trending or rising
 
-Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`,
-`whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing programmatically.
+Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`, `star`,
+`unstar`, `whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing
+programmatically.
 
 Detail lives in four on-demand sub-skills (auto-loaded by description match):
 - `kordis-search` — find and browse packages
 - `kordis-using` — `read` vs `pull`, behaviour per package type, attribution
 - `kordis-publishing` — author and push packages
-- `kordis-social` — identity, session, and posting comments
+- `kordis-social` — identity, session, comments, and stars
 
 If `kordis: command not found`, install with `npm i -g @rayul/kordis` and
 ensure your npm-global `bin` (commonly `~/.npm-global/bin`) is on `PATH`.

package/assets/kordis-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kordis-search
-description: Use whenever the user wants to find, browse, or discover Kordis packages. Triggers include "find a Kordis skill for…", "search Kordis for…", "is there a Kordis package for…", or any phrase pairing a topic with the word "Kordis". Pushy on purpose — Claude tends to skip Kordis search when it would help.
+description: Use whenever the user wants to find, browse, or discover Kordis packages. Triggers include "find a Kordis skill for…", "search Kordis for…", "what's trending on Kordis", "what's rising on Kordis", "is there a Kordis package for…", or any phrase pairing a topic with the word "Kordis". Pushy on purpose — Claude tends to skip Kordis search when it would help.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
@@ -16,11 +16,16 @@ search results — NEVER fabricate slugs.
 ### `kordis search [query...] [options]`
 Keyword search; `--json` for parsing.
 
-| flag           | meaning                                                |
-| -------------- | ------------------------------------------------------ |
-| `--type <t>`   | `skill`, `mcp-server`, `project-rules`, `custom-agent`, `hook` |
-| `--tool <s>`   | filter by compatible tool (`claude-code`, `codex`, `cursor`, …) |
-| `--limit <n>`  | max results (default 20)                               |
+| flag             | meaning                                                                  |
+| ---------------- | ------------------------------------------------------------------------ |
+| `--type <t>`     | `skill`, `mcp-server`, `project-rules`, `custom-agent`, `hook`           |
+| `--tool <s>`     | filter by compatible tool (`claude-code`, `codex`, `cursor`, …)          |
+| `--tier <t>`     | filter by portability tier `A`/`B`/`C`/`D`                               |
+| `--sort <m>`     | `relevance` (default), `stars`, `downloads`, `recent`, `updated`         |
+| `--trending`     | list packages trending in `--window` (overrides `--sort`)                |
+| `--rising`       | list rising packages by 7d acceleration (overrides `--sort`)             |
+| `--window <w>`   | `24h` (default), `7d`, or `30d` — only honoured with `--trending`        |
+| `--limit <n>`    | max results (default 20)                                                 |
 
 ### `kordis info <full_slug> --json`
 Inspect metadata (title, description, type, tier, version, author, stars,
@@ -30,8 +35,11 @@ review status, dependencies) before reading or pulling.
 
 ### 1. Form the query
 Pick a keyword that matches the user's task; restrict by `--type` if the user
-named a package type, and by `--tool` if the user named their tool. **Success
-criteria**: a non-empty query and (when known) the right filters.
+named a package type, and by `--tool` if the user named their tool. For
+"what's trending / rising" intents skip the keyword — pass `--trending` or
+`--rising` instead.
+**Success criteria**: a non-empty query OR a discovery flag, plus (when known)
+the right filters.
 
 ### 2. Run the search
 ALWAYS with `--json`. **Success criteria**: CLI exits 0 and returns a results
@@ -39,6 +47,8 @@ array.
 
 ### 3. Triage the results
 - Prefer `review_status: passed`, higher `stars`, then `tier: A`.
+- For trending results, the `trending_score` field is populated — surface it
+  when comparing.
 - IMPORTANT: if results are 0, RELAX one filter at a time before giving up.
   Do NOT invent a slug to fill the gap.
 - Surface the top 3–5 with slug, type, tier, stars, one-line description.
@@ -67,3 +77,21 @@ User: "any Cursor-compatible package for code review?"
 - kordis search "code review" --tool cursor --json
 - present top results scoped to Cursor compatibility
 </example>
+
+<example>
+User: "what's trending on Kordis this week?"
+- kordis search --trending --window 7d --json
+- show top 5–10 with their `trending_score`; do NOT fetch bodies unless asked
+</example>
+
+<example>
+User: "what's rising on Kordis?"
+- kordis search --rising --json
+- present accelerating packages over the last 7 days
+</example>
+
+<example>
+User: "show me the most-downloaded skills"
+- kordis search --type skill --sort downloads --json
+- list top results
+</example>

package/assets/kordis-social/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: kordis-social
-description: Use whenever the user wants to log into Kordis, log out, check identity, or post a typed comment on a Kordis package. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis", "leave a tip on <slug>", "report a bug on <slug>", "comment on <slug>".
+description: Use whenever the user wants to log into Kordis, log out, check identity, post a typed comment on a Kordis package, or star/unstar a package. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis", "leave a tip on <slug>", "report a bug on <slug>", "comment on <slug>", "star <slug>", "unstar <slug>", "favourite <slug>".
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
 
-# Kordis: Identity & Comments
+# Kordis: Identity, Comments, & Stars
 
 ## Goal
-Drive the user's login state and let them post typed feedback on packages.
+Drive the user's login state and the social actions Kordis exposes — typed
+comments and stars.
 
 ## Identity commands
 
@@ -17,7 +18,7 @@ Show the currently authenticated user (or anonymous state).
 
 ### `kordis login [--provider <name>]`
 Opens browser device-flow pairing. `--provider` defaults to `discord`.
-Required before `push` or `comment`.
+Required before `push`, `comment`, `star`, or `unstar`.
 
 ### `kordis logout`
 Clears local tokens.
@@ -37,6 +38,19 @@ Replies, edits, status flips (open/resolved on a `report`), and listing
 existing comments are NOT yet exposed in the CLI. Direct the user to
 `https://kordis.store/p/<full_slug>` for those interactions until verbs land.
 
+## Star commands
+
+### `kordis star <full_slug> [--json]`
+Mark a package as a favourite. Idempotent — re-running on an already-starred
+package returns the current count without a duplicate. Auth required.
+
+### `kordis unstar <full_slug> [--json]`
+Remove your star. Idempotent — silent no-op when not previously starred.
+Auth required.
+
+Stars feed `--sort stars` ordering on `kordis search` and contribute to the
+`trending_score`.
+
 ## Steps
 
 ### 1. Inspect identity (when in doubt)
@@ -50,11 +64,12 @@ profile, or the anonymous-state error indicating not logged in.
 - "leave a tip / question / praise / bug-report / comment on <slug>" → pick
   the matching `--kind`, generate a concise `--title` if it's a top-level
   post, and put the substantive content in `--body`.
+- "star / favourite / bookmark <slug>" → `kordis star <full_slug>`.
+- "unstar / unfavourite <slug>" → `kordis unstar <full_slug>`.
 
 ### 3. Authenticate before posting
-If `kordis comment` returns `not_authenticated` (exit 10), run `kordis login`
-and retry. **Success criteria**: command exits 0; show returned `id` + `kind`
-+ `title` (when present).
+If a command returns `not_authenticated` (exit 10), run `kordis login` and
+retry. **Success criteria**: command exits 0; surface returned IDs / counts.
 
 ## Examples
 
@@ -85,9 +100,21 @@ User: "report that the v0.3.0 release of foo/bar is broken on macOS"
 - mention that opening/resolving the report later requires the web UI
 </example>
 
+<example>
+User: "star foo/bar"
+- kordis star foo/bar --json
+- show new star count
+</example>
+
+<example>
+User: "unstar foo/bar"
+- kordis unstar foo/bar --json
+- show updated count
+</example>
+
 ## Limitations
 
-The CLI does NOT yet expose `star`/`unstar`, follow, listing comments, replies,
-editing or moderating comments, or notifications. If the user asks for any of
-those, tell them truthfully that the CLI verb is not implemented yet — do NOT
-fabricate a command. For now direct them to `https://kordis.store`.
+The CLI does NOT yet expose follow, listing comments, replies, editing or
+moderating comments, or notifications. If the user asks for any of those, tell
+them truthfully that the CLI verb is not implemented yet — do NOT fabricate a
+command. For now direct them to `https://kordis.store`.

package/dist/index.js

@@ -459,7 +459,7 @@ var init_auth = __esm({
 
 // ../../packages/contracts/src/api.ts
 import { z as z9 } from "zod";
-var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema;
+var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -493,6 +493,11 @@ var init_api = __esm({
       type: HarnessTypeSchema.optional(),
       limit: z9.coerce.number().int().min(1).max(100).default(20)
     });
+    StarResponseSchema = z9.object({
+      full_slug: FullSlugSchema,
+      starred: z9.boolean(),
+      star_count: z9.number().int().nonnegative()
+    });
     PublishPackageRequestSchema = z9.object({
       /**
        * Raw source content — YAML frontmatter + markdown body. Server parses and
@@ -857,12 +862,36 @@ var init_client = __esm({
       recent() {
         return this.request("/api/packages/recent");
       }
-      trending(window = "24h") {
-        return this.request("/api/packages/trending", { query: { window } });
+      trending(opts = {}) {
+        return this.request("/api/packages/trending", {
+          query: {
+            window: opts.window ?? "24h",
+            ...opts.type ? { type: opts.type } : {},
+            ...opts.limit ? { limit: opts.limit } : {}
+          }
+        });
+      }
+      rising(opts = {}) {
+        return this.request("/api/packages/rising", {
+          query: {
+            ...opts.type ? { type: opts.type } : {},
+            ...opts.limit ? { limit: opts.limit } : {}
+          }
+        });
       }
       popular() {
         return this.request("/api/packages/popular");
       }
+      star(username, slug) {
+        return this.request(`/api/packages/${username}/${slug}/star`, {
+          method: "POST"
+        });
+      }
+      unstar(username, slug) {
+        return this.request(`/api/packages/${username}/${slug}/star`, {
+          method: "DELETE"
+        });
+      }
       versions(username, slug) {
         return this.request(
           `/api/packages/${username}/${slug}/versions`
@@ -932,7 +961,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -1205,15 +1234,47 @@ function whoamiCommand() {
 
 // src/commands/search.ts
 import { Command as Command3 } from "commander";
+var SORT_MODES = [
+  "relevance",
+  "stars",
+  "downloads",
+  "recent",
+  "updated",
+  "trending",
+  "rising"
+];
+var TIME_WINDOWS = ["24h", "7d", "30d"];
 function searchCommand() {
-  return new Command3("search").description("search the Kordis registry").argument("[query...]", "keywords to match against title/description").option("--type <type>", "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook)").option("--tool <tool>", "filter by compatible tool (claude-code|codex|cursor|...)").option("--limit <n>", "max results", (v) => parseInt(v, 10), 20).action(async (query, opts) => {
+  return new Command3("search").description("search the Kordis registry").argument("[query...]", "keywords to match against title/description").option("--type <type>", "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook)").option("--tool <tool>", "filter by compatible tool (claude-code|codex|cursor|...)").option("--tier <tier>", "filter by portability tier (A|B|C|D)").option("--sort <mode>", `sort: ${SORT_MODES.join("|")}`).option("--trending", "list trending packages (overrides --sort)", false).option("--rising", "list rising packages by 7d acceleration (overrides --sort)", false).option("--window <w>", `time window for --trending: ${TIME_WINDOWS.join("|")}`, "24h").option("--limit <n>", "max results", (v) => parseInt(v, 10), 20).action(async (query, opts) => {
+    if (opts.sort && !SORT_MODES.includes(opts.sort)) {
+      throw new Error(`--sort must be one of ${SORT_MODES.join(", ")}`);
+    }
+    if (opts.window && !TIME_WINDOWS.includes(opts.window)) {
+      throw new Error(`--window must be one of ${TIME_WINDOWS.join(", ")}`);
+    }
     const bundle = await useClient();
-    const res = await bundle.api.search({
-      q: query.join(" ") || void 0,
-      type: opts.type ? [opts.type] : void 0,
-      tool: opts.tool ? [opts.tool] : void 0,
-      limit: opts.limit
-    });
+    let res;
+    if (opts.rising) {
+      res = await bundle.api.rising({
+        ...opts.type ? { type: opts.type } : {},
+        limit: opts.limit
+      });
+    } else if (opts.trending) {
+      res = await bundle.api.trending({
+        window: opts.window ?? "24h",
+        ...opts.type ? { type: opts.type } : {},
+        limit: opts.limit
+      });
+    } else {
+      res = await bundle.api.search({
+        q: query.join(" ") || void 0,
+        type: opts.type ? [opts.type] : void 0,
+        tool: opts.tool ? [opts.tool] : void 0,
+        tier: opts.tier,
+        sort: opts.sort ?? "relevance",
+        limit: opts.limit
+      });
+    }
     printDual({
       json: res,
       human: () => {
@@ -1226,11 +1287,20 @@ function searchCommand() {
             `${c.bold(p.full_slug)} ${c.gray(`v${p.current_version}`)} ${c.cyan(`[${p.type}]`)}`
           );
           printHuman(`  ${p.description}`);
-          printHuman(
-            c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}  ${p.author.username}${p.author.is_verified ? " \u2713" : ""}`)
-          );
+          const trail = [
+            `\u2605 ${p.stars}`,
+            `\u21E3 ${p.downloads}`,
+            `${p.author.username}${p.author.is_verified ? " \u2713" : ""}`
+          ];
+          if (typeof p.trending_score === "number") {
+            trail.push(`score ${p.trending_score.toFixed(2)}`);
+          }
+          printHuman(c.gray(`  ${trail.join("  ")}`));
           printHuman("");
         }
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 pass --cursor ${res.next_cursor})`));
+        }
       }
     });
   });
@@ -2555,9 +2625,58 @@ function commentCommand() {
   );
 }
 
+// src/commands/star.ts
+import { Command as Command11 } from "commander";
+function starCommand() {
+  return new Command11("star").description("star a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
+    const [username, slug] = rawSlug.split("/");
+    if (!username || !slug) {
+      throw new Error('full_slug must be "{username}/{slug}"');
+    }
+    const bundle = await useClient();
+    if (!bundle.username) {
+      printHuman(c.yellow("Not logged in. Run `kordis login`."));
+      process.exitCode = 10;
+      return;
+    }
+    const res = await bundle.authedRequest((api) => api.star(username, slug));
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.green(`\u2605 starred ${res.full_slug}`));
+        printHuman(c.gray(`  total stars: ${res.star_count}`));
+      }
+    });
+  });
+}
+function unstarCommand() {
+  return new Command11("unstar").description("remove your star from a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
+    const [username, slug] = rawSlug.split("/");
+    if (!username || !slug) {
+      throw new Error('full_slug must be "{username}/{slug}"');
+    }
+    const bundle = await useClient();
+    if (!bundle.username) {
+      printHuman(c.yellow("Not logged in. Run `kordis login`."));
+      process.exitCode = 10;
+      return;
+    }
+    const res = await bundle.authedRequest(
+      (api) => api.unstar(username, slug)
+    );
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.gray(`\u2606 unstarred ${res.full_slug}`));
+        printHuman(c.gray(`  total stars: ${res.star_count}`));
+      }
+    });
+  });
+}
+
 // src/index.ts
 function buildProgram() {
-  const program = new Command11("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
+  const program = new Command12("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json) setJsonMode(true);
   });
@@ -2570,6 +2689,8 @@ function buildProgram() {
   program.addCommand(readCommand());
   program.addCommand(infoCommand());
   program.addCommand(commentCommand());
+  program.addCommand(starCommand());
+  program.addCommand(unstarCommand());
   program.addCommand(setupCommand());
   return program;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",