@rayul/kordis 0.7.1 → 0.8.0

package/assets/kordis-social/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: kordis-social
-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>".
+description: Use whenever the user wants to log into Kordis, log out, check identity, post a typed comment on a Kordis package, star/unstar a package, view a user's public profile, list their packages or stars, or follow/unfollow another user. 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>", "follow <username>", "unfollow <username>", "팔로우", "팔로워", "show me <username>'s profile", "프로필", "what has <username> starred", "who follows <username>", "who does <username> follow".
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
 
-# Kordis: Identity, Comments, & Stars
+# Kordis: Identity, Comments, Stars, & Social
 
 ## Goal
 Drive the user's login state and the social actions Kordis exposes — typed
-comments and stars.
+comments, stars, public profiles, and follow/unfollow (0.8.0+).
 
 ## Identity commands
 
@@ -127,9 +127,72 @@ User: "unstar foo/bar"
 - show updated count
 </example>
 
+## Profile & follow commands (0.8.0+)
+
+### `kordis profile <username>`
+Anonymous-OK. Shows display name, bio, follower count, package count,
+total stars, total downloads, first/last published timestamps.
+
+### `kordis list <username>` (extended)
+With no argument → your own packages (auth required, offset pagination).
+With a username → public packages of that user (anonymous-OK, cursor
+pagination via `--cursor`).
+
+### `kordis stars <username>`
+Anonymous-OK. Lists packages this user has starred. Cursor-paginated.
+
+### `kordis follow <username>` / `kordis unfollow <username>`
+Auth required. Idempotent (re-following is a no-op, no double-count).
+Self-follow is rejected with `usage_error`. Response carries the
+post-mutation `follower_count` so you don't need a separate GET.
+
+### `kordis followers <username>` / `kordis following <username>`
+Anonymous-OK, cursor-paginated. Returns `PublicUser` rows.
+
+<example>
+User: "show me alice's profile"
+- kordis profile alice --json
+- render display_name, bio, package_count, follower_count, joined date
+</example>
+
+<example>
+User: "follow alice"
+- ALWAYS check the user is logged in first (`kordis whoami --json`); if
+  not authenticated, prompt them to run `kordis login --emit-only`
+- kordis follow alice --json
+- report the updated follower_count from the response
+</example>
+
+<example>
+User: "what has bob starred?" / "bob이 별 누른거 보여줘"
+- kordis stars bob --json
+- render top results; offer `--cursor` for the next page if `next_cursor` is non-null
+</example>
+
+<example>
+User: "who follows alice?"
+- kordis followers alice --json
+- list users; for each, display username + display_name + follower_count
+</example>
+
+<example>
+User: "i don't want to follow alice anymore"
+- ALWAYS confirm the user intent before destructive social actions (unfollow IS reversible — re-following is one command — but a courtesy confirm avoids surprises)
+- kordis unfollow alice --json
+- report the new follower_count
+</example>
+
+<example>
+User: "kordis list popular"
+- this is a sort-keyword collision — `popular` is NOT a username
+- the CLI catches this client-side and points the user at `--sort popular`
+- show the error message verbatim; don't try to "fix" it by guessing
+</example>
+
 ## Limitations
 
-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`.
+The CLI now exposes follow/unfollow + profile + public list/stars
+(0.8.0+). Still NOT exposed: listing comments per user (use `kordis
+comments <full_slug>` for per-package), per-user blocklists,
+notifications, friend recommendations. For those direct the user to
+`https://kordis.store` or wait for the next minor.

package/dist/index.js

@@ -486,7 +486,7 @@ var init_auth = __esm({
 
 // ../../packages/contracts/src/api.ts
 import { z as z9 } from "zod";
-var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema;
+var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -709,6 +709,26 @@ var init_api = __esm({
       limit: z9.coerce.number().int().min(1).max(100).default(20),
       cursor: CursorSchema.optional()
     });
+    ListUserPackagesResponseSchema = z9.object({
+      results: PackageSummarySchema.array(),
+      next_cursor: z9.string().nullable()
+    });
+    ListUserStarsResponseSchema = z9.object({
+      results: PackageSummarySchema.array(),
+      next_cursor: z9.string().nullable()
+    });
+    FollowResponseSchema = z9.object({
+      following: z9.boolean(),
+      follower_count: z9.number().int().nonnegative()
+    });
+    ListFollowersQuerySchema = z9.object({
+      limit: z9.coerce.number().int().min(1).max(100).default(50),
+      cursor: CursorSchema.optional()
+    });
+    ListFollowersResponseSchema = z9.object({
+      results: PublicUserSchema.array(),
+      next_cursor: z9.string().nullable()
+    });
   }
 });
 
@@ -912,6 +932,34 @@ var init_src = __esm({
 });
 
 // ../../packages/api-client/src/errors.ts
+function httpStatusToCode(status) {
+  if (status === 401) return "not_authenticated";
+  if (status === 403) return "not_authorized";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "internal_error";
+  if (status >= 400) return "usage_error";
+  return "generic_failure";
+}
+function normalizeErrorEnvelope(status, parsed, fallbackText) {
+  const isObject = (v) => typeof v === "object" && v !== null;
+  if (isObject(parsed) && isObject(parsed.error) && typeof parsed.error.code === "string" && typeof parsed.error.message === "string") {
+    return parsed;
+  }
+  let message;
+  if (isObject(parsed) && typeof parsed.message === "string") {
+    message = parsed.message;
+  } else if (fallbackText) {
+    message = fallbackText.slice(0, 500);
+  }
+  return {
+    error: {
+      code: httpStatusToCode(status),
+      message: message ?? `HTTP ${status}`
+    }
+  };
+}
 var KordisApiError, KordisNetworkError;
 var init_errors2 = __esm({
   "../../packages/api-client/src/errors.ts"() {
@@ -1027,7 +1075,8 @@ var init_client = __esm({
         const text = await res.text();
         const parsed = text ? JSON.parse(text) : void 0;
         if (!res.ok) {
-          throw new KordisApiError(res.status, parsed, requestId);
+          const envelope = normalizeErrorEnvelope(res.status, parsed, text);
+          throw new KordisApiError(res.status, envelope, requestId);
         }
         return parsed;
       }
@@ -1233,6 +1282,51 @@ var init_client = __esm({
           body: payload
         });
       }
+      // ─── social (0.8.0+) ───────────────────────────────────────────────────
+      /** Public profile + aggregated stats. Anonymous-OK. */
+      getUserProfile(username) {
+        return this.request(`/api/users/${encodeURIComponent(username)}`);
+      }
+      /** Cursor-paginated public package list authored by `username`. */
+      listUserPackages(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/packages`,
+          { query }
+        );
+      }
+      /** Cursor-paginated packages that `username` has starred. */
+      listUserStars(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/stars`,
+          { query }
+        );
+      }
+      /** Auth-required. Idempotent (re-follow is a no-op). Returns post-mutation counter. */
+      followUser(username) {
+        return this.request(`/api/users/${encodeURIComponent(username)}/follow`, {
+          method: "POST"
+        });
+      }
+      /** Auth-required. Idempotent (unfollow of non-edge is a no-op). */
+      unfollowUser(username) {
+        return this.request(`/api/users/${encodeURIComponent(username)}/follow`, {
+          method: "DELETE"
+        });
+      }
+      /** Cursor-paginated followers of `username`. Anonymous-OK. */
+      listUserFollowers(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/followers`,
+          { query }
+        );
+      }
+      /** Cursor-paginated users that `username` follows. Anonymous-OK. */
+      listUserFollowing(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/following`,
+          { query }
+        );
+      }
     };
   }
 });
@@ -1242,7 +1336,8 @@ var src_exports = {};
 __export(src_exports, {
   KordisApiError: () => KordisApiError,
   KordisClient: () => KordisClient,
-  KordisNetworkError: () => KordisNetworkError
+  KordisNetworkError: () => KordisNetworkError,
+  normalizeErrorEnvelope: () => normalizeErrorEnvelope
 });
 var init_src2 = __esm({
   "../../packages/api-client/src/index.ts"() {
@@ -1254,7 +1349,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command19 } from "commander";
+import { Command as Command23 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -4294,44 +4389,91 @@ function deleteCommand() {
 
 // src/commands/list.ts
 import { Command as Command13 } from "commander";
+
+// src/lib/parse-username.ts
+init_src();
+var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
+function parseUsername(raw) {
+  if (SORT_KEYWORDS.includes(raw.toLowerCase())) {
+    throw new Error(
+      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`
+    );
+  }
+  const parsed = UsernameSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`
+    );
+  }
+  return parsed.data;
+}
+
+// src/commands/list.ts
 function listCommand() {
-  return new Command13("list").description("list your own packages (requires login)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10), 1).option("--sort <mode>", "sort: latest|popular", "latest").action(async (opts) => {
-    const sort = opts.sort === "popular" ? "popular" : "latest";
+  return new Command13("list").description("list packages \u2014 your own (no arg) or a public user\u2019s (with <username>)").argument("[username]", "kordis username to list (omit for self)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "self-mode page number (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "public-mode pagination cursor").option("--sort <mode>", "sort: latest|popular (self) or stars|downloads|recent|updated (public)", "latest").action(async (rawUsername, opts) => {
     const bundle = await useClient();
-    requireAuth(bundle);
-    const spin = spinner("Fetching your packages");
-    const res = await bundle.authedRequest(
-      (api) => api.listMyPackages({ page: opts.page, limit: opts.limit, sort })
-    );
-    spin.succeed();
+    if (rawUsername === void 0) {
+      requireAuth(bundle);
+      const sort = opts.sort === "popular" ? "popular" : "latest";
+      const spin = spinner("Fetching your packages");
+      const res2 = await bundle.authedRequest(
+        (api) => api.listMyPackages({ page: opts.page, limit: opts.limit, sort })
+      );
+      spin.succeed();
+      printDual({
+        json: res2,
+        human: () => {
+          if (res2.packages.length === 0) {
+            printHuman(c.yellow("(no packages yet \u2014 use `kordis push` to publish your first)"));
+            return;
+          }
+          printHuman(
+            c.gray(
+              `Showing ${res2.packages.length} of ${res2.total} package${res2.total !== 1 ? "s" : ""} (page ${res2.page})`
+            )
+          );
+          printHuman("");
+          for (const p of res2.packages) {
+            const desc = p.description.length > 60 ? p.description.slice(0, 57) + "..." : p.description;
+            printHuman(
+              `${c.bold(p.full_slug)} ${c.gray(`v${p.current_version}`)} ${c.cyan(`[${p.type}]`)}`
+            );
+            printHuman(`  ${desc}`);
+            printHuman(c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}  ${p.visibility}`));
+            printHuman("");
+          }
+          if (res2.page * res2.limit < res2.total) {
+            printHuman(c.gray(`(more available \u2014 pass --page ${res2.page + 1})`));
+          }
+        }
+      });
+      return;
+    }
+    const username = parseUsername(rawUsername);
+    const publicSort = ["stars", "downloads", "recent", "updated"].includes(opts.sort) ? opts.sort : "stars";
+    const res = await bundle.api.listUserPackages(username, {
+      limit: opts.limit,
+      sort: publicSort,
+      ...opts.cursor ? { cursor: opts.cursor } : {}
+    });
     printDual({
       json: res,
       human: () => {
-        if (res.packages.length === 0) {
-          printHuman(c.yellow("(no packages yet \u2014 use `kordis push` to publish your first)"));
+        if (res.results.length === 0) {
+          printHuman(c.yellow(`(no public packages for ${username})`));
           return;
         }
-        printHuman(
-          c.gray(
-            `Showing ${res.packages.length} of ${res.total} package${res.total !== 1 ? "s" : ""} (page ${res.page})`
-          )
-        );
-        printHuman("");
-        for (const p of res.packages) {
+        for (const p of res.results) {
           const desc = p.description.length > 60 ? p.description.slice(0, 57) + "..." : p.description;
           printHuman(
-            `${c.bold(p.full_slug)} ${c.gray(`v${p.current_version}`)} ${c.cyan(`[${p.type}]`)}`
+            `${c.bold(p.full_slug)} ${c.gray("v" + p.current_version)} ${c.cyan("[" + p.type + "]")}`
           );
           printHuman(`  ${desc}`);
-          printHuman(
-            c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}  ${p.visibility}`)
-          );
+          printHuman(c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}`));
           printHuman("");
         }
-        if (res.page * res.limit < res.total) {
-          printHuman(
-            c.gray(`(more available \u2014 pass --page ${res.page + 1})`)
-          );
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis list ${username} --cursor ${res.next_cursor})`));
         }
       }
     });
@@ -4793,9 +4935,159 @@ function renderItem(idx, it, verbose) {
   printHuman("");
 }
 
+// src/commands/profile.ts
+import { Command as Command19 } from "commander";
+function profileCommand() {
+  return new Command19("profile").description("inspect a user\u2019s public profile").argument("<username>", "kordis username").action(async (raw) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    const profile = await bundle.api.getUserProfile(username);
+    printDual({
+      json: profile,
+      human: () => {
+        const verified = profile.is_verified ? c.cyan(" \u2713") : "";
+        const displayLine = profile.display_name ? `${c.bold(profile.username)}${verified}  ${c.gray("(" + profile.display_name + ")")}` : `${c.bold(profile.username)}${verified}`;
+        printHuman(displayLine);
+        if (profile.bio) printHuman(c.gray(profile.bio));
+        printHuman("");
+        printHuman(
+          `  ${c.bold(String(profile.stats.package_count))} packages  \xB7  ${c.bold(String(profile.stats.total_stars))} \u2605 across all  \xB7  ${c.bold(String(profile.stats.total_downloads))} downloads`
+        );
+        printHuman(
+          `  ${c.bold(String(profile.follower_count))} follower${profile.follower_count === 1 ? "" : "s"}  \xB7  joined ${profile.created_at.split("T")[0]}`
+        );
+        if (profile.stats.last_published_at) {
+          printHuman(
+            c.gray(
+              `  last published: ${profile.stats.last_published_at.split("T")[0]}`
+            )
+          );
+        }
+        printHuman("");
+        printHuman(c.gray(`  \u2192 list packages: kordis list ${profile.username}`));
+        printHuman(c.gray(`  \u2192 list stars:    kordis stars ${profile.username}`));
+        printHuman(c.gray(`  \u2192 follow:        kordis follow ${profile.username}`));
+      }
+    });
+  });
+}
+
+// src/commands/stars.ts
+import { Command as Command20 } from "commander";
+function starsCommand() {
+  return new Command20("stars").description("list packages a user has starred").argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    const res = await bundle.api.listUserStars(username, {
+      limit: opts.limit,
+      ...opts.cursor ? { cursor: opts.cursor } : {}
+    });
+    printDual({
+      json: res,
+      human: () => {
+        if (res.results.length === 0) {
+          printHuman(c.yellow(`(no stars yet for ${username})`));
+          printHuman(c.gray(`  \u2192 they may not have starred any public packages, or have set stars to private`));
+          return;
+        }
+        for (const p of res.results) {
+          printHuman(
+            `${c.bold(p.full_slug)} ${c.gray("v" + p.current_version)} ${c.cyan("[" + p.type + "]")}`
+          );
+          printHuman(`  ${p.description}`);
+          printHuman(c.gray(`  \u2605 ${p.stars}  \xB7  \u21E3 ${p.downloads}`));
+          printHuman("");
+        }
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis stars ${username} --cursor ${res.next_cursor})`));
+        }
+      }
+    });
+  });
+}
+
+// src/commands/follow.ts
+import { Command as Command21 } from "commander";
+function followCommand() {
+  return new Command21("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    requireAuth(bundle);
+    const res = await bundle.authedRequest((api) => api.followUser(username));
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.green(`\u2713 following ${username}`));
+        printHuman(c.gray(`  total followers: ${res.follower_count}`));
+      }
+    });
+  });
+}
+function unfollowCommand() {
+  return new Command21("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    requireAuth(bundle);
+    const res = await bundle.authedRequest((api) => api.unfollowUser(username));
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.gray(`\u2717 unfollowed ${username}`));
+        printHuman(c.gray(`  total followers: ${res.follower_count}`));
+      }
+    });
+  });
+}
+
+// src/commands/followers.ts
+import { Command as Command22 } from "commander";
+function makeListing(name) {
+  return new Command22(name).description(
+    name === "followers" ? "list users following <username>" : "list users that <username> follows"
+  ).argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    const fn = name === "followers" ? bundle.api.listUserFollowers.bind(bundle.api) : bundle.api.listUserFollowing.bind(bundle.api);
+    const res = await fn(username, {
+      limit: opts.limit,
+      ...opts.cursor ? { cursor: opts.cursor } : {}
+    });
+    printDual({
+      json: res,
+      human: () => {
+        if (res.results.length === 0) {
+          const noun = name === "followers" ? "followers yet" : "one yet";
+          printHuman(c.yellow(`(no ${noun} for ${username})`));
+          return;
+        }
+        for (const u of res.results) {
+          const verified = u.is_verified ? c.cyan(" \u2713") : "";
+          const display = u.display_name ? ` ${c.gray("(" + u.display_name + ")")}` : "";
+          printHuman(`${c.bold(u.username)}${verified}${display}`);
+          printHuman(
+            c.gray(
+              `  ${u.follower_count} follower${u.follower_count === 1 ? "" : "s"}  \xB7  joined ${u.created_at.split("T")[0]}`
+            )
+          );
+          printHuman("");
+        }
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis ${name} ${username} --cursor ${res.next_cursor})`));
+        }
+      }
+    });
+  });
+}
+function followersCommand() {
+  return makeListing("followers");
+}
+function followingCommand() {
+  return makeListing("following");
+}
+
 // src/index.ts
 function buildProgram() {
-  const program = new Command19("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 Command23("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);
   }).addHelpText("after", `
@@ -4821,6 +5113,12 @@ Environment variables (see README.md "Privacy & environment variables"):
   program.addCommand(uncommentCommand());
   program.addCommand(starCommand());
   program.addCommand(unstarCommand());
+  program.addCommand(profileCommand());
+  program.addCommand(starsCommand());
+  program.addCommand(followCommand());
+  program.addCommand(unfollowCommand());
+  program.addCommand(followersCommand());
+  program.addCommand(followingCommand());
   program.addCommand(deleteCommand());
   program.addCommand(listCommand());
   program.addCommand(versionsCommand());

package/package.json

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