@rayul/kordis 0.11.0 → 0.11.1

package/dist/index.js

@@ -20,7 +20,7 @@ var init_primitives = __esm({
     UsernameSchema = z.string().min(3).max(32).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "username must be lowercase alphanumeric with single hyphens");
     SlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "slug must be lowercase alphanumeric with single hyphens");
     FullSlugSchema = z.string().min(5).max(128).regex(/^[a-z0-9](-?[a-z0-9])*\/[a-z0-9](-?[a-z0-9])*$/, "full_slug must match {username}/{slug}");
-    SemverSchema = z.string().regex(
+    SemverSchema = z.string().max(32).regex(
       // eslint-disable-next-line no-useless-escape
       /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
       "must be a valid semver version"
@@ -478,8 +478,8 @@ var init_auth = __esm({
     });
     DeviceCodeResponseSchema = z8.object({
       device_code: z8.string().min(16),
-      user_code: z8.string().length(8),
-      // shown to the user: e.g. "KORDIS-AB12"
+      user_code: z8.string().regex(/^KORDIS-[0-9A-Z]{4}-[0-9A-Z]{4}$/),
+      // shown to the user: e.g. "KORDIS-7QFX-2M9K"
       verification_url: z8.string().url(),
       expires_in: z8.number().int().positive(),
       // seconds
@@ -1153,7 +1153,7 @@ var init_client = __esm({
                   `[kordis] api: ${method} ${url.pathname}${url.search} \u2192 fetch failed, retrying in 150ms (${err.message})`
                 );
               }
-              await new Promise((resolve2) => setTimeout(resolve2, 150));
+              await new Promise((resolve3) => setTimeout(resolve3, 150));
               continue;
             }
           }
@@ -1178,7 +1178,12 @@ var init_client = __esm({
         }
         if (res.status === 204) return void 0;
         const text = await res.text();
-        const parsed = text ? JSON.parse(text) : void 0;
+        let parsed;
+        try {
+          parsed = text ? JSON.parse(text) : void 0;
+        } catch {
+          parsed = void 0;
+        }
         if (!res.ok) {
           const envelope = normalizeErrorEnvelope(res.status, parsed, text);
           throw new KordisApiError(res.status, envelope, requestId);
@@ -1919,7 +1924,7 @@ async function reportError(kind, err, extras = {}) {
     });
     await Promise.race([
       client.recordTelemetryError(payload),
-      new Promise((resolve2) => setTimeout(resolve2, REPORT_TIMEOUT_MS))
+      new Promise((resolve3) => setTimeout(resolve3, REPORT_TIMEOUT_MS))
     ]);
   } catch {
   }
@@ -2505,8 +2510,8 @@ function normaliseDep(entry, idx) {
       );
     }
     return {
-      full_slug: m[1],
-      version_range: (m[4] ?? "*").trim()
+      full_slug: FullSlugSchema.parse(m[1]),
+      version_range: SemverRangeSchema.parse((m[4] ?? "*").trim())
     };
   }
   if (typeof entry === "object" && entry !== null) {
@@ -2962,7 +2967,7 @@ var ASSET_MAX_COUNT = 50;
 var SAFE_PATH_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/;
 function isAssetPathSafe(p) {
   if (!SAFE_PATH_RE.test(p)) return false;
-  return !p.split("/").some((seg) => seg === "..");
+  return p.split("/").every((seg) => seg.length > 0 && seg !== "." && seg !== "..");
 }
 function validateAssets(assets) {
   const flags = [];
@@ -3255,7 +3260,11 @@ async function bundleSkillZip(zipPath) {
   const buf = await readFile6(zipPath);
   const zip = await JSZip.loadAsync(buf);
   const entries = Object.keys(zip.files).filter((k) => !zip.files[k].dir);
-  if (entries.length === 0) throw new Error(".skill file is empty");
+  if (entries.length === 0) {
+    const e = new Error(".skill file is empty");
+    e.hint = "The .skill archive contains no files. Re-export the .skill from skill-creator, or push the unpacked skill directory instead (the dir containing SKILL.md).";
+    throw e;
+  }
   const firstParts = entries[0].split("/");
   const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
   const stripped = entries.map((k) => ({
@@ -3264,7 +3273,11 @@ async function bundleSkillZip(zipPath) {
   })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
   const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
   if (!skillEntry) {
-    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
+    const e = new Error(
+      `.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`
+    );
+    e.hint = "SKILL.md must sit at <skill-name>/SKILL.md at the archive root. Re-package so the single top-level directory contains SKILL.md (skill-creator does this by default).";
+    throw e;
   }
   const content = await zip.files[skillEntry.zipKey].async("string");
   const assets = [];
@@ -3287,7 +3300,7 @@ async function bundleSkillZip(zipPath) {
 // src/commands/pull.ts
 import { Command as Command5 } from "commander";
 import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname2, join as join9 } from "path";
+import { dirname as dirname2, join as join9, resolve as resolve2, sep as sep2 } from "path";
 
 // ../../packages/translators/src/skill/identity.ts
 function buildSkillFile(input, outputPath) {
@@ -3531,13 +3544,13 @@ var mcpToContinue = (input) => {
     }
     if (t.env && Object.keys(t.env).length > 0) {
       lines.push("env:");
-      for (const [k, v] of Object.entries(t.env)) lines.push(`  ${k}: ${JSON.stringify(v)}`);
+      for (const [k, v] of Object.entries(t.env)) lines.push(`  ${JSON.stringify(k)}: ${JSON.stringify(v)}`);
     }
   } else {
     lines.push(`type: ${t.type}`, `url: ${JSON.stringify(t.url)}`);
     if (t.headers && Object.keys(t.headers).length > 0) {
       lines.push("headers:");
-      for (const [k, v] of Object.entries(t.headers)) lines.push(`  ${k}: ${JSON.stringify(v)}`);
+      for (const [k, v] of Object.entries(t.headers)) lines.push(`  ${JSON.stringify(k)}: ${JSON.stringify(v)}`);
     }
   }
   return {
@@ -3764,16 +3777,23 @@ async function recordInstalled(fullSlug, entry) {
 // src/lib/parse-username.ts
 init_src();
 var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
+function usernameError(message, hint) {
+  const e = new Error(message);
+  e.hint = hint;
+  return e;
+}
 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).`
+    throw usernameError(
+      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`,
+      `Pass it as the sort flag instead, e.g. \`--sort ${raw}\`, or supply an actual username argument.`
     );
   }
   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")`
+    throw usernameError(
+      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`,
+      "Usernames are lowercase alphanumeric with single hyphens. Browse existing users with `kordis search` or look one up with `kordis profile <username>`."
     );
   }
   return parsed.data;
@@ -3839,7 +3859,11 @@ function parseSlugAtVersion(raw) {
 // src/commands/pull.ts
 async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   const [username, slug] = fullSlug.split("/");
-  if (!username || !slug) throw new Error('full_slug must be "{username}/{slug}"');
+  if (!username || !slug) {
+    const e = new Error('full_slug must be "{username}/{slug}"');
+    e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+    throw e;
+  }
   const bundle = await useClient();
   const pullRes = await bundle.api.pull(username, slug, {
     ...opts.version ? { version: opts.version } : {},
@@ -3854,7 +3878,9 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   });
   const parsed = validatePackageSource(contentRes.content);
   if (!parsed.ok || !parsed.type || !parsed.frontmatter) {
-    throw new Error("package stored content is not currently valid");
+    const e = new Error("package stored content is not currently valid");
+    e.hint = `This version's stored bytes no longer pass validation. Try another version via \`kordis versions ${fullSlug}\` (then pull a specific \`@<version>\`), or re-push a corrected version if you authored it.`;
+    throw e;
   }
   const written = [];
   const notes = [];
@@ -3869,7 +3895,7 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
       assets: contentRes.assets
     });
     for (const f of result.files) {
-      const abs = join9(installRoot, f.path);
+      const abs = safeInstallPath(installRoot, f.path);
       await mkdir6(dirname2(abs), { recursive: true });
       await writeEmittedFile(abs, f.content, f.encoding);
       written.push(abs);
@@ -3889,7 +3915,7 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
         `Tool "${format}" is not supported for type "${parsed.type}"; installed canonical form instead.`
       );
       for (const f of result.files) {
-        const abs = join9(installRoot, f.path);
+        const abs = safeInstallPath(installRoot, f.path);
         await mkdir6(dirname2(abs), { recursive: true });
         await writeEmittedFile(abs, f.content, f.encoding);
         written.push(abs);
@@ -4052,6 +4078,26 @@ async function detectTool(root) {
   }
   return null;
 }
+function safeInstallPath(installRoot, relPath) {
+  if (relPath.startsWith("/") || resolve2(relPath) === relPath) {
+    const e = new Error(
+      `refusing to write absolute path "${relPath}" outside the install root`
+    );
+    e.hint = "Package emitted an absolute file path. Re-push the package with relative paths only; report it to the author if you did not publish it.";
+    throw e;
+  }
+  const abs = join9(installRoot, relPath);
+  const resolvedRoot = resolve2(installRoot);
+  const resolvedAbs = resolve2(abs);
+  if (resolvedAbs !== resolvedRoot && !resolvedAbs.startsWith(resolvedRoot + sep2)) {
+    const e = new Error(
+      `refusing to write "${relPath}" \u2014 resolves outside the install root`
+    );
+    e.hint = "Package tried to write outside the install directory (path traversal). Re-push the package with relative in-tree paths only; report it to the author if you did not publish it.";
+    throw e;
+  }
+  return abs;
+}
 async function writeEmittedFile(abs, content, encoding) {
   if (encoding === "base64") {
     await writeFile6(abs, Buffer.from(content, "base64"));
@@ -4549,7 +4595,9 @@ function commentsCommand() {
     async (rawSlug, opts) => {
       const [username, slug] = rawSlug.split("/");
       if (!username || !slug) {
-        throw new Error('full_slug must be "{username}/{slug}"');
+        const e = new Error('full_slug must be "{username}/{slug}"');
+        e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+        throw e;
       }
       if (opts.kind && !KINDS.includes(opts.kind)) {
         throw new Error(`--kind must be one of ${KINDS.join(", ")}`);
@@ -4564,14 +4612,13 @@ function commentsCommand() {
         ...opts.kind ? { kind: opts.kind } : {},
         ...opts.sort ? { sort: opts.sort } : {}
       });
+      const emptyHint = "no comments yet \u2014 be the first: kordis comment " + rawSlug + ' --body "..."';
       printDual({
-        json: res,
+        json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
         human: () => {
           if (res.results.length === 0) {
             printHuman(c.yellow("(no comments)"));
-            printHuman(
-              c.gray("  \u2192 be the first: kordis comment " + rawSlug + ' --body "..."')
-            );
+            printHuman(c.gray("  \u2192 " + emptyHint));
             return;
           }
           printHuman(
@@ -4639,7 +4686,9 @@ 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 e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     requireAuth(bundle);
@@ -4657,7 +4706,9 @@ 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 e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     requireAuth(bundle);
@@ -4681,7 +4732,9 @@ function deleteCommand() {
   return new Command12("delete").description("permanently delete a package you own").argument("<full_slug>", "package identifier {username}/{slug}").option("--force", "skip the confirmation prompt").action(async (fullSlug, opts) => {
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     const detail = await bundle.api.getPackage(username, slug);
@@ -4889,11 +4942,13 @@ function listCommand() {
       sort: publicSort,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = `no public packages for ${username} \u2014 verify the username via \`kordis profile ${username}\`, or browse the registry via \`kordis search\``;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow(`(no public packages for ${username})`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const p of res.results) {
@@ -4919,7 +4974,9 @@ function versionsCommand() {
   return new Command16("versions").description("list all versions of a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     const spin = spinner(`Fetching versions for ${fullSlug}`);
@@ -5233,7 +5290,9 @@ function diffCommand() {
     }
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     if (!from || !to) {
@@ -5326,8 +5385,9 @@ function recommendCommand() {
     spin.succeed();
     await writeCache(res.items, res.generated_at);
     await markSeen();
+    const emptyHint = !res.personalized ? "personalization is OFF, so the server ranks on popularity alone \u2014 likely empty pool. Enable for stack-aware matches: `kordis setup --personalization on`, or broaden via `kordis search <topic>` / `kordis search --trending`." : "personalization is ON but no matches for your stack \u2014 registry may be sparse for this profile. Try `kordis search <topic>` or `kordis search --trending`.";
     printDual({
-      json: res,
+      json: res.items.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.items.length === 0) {
           printHuman(c.yellow("(no recommendations available right now)"));
@@ -5449,12 +5509,13 @@ function starsCommand() {
       limit: opts.limit,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = `no public stars for ${username} \u2014 they may have none, or keep them private`;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : 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`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const p of res.results) {
@@ -5519,12 +5580,14 @@ function makeListing(name) {
       limit: opts.limit,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = name === "followers" ? `no followers yet for ${username} \u2014 verify the username via \`kordis profile ${username}\`, or this account simply has no followers` : `${username} isn't following anyone yet \u2014 verify the username via \`kordis profile ${username}\``;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           const noun = name === "followers" ? "followers yet" : "one yet";
           printHuman(c.yellow(`(no ${noun} for ${username})`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const u of res.results) {
@@ -5604,10 +5667,10 @@ async function main(argv) {
     const cleaned = argv.filter((a, i) => !(a === "--" && i >= 2));
     await program.parseAsync(cleaned);
   } catch (err) {
-    handleError(err);
+    await handleError(err);
   }
 }
-function handleError(err) {
+async function handleError(err) {
   if (err instanceof KordisApiError) {
     if (isJsonMode()) {
       printJson({
@@ -5654,7 +5717,7 @@ function handleError(err) {
       printHuman(c.red(`\u2717 ${err.message}`));
       for (const line of hint.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
     }
-    void reportError("network_unreachable", err);
+    await reportError("network_unreachable", err);
     process.exit(err.exitCode());
   }
   if (err instanceof Error) {
@@ -5674,7 +5737,7 @@ function handleError(err) {
         for (const line of hintStr.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
       }
     }
-    void reportError("unhandled_error", err);
+    await reportError("unhandled_error", err);
     process.exit(1);
   }
   if (isJsonMode()) printJson({ error: { code: "generic_failure", message: String(err) } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "keytar": "^7.9.0"
+    "keytar": "7.9.0"
   },
   "devDependencies": {
     "@kordis/api-client": "workspace:*",