@nomadamas/k-skill 0.1.0 → 0.2.0

package/src/assemble.js

@@ -6,6 +6,7 @@ const path = require("node:path");
 const packageRoot = path.join(__dirname, "..");
 const templatesDir = path.join(packageRoot, "templates");
 const skillsDir = path.join(packageRoot, "skills");
+const CLI_INVOCATION = "npx -y @nomadamas/k-skill@0";
 
 const KNOWN_PROFILES = [
   "core",
@@ -14,12 +15,13 @@ const KNOWN_PROFILES = [
   "vault",
   "action:booking",
   "action:commerce",
-  "action:communication",
   "action:submission",
   "action:account",
-  "hard-boundary",
+  "action:recruiting",
+  "legal",
   "lookup",
   "local",
+  "operations",
 ];
 
 function profileTemplatePath(profile) {
@@ -64,6 +66,133 @@ function loadSkill(skillName) {
   };
 }
 
+function assetRelativePaths(skillName) {
+  const { dir } = loadSkill(skillName);
+  return bundledFiles(skillName).map((filePath) => path.relative(dir, filePath).split(path.sep).join("/"));
+}
+
+function resolveBundledAsset(skillName, relativePath, allowedRoots = ["scripts", "references", "tests"]) {
+  const { dir } = loadSkill(skillName);
+  const normalized = path.posix.normalize(String(relativePath).replaceAll("\\", "/"));
+  const root = normalized.split("/")[0];
+
+  if (
+    normalized === "." ||
+    normalized.startsWith("../") ||
+    path.posix.isAbsolute(normalized) ||
+    !allowedRoots.includes(root)
+  ) {
+    const error = new Error(
+      `asset path "${relativePath}" must stay inside ${allowedRoots.join(", ")} for skill "${skillName}"`,
+    );
+    error.code = "EASSETPATH";
+    throw error;
+  }
+
+  const candidate = path.resolve(dir, ...normalized.split("/"));
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+    const error = new Error(`asset "${normalized}" is not bundled for skill "${skillName}"`);
+    error.code = "EASSETNOTFOUND";
+    throw error;
+  }
+
+  const realDir = fs.realpathSync(dir);
+  const realCandidate = fs.realpathSync(candidate);
+  if (!realCandidate.startsWith(`${realDir}${path.sep}`)) {
+    const error = new Error(`asset "${normalized}" escapes skill "${skillName}"`);
+    error.code = "EASSETPATH";
+    throw error;
+  }
+
+  return realCandidate;
+}
+
+function readBundledAsset(skillName, relativePath) {
+  return fs.readFileSync(resolveBundledAsset(skillName, relativePath, ["references", "scripts"]), "utf8");
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function scriptPathPattern(skillName, relativePath) {
+  const rel = escapeRegex(relativePath);
+  const skill = escapeRegex(skillName);
+  return `(?:"?\\$SKILL_DIR/|\\./${skill}/|${skill}/|\\./)?${rel}"?`;
+}
+
+function rewriteAssetCommandReferences(raw, skillName) {
+  let output = raw;
+  const assets = assetRelativePaths(skillName);
+  const scripts = assets.filter((relativePath) => relativePath.startsWith("scripts/"));
+  const references = assets.filter((relativePath) => relativePath.startsWith("references/"));
+
+  for (const relativePath of scripts.sort((a, b) => b.length - a.length)) {
+    const assetPattern = scriptPathPattern(skillName, relativePath);
+    const execCommand = `${CLI_INVOCATION} exec ${skillName} ${relativePath} --`;
+
+    output = output.replace(
+      new RegExp(`(?:python3?|node|bash|uv\\s+run)\\s+${assetPattern}`, "g"),
+      execCommand,
+    );
+    output = output.replace(
+      new RegExp(`(^|[|;&]\\s*)${assetPattern}(?=\\s|$)`, "gm"),
+      `$1${execCommand}`,
+    );
+  }
+
+  for (const relativePath of assets.filter((item) => /\.(?:md|txt|pin)$/i.test(item))) {
+    const assetPattern = scriptPathPattern(skillName, relativePath);
+    const readCommand = `${CLI_INVOCATION} read ${skillName} ${relativePath}`;
+
+    output = output.replace(new RegExp(`cat\\s+${assetPattern}`, "g"), readCommand);
+  }
+
+  for (const relativePath of references.sort((a, b) => b.length - a.length)) {
+    const escaped = escapeRegex(relativePath);
+    const readCommand = `${CLI_INVOCATION} read ${skillName} ${relativePath}`;
+
+    output = output.replace(
+      new RegExp(`\\[([^\\]]+)\\]\\((?:\\./)?${escaped}\\)`, "g"),
+      (_match, label) =>
+        label.includes(relativePath) ? `\`${readCommand}\`` : `${label} (\`${readCommand}\`)`,
+    );
+    output = output.replace(
+      new RegExp(`\`(?:\\./)?${escaped}\``, "g"),
+      `\`${readCommand}\``,
+    );
+  }
+
+  return output;
+}
+
+// Source instructions are migrated to the CLI surface, and assembly repeats
+// the normalization defensively so a newly added relative command cannot leak
+// into a released instruction before CI catches it.
+function rewriteBundledAssetInstructions(raw, skillName) {
+  const assets = assetRelativePaths(skillName);
+  const scripts = assets.filter((relativePath) => relativePath.startsWith("scripts/"));
+  const references = assets.filter((relativePath) => relativePath.startsWith("references/"));
+  let output = rewriteAssetCommandReferences(raw, skillName);
+
+  if (scripts.length || references.length) {
+    const accessRules = [
+      "## Bundled asset access",
+      "",
+      `- Execute bundled helpers only through \`${CLI_INVOCATION} exec ${skillName} scripts/<file> -- <args>\`; do not assume a repository-relative or installed-skill-relative path.`,
+      `- Resolve an asset path with \`${CLI_INVOCATION} path ${skillName} <relative-path>\` only when another tool explicitly requires a filesystem path.`,
+    ];
+    if (references.length) {
+      accessRules.push(
+        `- Read bundled references through \`${CLI_INVOCATION} read ${skillName} references/<file>\`.`,
+      );
+    }
+    output = `${accessRules.join("\n")}\n\n${output}`;
+  }
+
+  return output;
+}
+
 // Template files interleave `<!-- mode:always -->`, `<!-- mode:dolshoi -->`,
 // and `<!-- mode:generic -->` markers. Only the sections matching the detected
 // mode (plus always-sections) are emitted.
@@ -107,7 +236,8 @@ function assemble(skillName, runtime) {
   ].join("\n");
 
   // instruction.md may also use mode markers for mode-specific sections.
-  return `${header}\n\n${renderTemplate(instruction, runtime.mode)}\n`;
+  const renderedInstruction = renderTemplate(instruction, runtime.mode);
+  return `${header}\n\n${rewriteBundledAssetInstructions(renderedInstruction, skillName)}\n`;
 }
 
 function bundledFiles(skillName) {
@@ -131,4 +261,17 @@ function bundledFiles(skillName) {
   return results.sort();
 }
 
-module.exports = { assemble, bundledFiles, listSkills, loadSkill, renderTemplate, KNOWN_PROFILES };
+module.exports = {
+  CLI_INVOCATION,
+  KNOWN_PROFILES,
+  assemble,
+  assetRelativePaths,
+  bundledFiles,
+  listSkills,
+  loadSkill,
+  readBundledAsset,
+  renderTemplate,
+  resolveBundledAsset,
+  rewriteAssetCommandReferences,
+  rewriteBundledAssetInstructions,
+};

package/src/execute.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const childProcess = require("node:child_process");
+
+const { resolveBundledAsset } = require("./assemble");
+
+function splitShebang(value) {
+  return value.trim().split(/\s+/).filter(Boolean);
+}
+
+function resolveRunner(scriptPath, env = process.env) {
+  const firstLine = fs.readFileSync(scriptPath, "utf8").split(/\r?\n/, 1)[0];
+
+  if (firstLine.startsWith("#!")) {
+    const parts = splitShebang(firstLine.slice(2));
+    if (parts[0] === "/usr/bin/env") {
+      const args = parts.slice(parts[1] === "-S" ? 2 : 1);
+      if (args.length) {
+        const [command, ...prefixArgs] = args;
+        return {
+          command: command === "node" ? process.execPath : command,
+          args: [...prefixArgs, scriptPath],
+        };
+      }
+    }
+
+    if (parts[0]) {
+      return { command: parts[0], args: [...parts.slice(1), scriptPath] };
+    }
+  }
+
+  switch (path.extname(scriptPath).toLowerCase()) {
+    case ".py":
+      return { command: env.KSKILL_PYTHON || "python3", args: [scriptPath] };
+    case ".js":
+    case ".cjs":
+    case ".mjs":
+      return { command: process.execPath, args: [scriptPath] };
+    case ".sh":
+      return { command: env.KSKILL_BASH || "bash", args: [scriptPath] };
+    default: {
+      const error = new Error(
+        `cannot determine a runner for "${path.basename(scriptPath)}"; use a supported shebang or .py/.js/.sh extension`,
+      );
+      error.code = "EUNSUPPORTEDSCRIPT";
+      throw error;
+    }
+  }
+}
+
+function runBundledScript(skillName, relativePath, args = [], options = {}) {
+  const scriptPath = resolveBundledAsset(skillName, relativePath, ["scripts"]);
+  const runner = resolveRunner(scriptPath, options.env || process.env);
+  const result = childProcess.spawnSync(runner.command, [...runner.args, ...args], {
+    cwd: options.cwd || process.cwd(),
+    env: {
+      ...process.env,
+      ...options.env,
+      KSKILL_BUNDLED_SKILL_DIR: path.dirname(path.dirname(scriptPath)),
+    },
+    encoding: options.encoding,
+    stdio: options.stdio || "inherit",
+  });
+
+  if (result.error) throw result.error;
+  if (result.signal) {
+    const error = new Error(`script terminated by signal ${result.signal}`);
+    error.code = "ESCRIPTSIGNAL";
+    throw error;
+  }
+
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+module.exports = { resolveRunner, runBundledScript };

package/templates/action-recruiting.md

@@ -0,0 +1,5 @@
+<!-- mode:dolshoi -->
+- Use the official employer account surface to search and compare candidates, keeping masked/private data protected until the requested candidate is fixed.
+- Paid resume unlocks, contact-detail reveals, credit use, proposal delivery, shortlist mutation, and candidate-status changes are separate external effects. Immediately before each such action, call `clarify` with the candidate, cost/credit impact, disclosed data, message payload, and resulting state; execute only the approved action and verify it.
+<!-- mode:generic -->
+- Search and compare visible candidate information through the documented logged-in browser workflow. Prepare the shortlist and proposal draft, then hand paid unlocks, private-data reveals, credit use, and proposal delivery to the user on the official surface.

package/templates/legal.md

@@ -0,0 +1,6 @@
+<!-- mode:dolshoi -->
+- Use the official legal/government surface with CloakBrowser and vault-backed login. Proceed through ordinary login, supported identity verification, document upload, form filling, fee calculation, and reversible preparation when the official surface and available capabilities support them.
+- Do not evade CAPTCHA, impersonate the user, forge identity evidence, or bypass an authentication/security control. If the official flow presents a user-presence-only verification or electronic-signature prompt, open the exact prompt and let the user complete that control, then resume the same workflow immediately afterward.
+- Immediately before filing, bidding, paying a government fee, signing, cancelling, or another irreversible legal effect, call `clarify` with the exact case/form, parties, documents, amount, and legal effect. Execute after approval and verify the official receipt or resulting status.
+<!-- mode:generic -->
+- Navigate the official legal/government surface and complete every supported reversible preparation step. Keep login, identity verification, CAPTCHA, electronic signature, filing, bidding, payment, and cancellation on the official user-controlled surface unless the host provides an explicit capability for that step.

package/templates/operations.md

@@ -0,0 +1,3 @@
+<!-- mode:always -->
+- This skill operates or configures the k-skill installation itself. Inspect current state, apply the requested reversible setup/update/repair operation, and verify the installed CLI, skill directories, browser runtime, proxy connectivity, and credential-provider integration that the request covers.
+- Do not change unrelated user configuration. Before deleting data, replacing user-managed files, changing persistent update automation, or performing another irreversible operation, call `clarify` with the exact paths and effect.

package/templates/action-communication.md

@@ -1,5 +0,0 @@
-<!-- mode:dolshoi -->
-- When sending is requested, continue past lookup: identify the exact recipient and payload, prepare the draft on the official surface, and keep it unsent.
-- Immediately before actual delivery (message, application, inquiry), call `clarify` with the exact recipient and full payload. After approval, send and verify the sent state.
-<!-- mode:generic -->
-- Prepare the recipient, draft, and official surface link that the documented portable workflow supports, then hand the final send action to the user. Do not automate delivery here.

package/templates/hard-boundary.md

@@ -1,3 +0,0 @@
-<!-- mode:always -->
-- This skill has a hard boundary (law, mandatory physical presence, CAPTCHA, identity proofing, or electronic signature). Navigate to the exact official case/form/item, complete every lawful reversible preparation step, and prefill all safe fields — but never automate the bounded final step. Completion means the exact official screen is open, safe inputs are prepared, and the single user-only step is stated precisely.
-- If the remaining official step is merely irreversible (not identity-bound or prohibited), call `clarify` with the exact target and effect, then execute after approval.