@hasna/skills 0.8.5 → 0.8.7

package/README.md

@@ -246,8 +246,11 @@ select complete skill instructions from that verified cache using explicit
 A session retains its selected versions; compaction restores loaded instructions,
 and subagents inherit the parent's selection. Instructions that exceed the
 context budget produce an explicit `skills load` command. A hook never executes
-a skill. Cached use is explicit and expires after 24 hours; authentication
-failures do not silently switch to a local catalog.
+a skill. Cached use is explicit and expires after 24 hours. When cached context
+expires or is missing, the hook makes one authenticated API attempt for the same
+pinned session. It preserves exact versions and does not extend an expired
+receipt's lifetime. Authentication, integrity and native discovery failures still
+block; they do not silently switch to a local catalog.
 
 ## Profiles, station sync and rollback
 

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.8.5",
+    version: "0.8.7",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -38212,6 +38212,35 @@ function isSafeRelativePath(value) {
   const normalized = normalize(value).replace(/\\/g, "/");
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
 }
+function validateRuntimeEntry(skillPath, entrypoint, issues, warnings) {
+  if (typeof entrypoint !== "string" || !isSafeRelativePath(entrypoint) || /^[a-zA-Z]:/.test(entrypoint) || entrypoint.includes("\\") || entrypoint.split("/").some((part) => !part || part === "." || part === "..")) {
+    add2(issues, "skill.runtime_entrypoint_unsafe", "runtime.entrypoint must be a canonical relative file path inside the skill directory");
+    return;
+  }
+  const parts = entrypoint.split("/");
+  let current = skillPath;
+  for (let index = 0;index < parts.length; index++) {
+    current = join8(current, parts[index]);
+    let info;
+    try {
+      info = lstatSync(current);
+    } catch {
+      add2(issues, "skill.runtime_entrypoint_missing", "The declared runtime.entrypoint is missing or inaccessible");
+      return;
+    }
+    if (info.isSymbolicLink()) {
+      add2(issues, "skill.runtime_entrypoint_symlink", "runtime.entrypoint must not traverse symbolic links");
+      return;
+    }
+    if (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) {
+      add2(issues, "skill.runtime_entrypoint_not_file", "runtime.entrypoint must resolve to a regular file");
+      return;
+    }
+    if (index === parts.length - 1 && info.size < 50) {
+      add2(warnings, "skill.runtime_entrypoint_minimal", `Source entry point is very small (${info.size}B)`);
+    }
+  }
+}
 function isHostedPackageMetadata(pkg) {
   return isHostedMetadataPackage(pkg);
 }
@@ -38447,10 +38476,22 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
   } else {
     metadata.runtime = hostedMetadata ? "hosted" : "local";
     const srcDir = join8(skillPath, "src");
+    let declaredEntrypoint;
+    const manifestPath = join8(skillPath, "skill.json");
+    if (!hostedMetadata && existsSync8(manifestPath)) {
+      try {
+        const manifest = asRecord(readJsonFile(manifestPath));
+        declaredEntrypoint = asRecord(manifest?.runtime)?.entrypoint;
+      } catch {
+        add2(issues, "skill.manifest_invalid", "skill.json must contain valid JSON");
+      }
+    }
     if (hostedMetadata) {
       if (existsSync8(srcDir)) {
         add2(issues, "skill.hosted_source_forbidden", "Hosted metadata skills must not include local implementation source");
       }
+    } else if (declaredEntrypoint !== undefined && declaredEntrypoint !== null) {
+      validateRuntimeEntry(skillPath, declaredEntrypoint, issues, warnings);
     } else if (!existsSync8(srcDir)) {
       add2(issues, "skill.src_missing", "Missing src/ directory");
     } else if (!existsSync8(join8(srcDir, "index.ts")) && !existsSync8(join8(srcDir, "index.js"))) {
@@ -40028,7 +40069,11 @@ function validatePortableSkillDirectory(name, skillPath) {
           "package.missing",
           "package.bin_missing",
           "skill.src_missing",
-          "skill.src_index_missing"
+          "skill.src_index_missing",
+          "skill.runtime_entrypoint_unsafe",
+          "skill.runtime_entrypoint_missing",
+          "skill.runtime_entrypoint_symlink",
+          "skill.runtime_entrypoint_not_file"
         ]);
         for (let i = issues.length - 1;i >= 0; i--) {
           if (executableOnlyCodes.has(issues[i].code))
@@ -105416,6 +105461,34 @@ __export(exports_agent_integration, {
 });
 import { readFileSync as readFileSync37 } from "fs";
 import { isAbsolute as isAbsolute17 } from "path";
+async function contextForHook(input3, profileId, cached2, deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0)
+    throw new Error("Skills hook deadline exceeded");
+  const args2 = [process.execPath, process.argv[1], "context", "--stdin", "--json", "--selection-profile", profileId];
+  if (cached2)
+    args2.push("--cached");
+  const child = Bun.spawn(args2, { stdin: new Blob([JSON.stringify(input3)]), stdout: "pipe", stderr: "pipe", env: { ...process.env, NO_COLOR: "1" } });
+  const timer = setTimeout(() => child.kill("SIGKILL"), Math.min(6500, remaining));
+  let result2;
+  let status;
+  try {
+    const [stdout, , exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+    status = exitCode;
+    result2 = JSON.parse(stdout);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (status !== 0) {
+    if (cached2 && RECOVERABLE_CONTEXT_CACHE_ERRORS.has(result2?.error?.code)) {
+      return contextForHook(input3, profileId, false, deadline);
+    }
+    throw new Error("Skills context could not be resolved");
+  }
+  if (typeof result2?.context !== "string")
+    throw new Error("Invalid Skills context response");
+  return result2;
+}
 function agents(value) {
   if (value === "all")
     return [...INTEGRATION_AGENTS];
@@ -105444,6 +105517,7 @@ function registerAgentIntegration(parent) {
     }
   });
   hook.command("user-prompt").requiredOption("--agent <agent>", `Native payload/output adapter: ${INTEGRATION_AGENTS.join(", ")}`).option("--event <event>", "Native lifecycle event supplied by the installed adapter").option("--selection-profile <id>", "Selection profile to load").description("Read native lifecycle JSON on stdin and return selected context").action(async (options) => {
+    const deadline = Date.now() + 12000;
     let event = options.agent === "hermes" && options.event === "pre_tool_call" ? "pre_tool_call" : "UserPromptSubmit";
     try {
       if (agents(options.agent).length !== 1)
@@ -105492,38 +105566,29 @@ function registerAgentIntegration(parent) {
       if (typeof input3.prompt === "string")
         input3.prompt = normalizeAgentHookPrompt(options.agent, nativeEvent, input3.prompt);
       if (event === "SessionStart") {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+          throw new Error("Skills hook deadline exceeded");
         const refresh = Bun.spawn([process.execPath, process.argv[1], "sync", "--selection-profile", selectionProfile, "--json"], { stdin: "ignore", stdout: "pipe", stderr: "pipe", env: { ...process.env, NO_COLOR: "1" } });
-        const timer2 = setTimeout(() => refresh.kill("SIGKILL"), 6500);
+        const timer = setTimeout(() => refresh.kill("SIGKILL"), Math.min(6500, remaining));
         try {
           const [, , status] = await Promise.all([new Response(refresh.stdout).text(), new Response(refresh.stderr).text(), refresh.exited]);
           if (status !== 0)
             throw new Error("Session profile refresh failed");
         } finally {
-          clearTimeout(timer2);
+          clearTimeout(timer);
         }
       }
-      const args2 = [process.execPath, process.argv[1], "context", "--stdin", "--json", "--cached", "--selection-profile", selectionProfile];
-      const child = Bun.spawn(args2, { stdin: new Blob([JSON.stringify(input3)]), stdout: "pipe", stderr: "pipe", env: { ...process.env, NO_COLOR: "1" } });
-      const timer = setTimeout(() => child.kill("SIGKILL"), 6500);
-      try {
-        const [stdout, , status] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
-        if (status !== 0)
-          throw new Error("Skills context could not be resolved");
-        const result2 = JSON.parse(stdout);
-        if (typeof result2.context !== "string")
-          throw new Error("Invalid Skills context response");
-        const output2 = hookContextOutput(event, result2);
-        if (options.agent === "hermes") {
-          await writeCliOutput(JSON.stringify({ context: output2.hookSpecificOutput?.additionalContext ?? "" }));
-        } else if (options.agent === "cursor") {
-          await writeCliOutput(JSON.stringify(event === "SessionStart" ? { additional_context: output2.hookSpecificOutput?.additionalContext ?? "" } : { continue: true }));
-        } else {
-          if (options.agent === "gemini" && output2.hookSpecificOutput)
-            output2.hookSpecificOutput.hookEventName = nativeEvent;
-          await writeCliOutput(JSON.stringify(output2));
-        }
-      } finally {
-        clearTimeout(timer);
+      const result2 = await contextForHook(input3, selectionProfile, true, deadline);
+      const output2 = hookContextOutput(event, result2);
+      if (options.agent === "hermes") {
+        await writeCliOutput(JSON.stringify({ context: output2.hookSpecificOutput?.additionalContext ?? "" }));
+      } else if (options.agent === "cursor") {
+        await writeCliOutput(JSON.stringify(event === "SessionStart" ? { additional_context: output2.hookSpecificOutput?.additionalContext ?? "" } : { continue: true }));
+      } else {
+        if (options.agent === "gemini" && output2.hookSpecificOutput)
+          output2.hookSpecificOutput.hookEventName = nativeEvent;
+        await writeCliOutput(JSON.stringify(output2));
       }
     } catch (error61) {
       const reason = error61 instanceof Error && error61.message.startsWith("NATIVE_SKILL_DRIFT:") ? error61.message : "Skills context is unavailable. Run skills sync --selection-profile <id> and skills context --stdin --json to diagnose the selected profile.";
@@ -105559,11 +105624,13 @@ function registerAgentIntegration(parent) {
     }
   });
 }
+var RECOVERABLE_CONTEXT_CACHE_ERRORS;
 var init_agent_integration2 = __esm(() => {
   init_agent_hermes();
   init_context();
   init_agent_adapters();
   init_agent_integration();
+  RECOVERABLE_CONTEXT_CACHE_ERRORS = new Set(["CACHED_PROFILE_EXPIRED", "CACHED_PROFILE_MISSING", "CACHED_BUNDLE_MISSING"]);
 });
 
 // src/lib/profile-admin.ts

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.8.5",
+    version: "0.8.7",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -36478,6 +36478,35 @@ function isSafeRelativePath(value) {
   const normalized = normalize(value).replace(/\\/g, "/");
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
 }
+function validateRuntimeEntry(skillPath, entrypoint, issues, warnings) {
+  if (typeof entrypoint !== "string" || !isSafeRelativePath(entrypoint) || /^[a-zA-Z]:/.test(entrypoint) || entrypoint.includes("\\") || entrypoint.split("/").some((part) => !part || part === "." || part === "..")) {
+    add(issues, "skill.runtime_entrypoint_unsafe", "runtime.entrypoint must be a canonical relative file path inside the skill directory");
+    return;
+  }
+  const parts = entrypoint.split("/");
+  let current = skillPath;
+  for (let index = 0;index < parts.length; index++) {
+    current = join7(current, parts[index]);
+    let info;
+    try {
+      info = lstatSync3(current);
+    } catch {
+      add(issues, "skill.runtime_entrypoint_missing", "The declared runtime.entrypoint is missing or inaccessible");
+      return;
+    }
+    if (info.isSymbolicLink()) {
+      add(issues, "skill.runtime_entrypoint_symlink", "runtime.entrypoint must not traverse symbolic links");
+      return;
+    }
+    if (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) {
+      add(issues, "skill.runtime_entrypoint_not_file", "runtime.entrypoint must resolve to a regular file");
+      return;
+    }
+    if (index === parts.length - 1 && info.size < 50) {
+      add(warnings, "skill.runtime_entrypoint_minimal", `Source entry point is very small (${info.size}B)`);
+    }
+  }
+}
 function isHostedPackageMetadata(pkg) {
   return isHostedMetadataPackage(pkg);
 }
@@ -36713,10 +36742,22 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
   } else {
     metadata.runtime = hostedMetadata ? "hosted" : "local";
     const srcDir = join7(skillPath, "src");
+    let declaredEntrypoint;
+    const manifestPath = join7(skillPath, "skill.json");
+    if (!hostedMetadata && existsSync4(manifestPath)) {
+      try {
+        const manifest = asRecord(readJsonFile(manifestPath));
+        declaredEntrypoint = asRecord(manifest?.runtime)?.entrypoint;
+      } catch {
+        add(issues, "skill.manifest_invalid", "skill.json must contain valid JSON");
+      }
+    }
     if (hostedMetadata) {
       if (existsSync4(srcDir)) {
         add(issues, "skill.hosted_source_forbidden", "Hosted metadata skills must not include local implementation source");
       }
+    } else if (declaredEntrypoint !== undefined && declaredEntrypoint !== null) {
+      validateRuntimeEntry(skillPath, declaredEntrypoint, issues, warnings);
     } else if (!existsSync4(srcDir)) {
       add(issues, "skill.src_missing", "Missing src/ directory");
     } else if (!existsSync4(join7(srcDir, "index.ts")) && !existsSync4(join7(srcDir, "index.js"))) {
@@ -38176,7 +38217,11 @@ function validatePortableSkillDirectory(name, skillPath) {
           "package.missing",
           "package.bin_missing",
           "skill.src_missing",
-          "skill.src_index_missing"
+          "skill.src_index_missing",
+          "skill.runtime_entrypoint_unsafe",
+          "skill.runtime_entrypoint_missing",
+          "skill.runtime_entrypoint_symlink",
+          "skill.runtime_entrypoint_not_file"
         ]);
         for (let i = issues.length - 1;i >= 0; i--) {
           if (executableOnlyCodes.has(issues[i].code))

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.5",
+  version: "0.8.7",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -83749,7 +83749,7 @@ var require_protocols9 = __commonJS((exports) => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.5",
+  version: "0.8.7",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -76168,7 +76168,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.5",
+  version: "0.8.7",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/index.js

@@ -7376,6 +7376,35 @@ function isSafeRelativePath(value) {
   const normalized = normalize(value).replace(/\\/g, "/");
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
 }
+function validateRuntimeEntry(skillPath, entrypoint, issues, warnings) {
+  if (typeof entrypoint !== "string" || !isSafeRelativePath(entrypoint) || /^[a-zA-Z]:/.test(entrypoint) || entrypoint.includes("\\") || entrypoint.split("/").some((part) => !part || part === "." || part === "..")) {
+    add(issues, "skill.runtime_entrypoint_unsafe", "runtime.entrypoint must be a canonical relative file path inside the skill directory");
+    return;
+  }
+  const parts = entrypoint.split("/");
+  let current = skillPath;
+  for (let index = 0;index < parts.length; index++) {
+    current = join4(current, parts[index]);
+    let info;
+    try {
+      info = lstatSync(current);
+    } catch {
+      add(issues, "skill.runtime_entrypoint_missing", "The declared runtime.entrypoint is missing or inaccessible");
+      return;
+    }
+    if (info.isSymbolicLink()) {
+      add(issues, "skill.runtime_entrypoint_symlink", "runtime.entrypoint must not traverse symbolic links");
+      return;
+    }
+    if (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) {
+      add(issues, "skill.runtime_entrypoint_not_file", "runtime.entrypoint must resolve to a regular file");
+      return;
+    }
+    if (index === parts.length - 1 && info.size < 50) {
+      add(warnings, "skill.runtime_entrypoint_minimal", `Source entry point is very small (${info.size}B)`);
+    }
+  }
+}
 function isHostedPackageMetadata(pkg) {
   return isHostedMetadataPackage(pkg);
 }
@@ -7611,10 +7640,22 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
   } else {
     metadata.runtime = hostedMetadata ? "hosted" : "local";
     const srcDir = join4(skillPath, "src");
+    let declaredEntrypoint;
+    const manifestPath = join4(skillPath, "skill.json");
+    if (!hostedMetadata && existsSync4(manifestPath)) {
+      try {
+        const manifest = asRecord(readJsonFile(manifestPath));
+        declaredEntrypoint = asRecord(manifest?.runtime)?.entrypoint;
+      } catch {
+        add(issues, "skill.manifest_invalid", "skill.json must contain valid JSON");
+      }
+    }
     if (hostedMetadata) {
       if (existsSync4(srcDir)) {
         add(issues, "skill.hosted_source_forbidden", "Hosted metadata skills must not include local implementation source");
       }
+    } else if (declaredEntrypoint !== undefined && declaredEntrypoint !== null) {
+      validateRuntimeEntry(skillPath, declaredEntrypoint, issues, warnings);
     } else if (!existsSync4(srcDir)) {
       add(issues, "skill.src_missing", "Missing src/ directory");
     } else if (!existsSync4(join4(srcDir, "index.ts")) && !existsSync4(join4(srcDir, "index.js"))) {
@@ -9146,7 +9187,11 @@ function validatePortableSkillDirectory(name, skillPath) {
           "package.missing",
           "package.bin_missing",
           "skill.src_missing",
-          "skill.src_index_missing"
+          "skill.src_index_missing",
+          "skill.runtime_entrypoint_unsafe",
+          "skill.runtime_entrypoint_missing",
+          "skill.runtime_entrypoint_symlink",
+          "skill.runtime_entrypoint_not_file"
         ]);
         for (let i = issues.length - 1;i >= 0; i--) {
           if (executableOnlyCodes.has(issues[i].code))
@@ -37660,7 +37705,7 @@ import { dirname as dirname14, relative as relative7 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.5",
+  version: "0.8.7",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/sdk/index.js

@@ -96141,7 +96141,7 @@ async function resolveExecutionGrant(input) {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.5",
+  version: "0.8.7",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -98480,6 +98480,35 @@ function isSafeRelativePath(value) {
   const normalized = normalize(value).replace(/\\/g, "/");
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
 }
+function validateRuntimeEntry(skillPath, entrypoint, issues, warnings) {
+  if (typeof entrypoint !== "string" || !isSafeRelativePath(entrypoint) || /^[a-zA-Z]:/.test(entrypoint) || entrypoint.includes("\\") || entrypoint.split("/").some((part) => !part || part === "." || part === "..")) {
+    add(issues, "skill.runtime_entrypoint_unsafe", "runtime.entrypoint must be a canonical relative file path inside the skill directory");
+    return;
+  }
+  const parts = entrypoint.split("/");
+  let current = skillPath;
+  for (let index = 0;index < parts.length; index++) {
+    current = join18(current, parts[index]);
+    let info;
+    try {
+      info = lstatSync13(current);
+    } catch {
+      add(issues, "skill.runtime_entrypoint_missing", "The declared runtime.entrypoint is missing or inaccessible");
+      return;
+    }
+    if (info.isSymbolicLink()) {
+      add(issues, "skill.runtime_entrypoint_symlink", "runtime.entrypoint must not traverse symbolic links");
+      return;
+    }
+    if (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) {
+      add(issues, "skill.runtime_entrypoint_not_file", "runtime.entrypoint must resolve to a regular file");
+      return;
+    }
+    if (index === parts.length - 1 && info.size < 50) {
+      add(warnings, "skill.runtime_entrypoint_minimal", `Source entry point is very small (${info.size}B)`);
+    }
+  }
+}
 function isHostedPackageMetadata(pkg) {
   return isHostedMetadataPackage(pkg);
 }
@@ -98715,10 +98744,22 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
   } else {
     metadata.runtime = hostedMetadata ? "hosted" : "local";
     const srcDir = join18(skillPath, "src");
+    let declaredEntrypoint;
+    const manifestPath = join18(skillPath, "skill.json");
+    if (!hostedMetadata && existsSync6(manifestPath)) {
+      try {
+        const manifest = asRecord(readJsonFile(manifestPath));
+        declaredEntrypoint = asRecord(manifest?.runtime)?.entrypoint;
+      } catch {
+        add(issues, "skill.manifest_invalid", "skill.json must contain valid JSON");
+      }
+    }
     if (hostedMetadata) {
       if (existsSync6(srcDir)) {
         add(issues, "skill.hosted_source_forbidden", "Hosted metadata skills must not include local implementation source");
       }
+    } else if (declaredEntrypoint !== undefined && declaredEntrypoint !== null) {
+      validateRuntimeEntry(skillPath, declaredEntrypoint, issues, warnings);
     } else if (!existsSync6(srcDir)) {
       add(issues, "skill.src_missing", "Missing src/ directory");
     } else if (!existsSync6(join18(srcDir, "index.ts")) && !existsSync6(join18(srcDir, "index.js"))) {
@@ -100216,7 +100257,11 @@ function validatePortableSkillDirectory(name, skillPath) {
           "package.missing",
           "package.bin_missing",
           "skill.src_missing",
-          "skill.src_index_missing"
+          "skill.src_index_missing",
+          "skill.runtime_entrypoint_unsafe",
+          "skill.runtime_entrypoint_missing",
+          "skill.runtime_entrypoint_symlink",
+          "skill.runtime_entrypoint_not_file"
         ]);
         for (let i = issues.length - 1;i >= 0; i--) {
           if (executableOnlyCodes.has(issues[i].code))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {