@rayul/kordis 0.2.2 → 0.3.1

package/assets/kordis-publishing/SKILL.md

@@ -31,15 +31,22 @@ Publish a valid, AI-review-passing version. ALWAYS dry-run first.
 
 ## Deleting a package
 
-There is **no `kordis delete` CLI command**. Options:
-- Web UI: `https://kordis.store/p/<full_slug>` (if a delete button is available)
-- Registry owner: soft-delete via the prod Postgres
-  (`UPDATE packages SET deleted_at = NOW() WHERE full_slug = '...'`)
-- Workaround: push a new version with `visibility: unlisted` or a
-  deprecation notice in the body
+### `kordis delete <full_slug> [--force]`
 
-If the body contains third-party content, MUST preserve the original copyright
-and license text inside the body and link to source via `homepage`.
+Soft-deletes a package you own. Removes from search / info / read /
+pull. The slug is **permanently reserved** after deletion (supply-chain
+safety) — it cannot be reused even by you. There is **no CLI undo**;
+the registry operator can restore from the soft-delete row if asked.
+
+Without `--force` the CLI shows the package metadata and prompts for
+confirmation. Use `--force` ONLY when the user has explicitly confirmed
+the destructive action (e.g. they said "yes, delete it"). Never pass
+`--force` on the user's behalf.
+
+If the body contains third-party content, MUST preserve the original
+copyright and license text inside the body and link to source via
+`homepage` — even on the version you intend to delete, in case the
+operator restores it.
 
 ## Commands
 
@@ -122,6 +129,15 @@ User: "release with a note that breaking-changes the API"
 2. clean → drop --dry-run for the real push
 </example>
 
+<example>
+User: "delete <full_slug>"
+1. confirm with the user that they understand the slug is permanently
+   reserved (cannot be reused) and there is no CLI undo
+2. kordis delete <full_slug>   # interactive confirmation prompt
+   - if user already confirmed in prior turn, kordis delete <full_slug> --force
+3. show the {status, full_slug} reply to the user
+</example>
+
 ## Forking another Kordis package
 
 When the user asks to fork / adapt / republish someone else's package

package/dist/index.js

@@ -175,6 +175,7 @@ var init_errors = __esm({
       error: z3.object({
         code: ErrorCodeSchema,
         message: z3.string(),
+        hint: z3.string().optional(),
         flags: z3.array(ReviewFlagSchema).optional(),
         retry_after_seconds: z3.number().int().nonnegative().optional(),
         request_id: z3.string().optional()
@@ -631,7 +632,17 @@ var init_api = __esm({
        * KORDIS.md recommends but does not enforce.
        */
       attribution: z9.string(),
-      read_at: z9.string().datetime({ offset: true })
+      read_at: z9.string().datetime({ offset: true }),
+      /**
+       * Paths (NOT contents) of bundled assets that ship with the package —
+       * `references/*.md`, `assets/*.html`, `scripts/*.py`, etc. Agents reading a
+       * skill that references its own bundled files (e.g. "use
+       * `assets/template.html`") need a structured signal to switch to
+       * `kordis pull`; without it, the only hint is in body prose. Optional in
+       * the schema for backwards compatibility with pre-0.2.3 servers; the
+       * current server always populates it (empty array when no assets).
+       */
+      bundled_assets: z9.array(z9.string()).optional()
     });
     PullPackageResponseSchema = z9.object({
       status: z9.enum(["installed", "already_installed", "skipped"]),
@@ -718,6 +729,7 @@ var init_errors2 = __esm({
     KordisApiError = class extends Error {
       code;
       status;
+      hint;
       flags;
       retryAfter;
       requestId;
@@ -726,6 +738,7 @@ var init_errors2 = __esm({
         this.name = "KordisApiError";
         this.code = envelope.error.code;
         this.status = status;
+        this.hint = envelope.error.hint;
         this.flags = envelope.error.flags ?? [];
         this.retryAfter = envelope.error.retry_after_seconds;
         this.requestId = envelope.error.request_id ?? requestId;
@@ -1041,7 +1054,7 @@ async function saveCliConfig(cfg) {
 }
 
 // src/keychain.ts
-import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, unlink } from "fs/promises";
+import { access, readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, unlink } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 var SERVICE = "kordis";
@@ -1054,12 +1067,28 @@ async function loadKeytar() {
     return null;
   }
 }
+function kordisHome() {
+  return process.env["KORDIS_HOME"] ?? join2(homedir2(), ".kordis");
+}
 function fallbackPath() {
-  return join2(process.env["KORDIS_HOME"] ?? join2(homedir2(), ".kordis"), ".tokens.json");
+  return join2(kordisHome(), ".tokens.json");
+}
+function warningSentinelPath() {
+  return join2(kordisHome(), ".warned-no-keychain");
+}
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
 async function createKeychain() {
   const keytar = await loadKeytar();
   if (keytar) {
+    await unlink(warningSentinelPath()).catch(() => {
+    });
     return {
       async save(username, tokens) {
         await keytar.setPassword(SERVICE, username, JSON.stringify(tokens));
@@ -1073,15 +1102,22 @@ async function createKeychain() {
       }
     };
   }
-  if (!plaintextWarningEmitted && process.env["KORDIS_JSON"] !== "1") {
+  if (!plaintextWarningEmitted && process.env["KORDIS_JSON"] !== "1" && !await pathExists(warningSentinelPath())) {
     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}
+[kordis] On macOS install Xcode Command Line Tools, on Linux install libsecret-1-dev to enable keytar.
+[kordis] (suppressing this warning on subsequent runs \u2014 delete ~/.kordis/.warned-no-keychain to re-enable)${reset}
 `
     );
+    await mkdir2(kordisHome(), { recursive: true }).catch(() => {
+    });
+    await writeFile2(warningSentinelPath(), "", { mode: 384 }).catch(() => {
+    });
+  } else if (!plaintextWarningEmitted) {
+    plaintextWarningEmitted = true;
   }
   const store = await readAll();
   return {
@@ -1920,10 +1956,13 @@ function zodFail(issues) {
         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.";
+      } else if (field) {
+        hint = `Fix the value of frontmatter field "${field}" to match the schema. See the per-type spec under packages/harness-schema/src/types/ for the exact shape.`;
+      } else {
+        hint = "Fix the frontmatter to match the schema. See the per-type spec under packages/harness-schema/src/types/ for the exact shape.";
       }
-      const extra = {};
+      const extra = { hint };
       if (field) extra.field = field;
-      if (hint) extra.hint = hint;
       return flag("invalid_frontmatter", i.message, extra);
     })
   };
@@ -2862,6 +2901,17 @@ function readCommand() {
       }
       process.stdout.write(res.body);
       if (!res.body.endsWith("\n")) process.stdout.write("\n");
+      const bundled = res.bundled_assets ?? [];
+      if (bundled.length > 0) {
+        process.stderr.write(
+          `${c.gray("\u2014")} ${c.bold(`\u24D8 ${bundled.length} bundled asset(s)`)} \u2014 fetch with ${c.cyan(`kordis pull ${res.full_slug}`)}:
+`
+        );
+        for (const path of bundled) {
+          process.stderr.write(`    ${c.gray("-")} ${path}
+`);
+        }
+      }
       process.stderr.write(
         `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version} ${c.gray("\xB7")} ${res.type} (tier ${res.tier}) ${c.gray("\xB7")} ${c.cyan(res.attribution)}
 `
@@ -2944,7 +2994,7 @@ function logoutCommand() {
 }
 
 // src/commands/setup.ts
-import { readFile as readFile5, writeFile as writeFile5, mkdir as mkdir5, access } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile5, mkdir as mkdir5, access as access2 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { join as join7, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -2969,7 +3019,7 @@ var SKILL_TARGETS = [
 ];
 async function exists(path) {
   try {
-    await access(path);
+    await access2(path);
     return true;
   } catch {
     return false;
@@ -3701,6 +3751,7 @@ function handleError(err) {
         error: {
           code: err.code,
           message: err.message,
+          ...err.hint ? { hint: err.hint } : {},
           flags: err.flags,
           ...err.retryAfter !== void 0 ? { retry_after_seconds: err.retryAfter } : {},
           request_id: err.requestId
@@ -3708,6 +3759,11 @@ function handleError(err) {
       });
     } else {
       printHuman(c.red(`\u2717 ${err.code}: ${err.message}`));
+      if (err.hint) {
+        for (const line of err.hint.split("\n")) {
+          printHuman(c.gray(`  \u2192 ${line}`));
+        }
+      }
       for (const f of err.flags) {
         printHuman(c.red(`  - ${f.code}${f.message ? `: ${f.message}` : ""}`));
         if (f.hint) {

package/package.json

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