@anaclumos/taal 1.1.2

package/src/skills/discovery.ts

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { validateSkill } from "./validator.js";
+
+/**
+ * Represents a discovered skill
+ */
+export interface Skill {
+  name: string;
+  path: string;
+  skillMdPath: string;
+}
+
+/**
+ * Expand ~ to home directory in a path
+ */
+function expandPath(path: string, home: string): string {
+  if (path.startsWith("~/")) {
+    return join(home, path.slice(2));
+  }
+  if (path === "~") {
+    return home;
+  }
+  return path;
+}
+
+/**
+ * Discover all valid skills from given paths
+ *
+ * @param paths - Array of paths to search for skills
+ * @param baseDir - Optional base directory for ~ expansion (defaults to homedir())
+ * @returns Array of discovered skills
+ */
+export function discoverSkills(paths: string[], baseDir?: string): Skill[] {
+  const skills: Skill[] = [];
+  const home = baseDir || homedir();
+
+  for (const rawPath of paths) {
+    const basePath = expandPath(rawPath, home);
+    if (!existsSync(basePath)) {
+      console.warn(`Skills path does not exist: ${basePath}`);
+      continue;
+    }
+
+    try {
+      const entries = readdirSync(basePath).sort();
+
+      for (const entry of entries) {
+        const skillPath = join(basePath, entry);
+
+        // Skip if not a directory
+        try {
+          const stat = statSync(skillPath);
+          if (!stat.isDirectory()) {
+            continue;
+          }
+        } catch {
+          continue;
+        }
+
+        // Check if SKILL.md exists
+        const skillMdPath = join(skillPath, "SKILL.md");
+        if (!existsSync(skillMdPath)) {
+          continue;
+        }
+
+        // Validate skill
+        const validation = validateSkill(skillPath);
+        if (!validation.valid) {
+          console.warn(`Invalid skill at ${skillPath}: ${validation.error}`);
+          continue;
+        }
+
+        skills.push({
+          name: validation.name!,
+          path: skillPath,
+          skillMdPath,
+        });
+      }
+    } catch (error) {
+      console.warn(`Failed to read skills directory ${basePath}: ${error}`);
+    }
+  }
+
+  return skills;
+}

package/src/skills/validator.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+interface SkillFrontmatter {
+  name?: string;
+  description?: string;
+  version?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  name?: string;
+}
+
+/**
+ * Validate a skill directory
+ * Checks that SKILL.md exists and has valid YAML frontmatter with 'name' field
+ *
+ * @param skillPath - Path to the skill directory
+ * @returns Validation result
+ */
+export function validateSkill(skillPath: string): ValidationResult {
+  const skillMdPath = join(skillPath, "SKILL.md");
+
+  // Check if SKILL.md exists
+  if (!existsSync(skillMdPath)) {
+    return {
+      valid: false,
+      error: "SKILL.md not found",
+    };
+  }
+
+  // Read file content
+  let content: string;
+  try {
+    content = readFileSync(skillMdPath, "utf-8");
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Failed to read SKILL.md: ${error}`,
+    };
+  }
+
+  // Check for YAML frontmatter
+  if (!content.startsWith("---\n")) {
+    return {
+      valid: false,
+      error: "SKILL.md must start with YAML frontmatter (---)",
+    };
+  }
+
+  // Extract frontmatter
+  const frontmatterEnd = content.indexOf("\n---\n", 4);
+  if (frontmatterEnd === -1) {
+    return {
+      valid: false,
+      error: "SKILL.md frontmatter not properly closed (missing closing ---)",
+    };
+  }
+
+  const frontmatterContent = content.substring(4, frontmatterEnd);
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(frontmatterContent);
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Invalid YAML frontmatter: ${error}`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    return {
+      valid: false,
+      error: "Frontmatter must be a YAML object",
+    };
+  }
+
+  const frontmatter = parsed as SkillFrontmatter;
+
+  if (!frontmatter.name || typeof frontmatter.name !== "string") {
+    return {
+      valid: false,
+      error: 'Frontmatter must contain a "name" field (string)',
+    };
+  }
+
+  return {
+    valid: true,
+    name: frontmatter.name,
+  };
+}

package/src/utils/atomic-write.ts

@@ -0,0 +1,35 @@
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Atomically writes content to a file using temp file + rename strategy
+ * This ensures the file is never in a partially written state
+ *
+ * @param filePath - Target file path
+ * @param content - Content to write (string or Buffer)
+ * @throws Error if write or rename fails
+ */
+export function atomicWrite(filePath: string, content: string | Buffer): void {
+  // Ensure parent directory exists
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+
+  // Create temp file in same directory (ensures same filesystem for atomic rename)
+  const tempPath = join(dir, `.${Date.now()}.tmp`);
+
+  try {
+    // Write to temp file
+    writeFileSync(tempPath, content, "utf-8");
+
+    // Atomic rename (overwrites target if exists)
+    renameSync(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file if it exists
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw new Error(`Atomic write failed for ${filePath}: ${error}`);
+  }
+}

package/src/utils/backup.ts

@@ -0,0 +1,27 @@
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+export function backupConfig(
+  filePath: string,
+  baseDir?: string
+): string | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  const home = baseDir || homedir();
+  const backupDir = join(home, ".taal", "backups");
+  mkdirSync(backupDir, { recursive: true });
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = basename(filePath);
+  const backupPath = join(backupDir, `${filename}.${timestamp}.backup`);
+
+  try {
+    copyFileSync(filePath, backupPath);
+    return backupPath;
+  } catch (error) {
+    throw new Error(`Failed to backup ${filePath}: ${error}`);
+  }
+}

package/taal.schema.json

@@ -0,0 +1,91 @@
+{
+  "$ref": "#/definitions/TaalConfig",
+  "definitions": {
+    "TaalConfig": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "const": "1"
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "env": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "url": {
+                "type": "string"
+              },
+              "headers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "overrides": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "enabled_tools": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "skills": {
+          "type": "object",
+          "properties": {
+            "paths": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": ["paths"],
+          "additionalProperties": false
+        },
+        "providers": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": ["enabled"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["version"],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}