@rayul/kordis 0.1.16 → 0.2.0

package/dist/index.js

@@ -45,7 +45,7 @@ var init_primitives = __esm({
 
 // ../../packages/contracts/src/enums.ts
 import { z as z2 } from "zod";
-var HarnessTypeSchema, PHASE_1_TYPES, TierSchema, TIER_OF_TYPE, SortModeSchema, TimeWindowSchema, VisibilitySchema, ReviewStatusSchema, PublishStatusSchema, DependencyKindSchema, OAuthProviderSchema, UserRoleSchema, ReportReasonSchema;
+var HarnessTypeSchema, PHASE_1_TYPES, TierSchema, TIER_OF_TYPE, CAPABILITIES_OF_TYPE, SortModeSchema, TimeWindowSchema, VisibilitySchema, ReviewStatusSchema, PublishStatusSchema, DependencyKindSchema, OAuthProviderSchema, UserRoleSchema, ReportReasonSchema;
 var init_enums = __esm({
   "../../packages/contracts/src/enums.ts"() {
     "use strict";
@@ -77,6 +77,16 @@ var init_enums = __esm({
       "mdc-rule": "C",
       plugin: "D"
     };
+    CAPABILITIES_OF_TYPE = {
+      skill: { jit_eligible: true, executable: false },
+      "project-rules": { jit_eligible: true, executable: false },
+      "custom-agent": { jit_eligible: true, executable: false },
+      "scoped-rule": { jit_eligible: true, executable: false },
+      "mdc-rule": { jit_eligible: true, executable: false },
+      "mcp-server": { jit_eligible: false, executable: true },
+      hook: { jit_eligible: false, executable: true },
+      plugin: { jit_eligible: false, executable: true }
+    };
     SortModeSchema = z2.enum([
       "stars",
       "downloads",
@@ -281,6 +291,14 @@ var init_package = __esm({
       tools_compatible: z6.array(ToolSlugSchema),
       tags: z6.array(TagSchema),
       agent_skills_compliant: z6.boolean().optional(),
+      /**
+       * Capability flags — explicit declaration of behavior. Defaults derive from
+       * `type` via `CAPABILITIES_OF_TYPE`; frontmatter MAY override. Optional in
+       * the schema so old API responses (pre-0.2.0) parse cleanly; consumers that
+       * need a value should fall back to `CAPABILITIES_OF_TYPE[type]`.
+       */
+      jit_eligible: z6.boolean().optional(),
+      executable: z6.boolean().optional(),
       review_status: ReviewStatusSchema,
       visibility: VisibilitySchema,
       installed_locally: z6.boolean().optional(),
@@ -1374,18 +1392,21 @@ function parseFrontmatter(source) {
     parsed = parseYaml(raw);
   } catch (err) {
     const msg = err.message;
-    const hint = msg.includes("Nested mapping") || msg.includes("compact mapping") ? ' Hint: if a field value (e.g. description) contains a colon, wrap the entire value in quotes: description: "Use when... Trigger: X".' : "";
-    throw new FrontmatterParseError(
-      `YAML frontmatter is malformed: ${msg}${hint}`,
-      { cause: err }
-    );
+    const hint = msg.includes("Nested mapping") || msg.includes("compact mapping") ? 'If the value contains ":" wrap it in quotes, e.g.  description: "Use when X. Trigger: Y"' : 'Frontmatter must be valid YAML between two "---" fences. Validate at https://yamllint.com';
+    throw new FrontmatterParseError(`YAML frontmatter is malformed: ${msg}`, {
+      cause: err,
+      hint
+    });
   }
   if (parsed === null || parsed === void 0) {
     return { frontmatter: {}, body: stripped.slice(match[0].length), bodyOffset: match[0].length };
   }
   if (typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new FrontmatterParseError(
-      "YAML frontmatter must decode to an object, got " + typeof parsed
+      "YAML frontmatter must decode to an object, got " + typeof parsed,
+      {
+        hint: "Frontmatter must be a YAML mapping (key: value pairs), not a list or scalar."
+      }
     );
   }
   return {
@@ -1395,9 +1416,12 @@ function parseFrontmatter(source) {
   };
 }
 var FrontmatterParseError = class extends Error {
+  /** Agent-actionable fix snippet, ready to render under the error. */
+  hint;
   constructor(message, options) {
     super(message, options);
     this.name = "FrontmatterParseError";
+    if (options?.hint) this.hint = options.hint;
   }
 };
 
@@ -1428,7 +1452,7 @@ function pushCommand() {
         const v = fm["name"];
         if (typeof v === "string") nameFromFm = v;
       } catch (err) {
-        throw new Error(err.message);
+        throw err instanceof Error ? err : new Error(String(err));
       }
       let targetUser = null;
       let targetSlug = null;
@@ -1820,37 +1844,43 @@ function validatePackageSource(source) {
     rawFrontmatter = parsed.frontmatter;
   } catch (err) {
     if (err instanceof FrontmatterParseError) {
-      return earlyExit(flag("malformed_frontmatter", err.message));
+      const extra = err.hint ? { hint: err.hint } : {};
+      return earlyExit(flag("malformed_frontmatter", err.message, extra));
     }
     throw err;
   }
   if (!rawFrontmatter) {
-    return earlyExit(flag("missing_frontmatter", "package must start with a YAML frontmatter block"));
+    return earlyExit(
+      flag("missing_frontmatter", "package must start with a YAML frontmatter block", {
+        hint: "Add a YAML block at the top:\n---\ntype: skill\nname: my-skill\ndescription: ...\n---"
+      })
+    );
   }
   const typeValue = rawFrontmatter["type"];
   if (typeof typeValue !== "string") {
     return earlyExit(
-      flag("missing_required_frontmatter", "`type` is required in frontmatter", { field: "type" })
+      flag("missing_required_frontmatter", "`type` is required in frontmatter", {
+        field: "type",
+        hint: "Add  type: skill  (or one of: mcp-server, project-rules, custom-agent, hook)"
+      })
     );
   }
   const typeParse = HarnessTypeSchema.safeParse(typeValue);
   if (!typeParse.success) {
     return earlyExit(
-      flag(
-        "unknown_type",
-        `type "${typeValue}" is not a recognised Harness type`,
-        { field: "type" }
-      )
+      flag("unknown_type", `type "${typeValue}" is not a recognised Harness type`, {
+        field: "type",
+        hint: "Allowed types: skill, mcp-server, project-rules, custom-agent, hook"
+      })
     );
   }
   const type = typeParse.data;
   if (!PHASE_1_TYPES.includes(type)) {
     flags.push(
-      flag(
-        "type_not_phase1",
-        `type "${type}" is planned for Phase 2+ and is not yet accepted`,
-        { field: "type" }
-      )
+      flag("type_not_phase1", `type "${type}" is planned for Phase 2+ and is not yet accepted`, {
+        field: "type",
+        hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook"
+      })
     );
     return earlyExit(null, { flags, body });
   }
@@ -1858,22 +1888,69 @@ function validatePackageSource(source) {
     type: _discard_type,
     depends: _discard_depends,
     recommends: _discard_recommends,
+    jit_eligible: rawJitEligible,
+    executable: rawExecutable,
     ...typeSpecific
   } = rawFrontmatter;
   void _discard_type;
   void _discard_depends;
   void _discard_recommends;
+  let jitOverride;
+  let execOverride;
+  if (rawJitEligible !== void 0) {
+    if (typeof rawJitEligible !== "boolean") {
+      flags.push(
+        flag(
+          "invalid_frontmatter",
+          "jit_eligible must be a boolean (true / false)",
+          {
+            field: "jit_eligible",
+            hint: "Example: jit_eligible: true"
+          }
+        )
+      );
+    } else {
+      jitOverride = rawJitEligible;
+    }
+  }
+  if (rawExecutable !== void 0) {
+    if (typeof rawExecutable !== "boolean") {
+      flags.push(
+        flag("invalid_frontmatter", "executable must be a boolean (true / false)", {
+          field: "executable",
+          hint: "Example: executable: false"
+        })
+      );
+    } else {
+      execOverride = rawExecutable;
+    }
+  }
   const result = dispatchValidation(type, typeSpecific);
   if (!result.ok) {
     flags.push(...result.flags);
     return earlyExit(null, { flags, body });
   }
+  const defaults = CAPABILITIES_OF_TYPE[type];
+  const capabilities = {
+    jit_eligible: jitOverride ?? defaults.jit_eligible,
+    executable: execOverride ?? defaults.executable
+  };
   const common = {
     title: typeof rawFrontmatter["title"] === "string" ? rawFrontmatter["title"] : typeof rawFrontmatter["name"] === "string" ? rawFrontmatter["name"] : null,
     description: typeof rawFrontmatter["description"] === "string" ? rawFrontmatter["description"] : null
   };
-  if (!common.title) flags.push(flag("missing_title", "title (or name) is required"));
-  if (!common.description) flags.push(flag("missing_description", "description is required"));
+  if (!common.title)
+    flags.push(
+      flag("missing_title", "title (or name) is required", {
+        hint: 'Add  title: "Human Readable Title"  (or rely on  name: ...  for skills)'
+      })
+    );
+  if (!common.description)
+    flags.push(
+      flag("missing_description", "description is required", {
+        hint: "Add a description field (1\u20132048 chars) explaining when to invoke this package."
+      })
+    );
   let depends = [];
   let recommends = [];
   try {
@@ -1883,7 +1960,12 @@ function validatePackageSource(source) {
       kind: DependencyKindSchema.parse("required")
     }));
   } catch (err) {
-    flags.push(flag("invalid_depends", err.message, { field: "depends" }));
+    flags.push(
+      flag("invalid_depends", err.message, {
+        field: "depends",
+        hint: 'Each entry must be "{username}/{slug}" optionally with "@^1.2.0". Example: alice/json-pretty@^1.0.0'
+      })
+    );
   }
   try {
     recommends = normaliseDepList(rawFrontmatter["recommends"]).map((d) => ({
@@ -1892,13 +1974,26 @@ function validatePackageSource(source) {
       kind: DependencyKindSchema.parse("recommended")
     }));
   } catch (err) {
-    flags.push(flag("invalid_recommends", err.message, { field: "recommends" }));
+    flags.push(
+      flag("invalid_recommends", err.message, {
+        field: "recommends",
+        hint: 'Each entry must be "{username}/{slug}" optionally with "@^1.2.0".'
+      })
+    );
   }
   if (body.trim().length < 50) {
-    flags.push(flag("content_too_short", "body must be at least 50 non-whitespace characters"));
+    flags.push(
+      flag("content_too_short", "body must be at least 50 non-whitespace characters", {
+        hint: 'Add an "## Instructions" section explaining when and how to use this package.'
+      })
+    );
   }
   if (body.length > 1e5) {
-    flags.push(flag("content_too_long", "body exceeds 100 kB cap"));
+    flags.push(
+      flag("content_too_long", "body exceeds 100 kB cap", {
+        hint: "Split long examples or transcripts into asset files under references/."
+      })
+    );
   }
   const ok = flags.every((f) => !BLOCKING_CODES.has(f.code));
   return {
@@ -1908,6 +2003,7 @@ function validatePackageSource(source) {
     frontmatter: result.frontmatter,
     body,
     common,
+    capabilities,
     depends,
     recommends,
     flags
@@ -1938,6 +2034,7 @@ function earlyExit(firstFlag, override = {}) {
     frontmatter: null,
     body: "",
     common: { title: null, description: null },
+    capabilities: null,
     depends: [],
     recommends: [],
     flags: firstFlag ? [firstFlag] : [],
@@ -1976,7 +2073,10 @@ function dispatchValidation(type, raw) {
         ok: false,
         frontmatter: null,
         flags: [
-          flag("type_not_phase1", `type "${type}" not accepted in Phase 1`, { field: "type" })
+          flag("type_not_phase1", `type "${type}" not accepted in Phase 1`, {
+            field: "type",
+            hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook"
+          })
         ]
       };
   }
@@ -1985,9 +2085,22 @@ function zodFail(issues) {
   return {
     ok: false,
     frontmatter: null,
-    flags: issues.map(
-      (i) => flag("invalid_frontmatter", i.message, { field: i.path.join(".") || void 0 })
-    )
+    flags: issues.map((i) => {
+      const field = i.path.join(".") || void 0;
+      const msg = i.message.toLowerCase();
+      let hint;
+      if (field === "name" && msg.includes("lowercase")) {
+        hint = 'name must be lowercase-with-hyphens, e.g. "my-cool-skill" not "MyCoolSkill"';
+      } else if (field === "description" && (msg.includes("big") || msg.includes("large") || msg.includes("long"))) {
+        hint = "description must be 1\u20132048 chars; current is too long. Move detail into the body.";
+      } else if (field === "description" && msg.includes("small")) {
+        hint = "description must be 1\u20132048 chars; provide a one-paragraph summary.";
+      }
+      const extra = {};
+      if (field) extra.field = field;
+      if (hint) extra.hint = hint;
+      return flag("invalid_frontmatter", i.message, extra);
+    })
   };
 }
 
@@ -2628,6 +2741,7 @@ function readCommand() {
 }
 
 // src/commands/info.ts
+init_src();
 import { Command as Command7 } from "commander";
 function infoCommand() {
   return new Command7("info").description("show details about a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
@@ -2635,6 +2749,9 @@ function infoCommand() {
     if (!username || !slug) throw new Error('full_slug must be "{username}/{slug}"');
     const bundle = await useClient();
     const detail = await bundle.api.getPackage(username, slug);
+    const typeDefaults = CAPABILITIES_OF_TYPE[detail.type];
+    const jitEligible = detail.jit_eligible ?? typeDefaults.jit_eligible;
+    const executable = detail.executable ?? typeDefaults.executable;
     printDual({
       json: detail,
       human: () => {
@@ -2642,6 +2759,12 @@ function infoCommand() {
         printHuman("  " + detail.description);
         printHuman("");
         printHuman(`  ${c.cyan("Type")}: ${detail.type} (tier ${detail.tier})`);
+        printHuman(
+          `  ${c.cyan("JIT-readable")}: ${jitEligible ? c.green("yes") : c.red("no")}`
+        );
+        printHuman(
+          `  ${c.cyan("Executable")}: ${executable ? c.yellow("yes") : c.gray("no")}`
+        );
         printHuman(`  ${c.cyan("Author")}: ${detail.author.username}`);
         printHuman(`  ${c.cyan("Stats")}: \u2605 ${detail.stars} \xB7 \u21E3 ${detail.downloads}`);
         if (detail.tools_compatible.length > 0) {
@@ -3329,7 +3452,7 @@ function diffCommand() {
     let fullSlug = fullSlugArg;
     let from = fromArg;
     let to = toArg;
-    const rangeMatch = /^(.+)@([^.]+)\.\.(.+)$/.exec(fullSlugArg);
+    const rangeMatch = /^(.+)@(.+?)\.\.(.+)$/.exec(fullSlugArg);
     if (rangeMatch) {
       fullSlug = rangeMatch[1];
       from = rangeMatch[2];
@@ -3441,6 +3564,11 @@ function handleError(err) {
       printHuman(c.red(`\u2717 ${err.code}: ${err.message}`));
       for (const f of err.flags) {
         printHuman(c.red(`  - ${f.code}${f.message ? `: ${f.message}` : ""}`));
+        if (f.hint) {
+          for (const line of f.hint.split("\n")) {
+            printHuman(c.gray(`      \u2192 ${line}`));
+          }
+        }
       }
       if (err.retryAfter !== void 0) {
         printHuman(c.yellow(`  retry after: ${err.retryAfter}s`));
@@ -3457,8 +3585,22 @@ function handleError(err) {
     process.exit(err.exitCode());
   }
   if (err instanceof Error) {
-    if (isJsonMode()) printJson({ error: { code: "generic_failure", message: err.message } });
-    else printHuman(c.red(`\u2717 ${err.message}`));
+    const hint = err.hint;
+    const hintStr = typeof hint === "string" ? hint : void 0;
+    if (isJsonMode()) {
+      printJson({
+        error: {
+          code: "generic_failure",
+          message: err.message,
+          ...hintStr ? { hint: hintStr } : {}
+        }
+      });
+    } else {
+      printHuman(c.red(`\u2717 ${err.message}`));
+      if (hintStr) {
+        for (const line of hintStr.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
+      }
+    }
     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.1.16",
+  "version": "0.2.0",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",