@tyvm/knowhow 0.0.129 → 0.0.130

package/src/services/SkillsService.ts

@@ -0,0 +1,622 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { createHash } from "crypto";
+import * as https from "https";
+
+// Default local install dir (relative to cwd)
+const LOCAL_SKILLS_DIR = ".knowhow/skills";
+// Lock file paths
+const LOCK_FILE_PRIMARY = ".knowhow/skills/skills-lock.json";
+const LOCK_FILE_LEGACY = "skills-lock.json";
+// Global install dir (absolute)
+const GLOBAL_SKILLS_DIR = path.join(os.homedir(), ".knowhow", "skills");
+const GLOBAL_LOCK_FILE = path.join(os.homedir(), ".knowhow", "skills", "skills-lock.json");
+
+const SKILLS_SH_API = "https://skills.sh";
+
+export interface SkillLockEntry {
+  source: string;
+  sourceType: "github" | "git" | "well-known" | string;
+  skillPath?: string;
+  computedHash: string;
+  commitHash?: string;
+  ref?: string;
+  sourceUrl?: string;
+}
+
+export interface SkillsLock {
+  version: number;
+  skills: Record<string, SkillLockEntry>;
+}
+
+export interface SkillDownloadResponse {
+  files: Array<{ path: string; contents: string }>;
+  hash: string;
+}
+
+export interface SkillsServiceOptions {
+  /** If true, use global ~/.knowhow/skills/ as install dir and lock file location */
+  global?: boolean;
+  /** Custom install directory (absolute or relative to cwd). Overrides global. */
+  installDir?: string;
+  /** Working directory (defaults to process.cwd()) */
+  cwd?: string;
+}
+
+function createEmptyLock(): SkillsLock {
+  return { version: 1, skills: {} };
+}
+
+/**
+ * Compute the same hash as `npx skills` `computeSnapshotHash` does:
+ * given an array of {path, contents} (as returned by skills.sh API),
+ * sort by path, then sha256(path + contents) for each file.
+ */
+export function computeSkillApiHash(
+  files: Array<{ path: string; contents: string }>
+): string {
+  const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+  const hash = createHash("sha256");
+  for (const file of sorted) {
+    hash.update(file.path);
+    hash.update(Buffer.from(file.contents, "utf-8"));
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * Compute a content hash for an already-installed skill folder.
+ * Sort files by relative path, then hash(relativePath + content) for each.
+ */
+export function computeSkillFolderHash(skillDir: string): string {
+  const files: Array<{ relativePath: string; content: Buffer }> = [];
+  collectFiles(skillDir, skillDir, files);
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(file.relativePath);
+    hash.update(file.content);
+  }
+  return hash.digest("hex");
+}
+
+function collectFiles(
+  baseDir: string,
+  currentDir: string,
+  results: Array<{ relativePath: string; content: Buffer }>
+): void {
+  if (!fs.existsSync(currentDir)) return;
+  const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      collectFiles(baseDir, fullPath, results);
+    } else if (entry.isFile()) {
+      const content = fs.readFileSync(fullPath);
+      const relativePath = path
+        .relative(baseDir, fullPath)
+        .split("\\")
+        .join("/");
+      results.push({ relativePath, content });
+    }
+  }
+}
+
+function fetchJson<T>(url: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "knowhow-cli" } }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          try {
+            const body = Buffer.concat(chunks).toString("utf-8");
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(`HTTP ${res.statusCode}: ${body}`));
+              return;
+            }
+            resolve(JSON.parse(body) as T);
+          } catch (e) {
+            reject(e);
+          }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+function fetchRaw(url: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "knowhow-cli" } }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          const body = Buffer.concat(chunks).toString("utf-8");
+          if (res.statusCode && res.statusCode >= 400) {
+            reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+            return;
+          }
+          resolve(body);
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Fetch the latest commit SHA for a file path in a GitHub repo.
+ */
+async function fetchLatestCommitHash(
+  owner: string,
+  repo: string,
+  filePath: string
+): Promise<string | undefined> {
+  try {
+    const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/commits?path=${encodeURIComponent(filePath)}&per_page=1`;
+    const commits = await fetchJson<Array<{ sha: string }>>(url);
+    if (Array.isArray(commits) && commits.length > 0) {
+      return commits[0].sha;
+    }
+  } catch {
+    // Non-fatal
+  }
+  return undefined;
+}
+
+/**
+ * Parse a skill reference. Supports:
+ *   - "owner/repo@skill-name"
+ *   - "owner/repo"
+ *   - "https://github.com/owner/repo"
+ *   - "https://github.com/owner/repo@skill-name"
+ *   - GitHub URL with explicit skillName override
+ */
+export function parseSkillRef(
+  input: string,
+  skillNameOverride?: string
+): {
+  owner: string;
+  repo: string;
+  skill?: string;
+  sourceUrl?: string;
+} {
+  // Strip trailing .git
+  let normalized = input.replace(/\.git$/, "");
+
+  // Extract @skill suffix before URL parsing
+  let skillFromAt: string | undefined;
+  const atIdx = normalized.lastIndexOf("@");
+  // Only treat @ as skill separator if it's not part of the protocol (https://)
+  if (atIdx > 0 && !normalized.slice(0, atIdx).match(/\/\/$/)) {
+    const beforeAt = normalized.slice(0, atIdx);
+    const afterAt = normalized.slice(atIdx + 1);
+    // Make sure the beforeAt part contains a slash (it's a path, not a protocol)
+    if (beforeAt.includes("/")) {
+      skillFromAt = afterAt;
+      normalized = beforeAt;
+    }
+  }
+
+  let owner: string;
+  let repo: string;
+  let sourceUrl: string | undefined;
+
+  // GitHub URL format
+  const githubMatch = normalized.match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/?$/
+  );
+  if (githubMatch) {
+    owner = githubMatch[1];
+    repo = githubMatch[2];
+    sourceUrl = `https://github.com/${owner}/${repo}`;
+  } else {
+    // owner/repo format
+    const parts = normalized.split("/");
+    if (parts.length < 2) {
+      throw new Error(
+        `Invalid skill reference "${input}". Expected formats:\n` +
+          `  owner/repo@skill-name\n` +
+          `  https://github.com/owner/repo --skill <name>`
+      );
+    }
+    owner = parts[0];
+    repo = parts[1];
+  }
+
+  // Precedence: explicit --skill flag > @skill in string
+  const skill = skillNameOverride ?? skillFromAt;
+
+  return { owner, repo, skill, sourceUrl };
+}
+
+export class SkillsService {
+  private cwd: string;
+  private isGlobal: boolean;
+  private customInstallDir?: string;
+
+  constructor(opts: SkillsServiceOptions = {}) {
+    this.cwd = opts.cwd ?? process.cwd();
+    this.isGlobal = opts.global ?? false;
+    this.customInstallDir = opts.installDir;
+  }
+
+  /** Absolute path to the skills install directory */
+  getInstallDir(): string {
+    if (this.customInstallDir) {
+      return path.isAbsolute(this.customInstallDir)
+        ? this.customInstallDir
+        : path.join(this.cwd, this.customInstallDir);
+    }
+    if (this.isGlobal) {
+      return GLOBAL_SKILLS_DIR;
+    }
+    return path.join(this.cwd, LOCAL_SKILLS_DIR);
+  }
+
+  /** Absolute path to the lock file */
+  getLockPath(): string {
+    if (this.isGlobal) {
+      return GLOBAL_LOCK_FILE;
+    }
+    if (this.customInstallDir) {
+      return path.join(this.getInstallDir(), "skills-lock.json");
+    }
+    // Local: prefer primary, fall back to legacy
+    const primary = path.join(this.cwd, LOCK_FILE_PRIMARY);
+    const legacy = path.join(this.cwd, LOCK_FILE_LEGACY);
+    if (!fs.existsSync(primary) && fs.existsSync(legacy)) {
+      return legacy;
+    }
+    return primary;
+  }
+
+  /** Absolute path to where we always write the lock file */
+  getLockWritePath(): string {
+    if (this.isGlobal) return GLOBAL_LOCK_FILE;
+    if (this.customInstallDir) {
+      return path.join(this.getInstallDir(), "skills-lock.json");
+    }
+    return path.join(this.cwd, LOCK_FILE_PRIMARY);
+  }
+
+  readLock(): SkillsLock {
+    const lockPath = this.getLockPath();
+    try {
+      if (fs.existsSync(lockPath)) {
+        const content = fs.readFileSync(lockPath, "utf-8");
+        const parsed = JSON.parse(content) as SkillsLock;
+        if (typeof parsed.version !== "number" || !parsed.skills) {
+          return createEmptyLock();
+        }
+        return parsed;
+      }
+    } catch {
+      // fall through
+    }
+    return createEmptyLock();
+  }
+
+  writeLock(lock: SkillsLock): void {
+    const lockPath = this.getLockWritePath();
+    const dir = path.dirname(lockPath);
+    fs.mkdirSync(dir, { recursive: true });
+
+    // Sort skills keys for deterministic output
+    const sortedSkills: Record<string, SkillLockEntry> = {};
+    for (const key of Object.keys(lock.skills).sort()) {
+      sortedSkills[key] = lock.skills[key];
+    }
+    const sorted: SkillsLock = { version: lock.version, skills: sortedSkills };
+    fs.writeFileSync(lockPath, JSON.stringify(sorted, null, 2) + "\n", "utf-8");
+  }
+
+  /**
+   * Fetch skill from skills.sh CDN API.
+   */
+  async fetchSkillFromApi(
+    owner: string,
+    repo: string,
+    skill: string
+  ): Promise<SkillDownloadResponse> {
+    const url = `${SKILLS_SH_API}/api/download/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(skill)}`;
+    return fetchJson<SkillDownloadResponse>(url);
+  }
+
+  /**
+   * Install a skill.
+   *
+   * @param skillRef - "owner/repo@skill", "owner/repo", or "https://github.com/owner/repo"
+   * @param skillNameOverride - explicit skill name (from --skill flag), overrides @skill in ref
+   */
+  async add(skillRef: string, skillNameOverride?: string): Promise<void> {
+    const { owner, repo, skill, sourceUrl } = parseSkillRef(skillRef, skillNameOverride);
+    const source = `${owner}/${repo}`;
+
+    if (!skill) {
+      throw new Error(
+        `Please specify a skill name:\n` +
+          `  knowhow skills add ${source}@<skill-name>\n` +
+          `  knowhow skills add https://github.com/${source} --skill <skill-name>`
+      );
+    }
+
+    const installDir = this.getInstallDir();
+    const scope = this.isGlobal ? "globally" : "locally";
+    console.log(`📦 Fetching skill "${skill}" from ${source} (installing ${scope})...`);
+
+    let download: SkillDownloadResponse;
+    try {
+      download = await this.fetchSkillFromApi(owner, repo, skill);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(
+        `Failed to fetch skill "${skill}" from skills.sh API: ${msg}\n` +
+          `Make sure the skill exists at: https://skills.sh/${source}/${skill}`
+      );
+    }
+
+    if (!download.files || download.files.length === 0) {
+      throw new Error(`No files found for skill "${skill}"`);
+    }
+
+    // Write files to install dir
+    const skillInstallDir = path.join(installDir, skill);
+    fs.mkdirSync(skillInstallDir, { recursive: true });
+
+    for (const file of download.files) {
+      const filePath = path.join(skillInstallDir, file.path);
+      const fileDir = path.dirname(filePath);
+      fs.mkdirSync(fileDir, { recursive: true });
+      fs.writeFileSync(filePath, file.contents, "utf-8");
+    }
+
+    // Compute content hash from downloaded files
+    const computedHash = computeSkillApiHash(download.files);
+
+    if (download.hash && download.hash !== computedHash) {
+      console.warn(
+        `⚠ Note: API cached hash (${download.hash}) differs from computed hash (${computedHash}). Storing computed hash.`
+      );
+    }
+
+    const skillPath = `skills/${skill}/SKILL.md`;
+    const commitHash = await fetchLatestCommitHash(owner, repo, skillPath);
+    if (commitHash) {
+      console.log(`📎 Pinned to commit ${commitHash.slice(0, 8)}`);
+    }
+
+    // Update lock
+    const lock = this.readLock();
+    lock.skills[skill] = {
+      source,
+      sourceType: "github",
+      skillPath,
+      computedHash,
+      ...(commitHash ? { commitHash } : {}),
+      ...(sourceUrl ? { sourceUrl } : {}),
+    };
+    this.writeLock(lock);
+
+    console.log(`✅ Installed skill "${skill}" to ${skillInstallDir}`);
+    console.log(`🔒 Updated lock file at ${this.getLockWritePath()}`);
+  }
+
+  /**
+   * Remove a skill by name.
+   */
+  remove(skillName: string): void {
+    const lock = this.readLock();
+
+    if (!lock.skills[skillName]) {
+      console.warn(`⚠ Skill "${skillName}" not found in lock file.`);
+    } else {
+      delete lock.skills[skillName];
+      this.writeLock(lock);
+      console.log(`🗑  Removed "${skillName}" from lock file.`);
+    }
+
+    const installDir = path.join(this.getInstallDir(), skillName);
+    if (fs.existsSync(installDir)) {
+      fs.rmSync(installDir, { recursive: true, force: true });
+      console.log(`🗑  Deleted ${installDir}`);
+    } else {
+      console.warn(`⚠ Skill directory not found: ${installDir}`);
+    }
+  }
+
+  /**
+   * List installed skills from lock file.
+   */
+  list(): void {
+    const lock = this.readLock();
+    const skillEntries = Object.entries(lock.skills);
+
+    if (skillEntries.length === 0) {
+      console.log(
+        "No skills installed. Run `knowhow skills add <owner/repo@skill>` to install one."
+      );
+      return;
+    }
+
+    const installDir = this.getInstallDir();
+    console.log(`Installed skills (${skillEntries.length}):\n`);
+    for (const [name, entry] of skillEntries) {
+      const skillDir = path.join(installDir, name);
+      const installed = fs.existsSync(skillDir);
+      const statusIcon = installed ? "✅" : "❌";
+      console.log(`  ${statusIcon} ${name}`);
+      console.log(`     source: ${entry.source}`);
+      if (entry.skillPath) console.log(`     path:   ${entry.skillPath}`);
+      console.log(`     hash:   ${entry.computedHash}`);
+    }
+  }
+
+  /**
+   * Install all skills from the lock file (restore).
+   */
+  async install(): Promise<void> {
+    const lock = this.readLock();
+    const skillEntries = Object.entries(lock.skills);
+
+    if (skillEntries.length === 0) {
+      console.log("No skills in lock file. Nothing to install.");
+      return;
+    }
+
+    const installDir = this.getInstallDir();
+    console.log(`📦 Installing ${skillEntries.length} skill(s) from lock file...\n`);
+    let installed = 0;
+    let skipped = 0;
+    let failed = 0;
+
+    for (const [name, entry] of skillEntries) {
+      const skillDir = path.join(installDir, name);
+
+      // Check if already installed with correct hash
+      if (fs.existsSync(skillDir)) {
+        const currentHash = computeSkillFolderHash(skillDir);
+        if (currentHash === entry.computedHash) {
+          console.log(`  ⏭  ${name} (already up to date)`);
+          skipped++;
+          continue;
+        }
+      }
+
+      const parts = entry.source.split("/");
+      if (parts.length < 2 || entry.sourceType !== "github") {
+        console.warn(
+          `  ⚠ ${name}: unsupported sourceType "${entry.sourceType}", skipping`
+        );
+        failed++;
+        continue;
+      }
+
+      const [owner, repo] = parts;
+      let skillSlug = name;
+      if (entry.skillPath) {
+        const pathParts = entry.skillPath.split("/");
+        if (pathParts.length >= 2) {
+          skillSlug = pathParts[pathParts.length - 2];
+        }
+      }
+
+      try {
+        console.log(`  📥 Installing ${name}...`);
+        const download = await this.fetchSkillFromApi(owner, repo, skillSlug);
+        const files = download.files;
+
+        fs.mkdirSync(skillDir, { recursive: true });
+        for (const file of files) {
+          const filePath = path.join(skillDir, file.path);
+          fs.mkdirSync(path.dirname(filePath), { recursive: true });
+          fs.writeFileSync(filePath, file.contents, "utf-8");
+        }
+
+        const actualHash = computeSkillApiHash(files);
+        if (actualHash !== entry.computedHash) {
+          console.warn(
+            `     ⚠ Hash mismatch for ${name}: locked ${entry.computedHash.slice(0, 16)}..., got ${actualHash.slice(0, 16)}...`
+          );
+        } else {
+          console.log(`     ✓ Hash verified`);
+        }
+
+        console.log(`  ✅ ${name}`);
+        installed++;
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`  ❌ ${name}: ${msg}`);
+        failed++;
+      }
+    }
+
+    console.log(
+      `\nDone: ${installed} installed, ${skipped} skipped, ${failed} failed.`
+    );
+  }
+
+  /**
+   * Update installed skills to their latest version.
+   */
+  async update(skillNames?: string[]): Promise<void> {
+    const lock = this.readLock();
+    const toUpdate =
+      skillNames && skillNames.length > 0
+        ? skillNames
+        : Object.keys(lock.skills);
+
+    if (toUpdate.length === 0) {
+      console.log("No skills to update.");
+      return;
+    }
+
+    const installDir = this.getInstallDir();
+    console.log(`🔄 Updating ${toUpdate.length} skill(s)...\n`);
+    let updated = 0;
+    let unchanged = 0;
+    let failed = 0;
+
+    for (const name of toUpdate) {
+      const entry = lock.skills[name];
+      if (!entry) {
+        console.warn(`  ⚠ "${name}" not found in lock file, skipping.`);
+        failed++;
+        continue;
+      }
+
+      const parts = entry.source.split("/");
+      if (parts.length < 2 || entry.sourceType !== "github") {
+        console.warn(`  ⚠ ${name}: unsupported sourceType, skipping`);
+        failed++;
+        continue;
+      }
+
+      const [owner, repo] = parts;
+      let skillSlug = name;
+      if (entry.skillPath) {
+        const pathParts = entry.skillPath.split("/");
+        if (pathParts.length >= 2) {
+          skillSlug = pathParts[pathParts.length - 2];
+        }
+      }
+
+      try {
+        const download = await this.fetchSkillFromApi(owner, repo, skillSlug);
+        const newHash = computeSkillApiHash(download.files);
+
+        if (newHash === entry.computedHash) {
+          console.log(`  ⏭  ${name} (already up to date)`);
+          unchanged++;
+          continue;
+        }
+
+        const skillDir = path.join(installDir, name);
+        fs.mkdirSync(skillDir, { recursive: true });
+        for (const file of download.files) {
+          const filePath = path.join(skillDir, file.path);
+          fs.mkdirSync(path.dirname(filePath), { recursive: true });
+          fs.writeFileSync(filePath, file.contents, "utf-8");
+        }
+
+        lock.skills[name] = { ...entry, computedHash: newHash };
+        console.log(`  ✅ ${name} (updated)`);
+        updated++;
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`  ❌ ${name}: ${msg}`);
+        failed++;
+      }
+    }
+
+    if (updated > 0) {
+      this.writeLock(lock);
+    }
+
+    console.log(
+      `\nDone: ${updated} updated, ${unchanged} unchanged, ${failed} failed.`
+    );
+  }
+}

package/src/services/Tools.ts

@@ -14,6 +14,7 @@ import {
 } from "./types";
 import { PluginService } from "../plugins/plugins";
 import { McpService } from "./Mcp";
+import { BehaviorsService } from "./BehaviorsService";
 
 export interface ToolContext {
   Agents?: AgentService;
@@ -22,6 +23,7 @@ export interface ToolContext {
   Tools?: ToolsService;
   Plugins?: PluginService;
   Mcp?: McpService;
+  Behaviors?: BehaviorsService;
   metadata?: { [key: string]: any };
 }
 

package/src/services/index.ts

@@ -7,13 +7,14 @@ import { KnowhowSimpleClient } from "./KnowhowClient";
 import { McpService } from "./Mcp";
 import { S3Service } from "./S3";
 import { ToolsService } from "./Tools";
-import { PluginService } from "../plugins/plugins";
+import { CliPluginService, PluginService } from "../plugins/plugins";
 import { DockerService } from "./DockerService";
 import { AgentSyncKnowhowWeb } from "./AgentSyncKnowhowWeb";
 import { AgentSyncFs } from "./AgentSyncFs";
 import { SessionManager } from "./SessionManager";
 import { TaskRegistry } from "./TaskRegistry";
 import { MediaProcessorService } from "./MediaProcessorService";
+import { BehaviorsService } from "./BehaviorsService";
 
 import { ConversionService } from "./conversion/ConversionService";
 
@@ -38,6 +39,7 @@ export * from "./SyncerService";
 export * from "./watchers";
 export { Clients } from "../clients";
 export * from "./conversion";
+export { BehaviorsService } from "./BehaviorsService";
 
 let Singletons = {} as {
   Tools: ToolsService;
@@ -53,6 +55,7 @@ let Singletons = {} as {
   Clients: AIClient;
   MediaProcessor: MediaProcessorService;
   Conversion: ConversionService;
+  Behaviors: BehaviorsService;
 };
 
 export const services = (): typeof Singletons => {
@@ -61,8 +64,9 @@ export const services = (): typeof Singletons => {
     const Events = new EventService();
     const Agents = new AgentService(Tools, Events);
     const MediaProcessor = new MediaProcessorService(Clients);
+    const Behaviors = new BehaviorsService();
     const Conversion = new ConversionService(Clients, MediaProcessor);
-    const Plugins = new PluginService({
+    const Plugins = new CliPluginService({
       Agents,
       Events,
       Tools,
@@ -83,6 +87,7 @@ export const services = (): typeof Singletons => {
       Plugins,
       Tools,
       knowhowApiClient: new KnowhowSimpleClient(),
+      Behaviors,
     };
 
     Singletons.Tools.setContext({
@@ -90,6 +95,7 @@ export const services = (): typeof Singletons => {
       Events,
       Plugins,
       Clients,
+      Behaviors,
     });
   }
 

package/src/services/modules/types.ts

@@ -13,6 +13,7 @@ import { MediaProcessorService } from "../MediaProcessorService";
 import { TunnelHandler } from "@tyvm/knowhow-tunnel";
 import { EventService } from "../EventService";
 import { ConversionService } from "../conversion/ConversionService";
+import { BehaviorsService } from "../BehaviorsService";
 
 /*
  *
@@ -61,6 +62,7 @@ export interface ModuleContext {
   Conversion?: ConversionService;
   Tunnel?: TunnelHandler;
   Program?: Command;
+  Behaviors?: BehaviorsService
 }
 
 export interface KnowhowModule {