@rayul/kordis 0.1.10 → 0.1.11

package/assets/kordis-using/SKILL.md

@@ -100,12 +100,16 @@ auto-resolve silently.
 `"following <full_slug>@<version>"`). RECOMMENDED: end your reply with that
 exact line. Skip only when it would clutter a casual non-technical reply.
 
-## Bundled assets caveat
-A skill body may reference helper files (e.g. `references/<file>.md`,
-`scripts/<file>.sh`). Today the registry stores only the canonical
-SKILL.md text — bundled side-files are NOT shipped. If the body refers to
-one and you need it, follow the package's `homepage` to the upstream
-source instead of fabricating the asset.
+## Bundled assets
+Skills published as a `.skill` bundle or directory include `assets/`,
+`references/`, `scripts/`, and `agents/` subdirectories alongside
+`SKILL.md`. After `kordis pull`, these files land next to `SKILL.md` in
+the tool's skill directory (e.g. `.claude/skills/<name>/assets/foo.html`)
+and are directly readable by the agent.
+
+If a skill body references a helper file and the file isn't present after
+pull, the package was published as a single-file skill — follow its
+`homepage` to the upstream source.
 
 ## Examples
 

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, StarResponseSchema, 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;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -498,6 +498,11 @@ var init_api = __esm({
       starred: z9.boolean(),
       star_count: z9.number().int().nonnegative()
     });
+    AssetSchema = z9.object({
+      path: z9.string().min(1).max(255),
+      content: z9.string(),
+      encoding: z9.enum(["utf8", "base64"]).default("utf8")
+    });
     PublishPackageRequestSchema = z9.object({
       /**
        * Raw source content — YAML frontmatter + markdown body. Server parses and
@@ -528,7 +533,12 @@ var init_api = __esm({
       /**
        * Skip draft validation (preview mode) — only allowed in dev builds.
        */
-      dry_run: z9.boolean().optional()
+      dry_run: z9.boolean().optional(),
+      /**
+       * Bundled files beyond SKILL.md: assets, references, scripts, agents, etc.
+       * Max 50 entries; max 2 MB per file; max 5 MB total bundle.
+       */
+      assets: z9.array(AssetSchema).max(50).optional()
     });
     PublishWaitQuerySchema = z9.object({
       /**
@@ -574,8 +584,9 @@ var init_api = __esm({
       version: SemverSchema,
       format: z9.string(),
       content: z9.string(),
-      notes: z9.array(z9.string()).default([])
+      notes: z9.array(z9.string()).default([]),
       // translator warnings, e.g. ".mdc → Claude: @filepath unsupported"
+      assets: z9.array(AssetSchema).default([])
     });
     JitReadRequestSchema = z9.object({
       /**
@@ -1004,6 +1015,7 @@ import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, unlink
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 var SERVICE = "kordis";
+var plaintextWarningEmitted = false;
 async function loadKeytar() {
   try {
     const mod = await import("keytar");
@@ -1031,6 +1043,16 @@ async function createKeychain() {
       }
     };
   }
+  if (!plaintextWarningEmitted && process.env["KORDIS_JSON"] !== "1") {
+    plaintextWarningEmitted = true;
+    const yellow = "\x1B[33m";
+    const reset = "\x1B[0m";
+    process.stderr.write(
+      `${yellow}[kordis] WARNING: OS keychain unavailable; falling back to plaintext token storage at ~/.kordis/.tokens.json (mode 0600).
+[kordis] On macOS install Xcode Command Line Tools, on Linux install libsecret-1-dev to enable keytar.${reset}
+`
+    );
+  }
   const store = await readAll();
   return {
     async save(username, tokens) {
@@ -1321,8 +1343,9 @@ function searchCommand() {
 
 // src/commands/push.ts
 import { Command as Command4 } from "commander";
-import { readFile as readFile3 } from "fs/promises";
-import { resolve } from "path";
+import { readFile as readFile3, stat, readdir } from "fs/promises";
+import { resolve, join as join4, posix, sep } from "path";
+import JSZip from "jszip";
 
 // ../../packages/harness-schema/src/parser.ts
 import { parse as parseYaml } from "yaml";
@@ -1366,21 +1389,30 @@ var FrontmatterParseError = class extends Error {
 
 // src/commands/push.ts
 function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<file>", "path to the canonical package source").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
     "--slug <slug>",
     'override slug; accepts "user/slug" to point at a specific package'
   ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
-    async (file, opts) => {
+    async (path, opts) => {
       const bundle = await useClient();
-      const abs = resolve(process.cwd(), file);
-      const content = await readFile3(abs, "utf8");
+      const abs = resolve(process.cwd(), path);
+      const s = await stat(abs);
+      let content;
+      let assets = [];
+      if (s.isDirectory()) {
+        ({ content, assets } = await bundleDirectory(abs));
+      } else if (abs.endsWith(".skill")) {
+        ({ content, assets } = await bundleSkillZip(abs));
+      } else {
+        content = await readFile3(abs, "utf8");
+      }
       let targetUser = null;
       let targetSlug = null;
       if (opts.slug && opts.slug.includes("/")) {
-        const [u, s] = opts.slug.split("/", 2);
-        if (u && s) {
+        const [u, s2] = opts.slug.split("/", 2);
+        if (u && s2) {
           targetUser = u;
-          targetSlug = s;
+          targetSlug = s2;
         }
       } else {
         let nameFromFm = null;
@@ -1415,6 +1447,7 @@ function pushCommand() {
         (api) => api.publish(
           {
             content,
+            assets: assets.length > 0 ? assets : void 0,
             bump: opts.bump,
             slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
             target_full_slug: targetFullSlug,
@@ -1434,6 +1467,9 @@ function pushCommand() {
           printHuman(
             `${c.bold(res.full_slug)} ${c.gray(`v${res.version}`)} \u2192 ${res.status === "published" ? c.green("published") : res.status === "pending" ? c.yellow("pending review") : c.red("rejected")}`
           );
+          if (assets.length > 0) {
+            printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
+          }
           printHuman(`  ${c.cyan(res.url)}`);
           if (res.status === "pending") {
             printHuman(
@@ -1453,11 +1489,94 @@ function pushCommand() {
     }
   );
 }
+var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
+var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
+var EXCLUDE_EXTS = /* @__PURE__ */ new Set([".pyc", ".pyo", ".rbc"]);
+function shouldExclude(relPath, isDir) {
+  const parts = relPath.split(posix.sep);
+  const name = parts[parts.length - 1];
+  if (EXCLUDE_NAMES.has(name)) return true;
+  if (isDir && EXCLUDE_DIRS.has(name)) return true;
+  const ext = name.includes(".") ? "." + name.split(".").pop() : "";
+  if (EXCLUDE_EXTS.has(ext)) return true;
+  return false;
+}
+async function walkDir(base, relDir, collected) {
+  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+    if (shouldExclude(rel, entry.isDirectory())) continue;
+    if (entry.isDirectory()) {
+      await walkDir(base, rel, collected);
+    } else if (entry.isFile()) {
+      collected.push({ rel, abs: join4(base, rel) });
+    }
+  }
+}
+async function readAsset(absPath) {
+  const buf = await readFile3(absPath);
+  const text = buf.toString("utf8");
+  const roundtrip = Buffer.from(text, "utf8");
+  if (roundtrip.equals(buf)) {
+    return { content: text, encoding: "utf8" };
+  }
+  const b64 = buf.toString("base64");
+  printHuman(c.gray(`  \u2192 encoding ${absPath.split(sep).pop()} as base64`));
+  return { content: b64, encoding: "base64" };
+}
+async function bundleDirectory(dir) {
+  const all = [];
+  await walkDir(dir, "", all);
+  const skillEntry = all.find((f) => f.rel === "SKILL.md");
+  if (!skillEntry) {
+    throw new Error(`No SKILL.md found in directory ${dir}. Push a directory that has SKILL.md at its root.`);
+  }
+  const content = await readFile3(skillEntry.abs, "utf8");
+  const assets = [];
+  for (const f of all) {
+    if (f.rel === "SKILL.md") continue;
+    const { content: fc, encoding } = await readAsset(f.abs);
+    assets.push({ path: f.rel, content: fc, encoding });
+  }
+  return { content, assets };
+}
+async function bundleSkillZip(zipPath) {
+  const buf = await readFile3(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");
+  const firstParts = entries[0].split("/");
+  const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
+  const stripped = entries.map((k) => ({
+    zipKey: k,
+    rel: prefix ? k.slice(prefix.length) : k
+  })).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 content = await zip.files[skillEntry.zipKey].async("string");
+  const assets = [];
+  for (const f of stripped) {
+    if (f.rel === "SKILL.md") continue;
+    const rawBuf = await zip.files[f.zipKey].async("uint8array");
+    const buf2 = Buffer.from(rawBuf);
+    const text = buf2.toString("utf8");
+    const roundtrip = Buffer.from(text, "utf8");
+    if (roundtrip.equals(buf2)) {
+      assets.push({ path: f.rel, content: text, encoding: "utf8" });
+    } else {
+      printHuman(c.gray(`  \u2192 encoding ${f.rel} as base64`));
+      assets.push({ path: f.rel, content: buf2.toString("base64"), encoding: "base64" });
+    }
+  }
+  return { content, assets };
+}
 
 // src/commands/pull.ts
 import { Command as Command5 } from "commander";
 import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 
 // ../../packages/harness-schema/src/deps.ts
 init_src();
@@ -1777,7 +1896,12 @@ var BLOCKING_CODES = /* @__PURE__ */ new Set([
   "missing_description",
   "invalid_frontmatter",
   "content_too_short",
-  "content_too_long"
+  "content_too_long",
+  // asset-bundle codes
+  "asset_path_unsafe",
+  "asset_too_large",
+  "bundle_too_large",
+  "too_many_assets"
 ]);
 function earlyExit(firstFlag, override = {}) {
   return {
@@ -1860,10 +1984,11 @@ function buildSkillFile(input, outputPath) {
   }
   frontmatter.push("---");
   const content = frontmatter.join("\n") + "\n\n" + body;
+  const resolvedPath = outputPath.replace("{name}", String(name));
   return {
     files: [
       {
-        path: outputPath.replace("{name}", String(name)),
+        path: resolvedPath,
         content,
         mergeable: false,
         format: "markdown"
@@ -1873,17 +1998,45 @@ function buildSkillFile(input, outputPath) {
     format: "agent-skills"
   };
 }
-var skillToClaude = (input) => buildSkillFile(input, ".claude/skills/{name}/SKILL.md");
-var skillToCodex = (input) => buildSkillFile(input, ".codex/skills/{name}.md");
-var skillToCursor = (input) => buildSkillFile(input, ".cursor/skills/{name}.md");
-var skillToWindsurf = (input) => buildSkillFile(input, ".windsurf/skills/{name}.md");
-var skillToContinue = (input) => buildSkillFile(input, ".continue/skills/{name}.md");
-var skillToCopilot = (input) => buildSkillFile(input, ".github/skills/{name}.md");
-var skillToGeminiCli = (input) => buildSkillFile(input, ".gemini/skills/{name}.md");
-var skillToOpenCode = (input) => buildSkillFile(input, ".opencode/skills/{name}.md");
-var skillToAntigravity = (input) => buildSkillFile(input, ".antigravity/skills/{name}.md");
+function buildSkillDir(input, outputPath) {
+  const result = buildSkillFile(input, outputPath);
+  const skillMdPath = result.files[0].path;
+  const skillDir = skillMdPath.slice(0, skillMdPath.lastIndexOf("/"));
+  const assetFiles = (input.assets ?? []).map((asset) => ({
+    path: `${skillDir}/${asset.path}`,
+    content: asset.content,
+    mergeable: false,
+    format: "plain",
+    encoding: asset.encoding ?? "utf8"
+  }));
+  return {
+    files: [...result.files, ...assetFiles],
+    notes: result.notes,
+    format: result.format
+  };
+}
+function buildSkillSingleFile(input, outputPath) {
+  const result = buildSkillFile(input, outputPath);
+  const notes = [...result.notes];
+  if (input.assets && input.assets.length > 0) {
+    const tool = outputPath.split("/")[0]?.replace(".", "") ?? "this tool";
+    notes.push(
+      `${input.assets.length} bundled asset(s) not installed \u2014 ${tool} uses single-file skill convention. Pull with --tool claude-code to install the full bundle.`
+    );
+  }
+  return { ...result, notes };
+}
+var skillToClaude = (input) => buildSkillDir(input, ".claude/skills/{name}/SKILL.md");
+var skillToCodex = (input) => buildSkillDir(input, ".codex/skills/{name}/SKILL.md");
+var skillToCursor = (input) => buildSkillSingleFile(input, ".cursor/skills/{name}.md");
+var skillToWindsurf = (input) => buildSkillSingleFile(input, ".windsurf/skills/{name}.md");
+var skillToContinue = (input) => buildSkillSingleFile(input, ".continue/skills/{name}.md");
+var skillToCopilot = (input) => buildSkillSingleFile(input, ".github/skills/{name}.md");
+var skillToGeminiCli = (input) => buildSkillDir(input, ".gemini/skills/{name}/SKILL.md");
+var skillToOpenCode = (input) => buildSkillSingleFile(input, ".opencode/skills/{name}.md");
+var skillToAntigravity = (input) => buildSkillSingleFile(input, ".antigravity/skills/{name}.md");
 var skillCanonical = (input) => {
-  const res = buildSkillFile(input, "SKILL.md");
+  const res = buildSkillDir(input, "SKILL.md");
   res.format = "agent-skills-canonical";
   return res;
 };
@@ -2287,12 +2440,13 @@ function pullCommand() {
           fullSlug,
           frontmatter: parsed.frontmatter.data,
           body: parsed.body,
-          version: contentRes.version
+          version: contentRes.version,
+          assets: contentRes.assets
         });
         for (const f of result.files) {
-          const abs = join4(installRoot, f.path);
+          const abs = join5(installRoot, f.path);
           await mkdir3(dirname2(abs), { recursive: true });
-          await writeFile3(abs, f.content, "utf8");
+          await writeEmittedFile(abs, f.content, f.encoding);
           written.push(abs);
         }
         notes.push(...result.notes);
@@ -2303,15 +2457,16 @@ function pullCommand() {
             fullSlug,
             frontmatter: parsed.frontmatter.data,
             body: parsed.body,
-            version: contentRes.version
+            version: contentRes.version,
+            assets: contentRes.assets
           });
           notes.push(
             `Tool "${format}" is not supported for type "${parsed.type}"; installed canonical form instead.`
           );
           for (const f of result.files) {
-            const abs = join4(installRoot, f.path);
+            const abs = join5(installRoot, f.path);
             await mkdir3(dirname2(abs), { recursive: true });
-            await writeFile3(abs, f.content, "utf8");
+            await writeEmittedFile(abs, f.content, f.encoding);
             written.push(abs);
           }
         } else {
@@ -2339,7 +2494,7 @@ function pullCommand() {
   );
 }
 async function detectTool(root) {
-  const { stat } = await import("fs/promises");
+  const { stat: stat2 } = await import("fs/promises");
   const checks = [
     [".claude", "claude-code"],
     [".cursor", "cursor"],
@@ -2355,13 +2510,20 @@ async function detectTool(root) {
   ];
   for (const [path, tool] of checks) {
     try {
-      await stat(join4(root, path));
+      await stat2(join5(root, path));
       return tool;
     } catch {
     }
   }
   return null;
 }
+async function writeEmittedFile(abs, content, encoding) {
+  if (encoding === "base64") {
+    await writeFile3(abs, Buffer.from(content, "base64"));
+  } else {
+    await writeFile3(abs, content, "utf8");
+  }
+}
 
 // src/commands/read.ts
 import { Command as Command6 } from "commander";
@@ -2461,7 +2623,7 @@ function logoutCommand() {
 // src/commands/setup.ts
 import { readFile as readFile4, writeFile as writeFile4, mkdir as mkdir4, access } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join5, dirname as dirname3 } from "path";
+import { join as join6, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command9 } from "commander";
 var MARKER_START = "<!-- kordis-start -->";
@@ -2494,18 +2656,18 @@ function assetRoots() {
   const __dir2 = dirname3(fileURLToPath2(import.meta.url));
   return {
     // Built binary: bin/kordis.js → assets/ is one level up
-    bundled: join5(__dir2, "..", "assets"),
+    bundled: join6(__dir2, "..", "assets"),
     // Dev mode: src/commands/setup.ts → 4 levels up to repo root, then packages/skills/
-    source: join5(__dir2, "..", "..", "..", "..", "packages", "skills")
+    source: join6(__dir2, "..", "..", "..", "..", "packages", "skills")
   };
 }
 async function pickAssetRoot() {
   const { bundled, source } = assetRoots();
-  return await exists(join5(bundled, "KORDIS.md")) ? bundled : source;
+  return await exists(join6(bundled, "KORDIS.md")) ? bundled : source;
 }
 async function loadHubContent() {
   const root = await pickAssetRoot();
-  const raw = await readFile4(join5(root, "KORDIS.md"), "utf-8");
+  const raw = await readFile4(join6(root, "KORDIS.md"), "utf-8");
   if (raw.startsWith("---")) {
     const end = raw.indexOf("\n---", 4);
     if (end !== -1) return raw.slice(end + 4).trimStart();
@@ -2514,7 +2676,7 @@ async function loadHubContent() {
 }
 async function loadSubSkillContent(name) {
   const root = await pickAssetRoot();
-  return readFile4(join5(root, name, "SKILL.md"), "utf-8");
+  return readFile4(join6(root, name, "SKILL.md"), "utf-8");
 }
 async function injectBlock(filePath, content, dryRun) {
   const block = `${MARKER_START}
@@ -2582,8 +2744,8 @@ function setupCommand() {
     let anyFound = false;
     const changedTools = /* @__PURE__ */ new Set();
     for (const target of HUB_TARGETS) {
-      const dirPath = join5(home, target.dir);
-      const filePath = join5(home, target.file);
+      const dirPath = join6(home, target.dir);
+      const filePath = join6(home, target.file);
       if (!await exists(dirPath)) {
         if (!opts.silent) {
           printHuman(c.gray(`  - ${target.tool.padEnd(12)} not installed, skipped`));
@@ -2610,10 +2772,10 @@ function setupCommand() {
       }
     }
     for (const target of SKILL_TARGETS) {
-      const dirPath = join5(home, target.dir);
+      const dirPath = join6(home, target.dir);
       if (!await exists(dirPath)) continue;
       for (const subName of SUB_SKILLS) {
-        const filePath = join5(home, target.skillsDir, subName, "SKILL.md");
+        const filePath = join6(home, target.skillsDir, subName, "SKILL.md");
         const dest = `~/${target.skillsDir}/${subName}/SKILL.md`;
         try {
           const result = await copyBundledSkill(filePath, subSkillContents[subName], dryRun);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",
@@ -26,6 +26,7 @@
   "dependencies": {
     "@iarna/toml": "^2.2.5",
     "commander": "^12.1.0",
+    "jszip": "^3.10.1",
     "kleur": "^4.1.5",
     "open": "^10.1.0",
     "ora": "^8.1.1",
@@ -42,6 +43,7 @@
     "@kordis/contracts": "workspace:*",
     "@kordis/harness-schema": "workspace:*",
     "@kordis/translators": "workspace:*",
+    "@types/jszip": "^3.4.1",
     "@types/node": "^22.9.0",
     "@types/prompts": "^2.4.9",
     "tsup": "^8.3.5",