mulmoclaude 0.1.0

package/server/workspace/skills/discovery.ts

@@ -0,0 +1,125 @@
+// Scan the user's ~/.claude/skills/ and the workspace-level
+// <workspace>/.claude/skills/ for SKILL.md files, parse them, and
+// produce a deduped list. Project-level skills override user-level
+// skills with the same name (mirrors settings precedence in #197).
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { log } from "../../system/logger/index.js";
+import { parseSkillFrontmatter } from "./parser.js";
+import { SKILL_FILE, USER_SKILLS_DIR, projectSkillsDir } from "./paths.js";
+import type { Skill, SkillSource } from "./types.js";
+
+// One directory entry → a parsed Skill, or null when the entry is
+// not a valid skill (no SKILL.md, malformed frontmatter, I/O error).
+// Errors are logged at warn, not thrown — a single broken skill
+// shouldn't take down the whole list.
+async function readSkillDir(skillDir: string, name: string, source: SkillSource): Promise<Skill | null> {
+  const skillPath = join(skillDir, SKILL_FILE);
+  try {
+    // Follow symlinks: stat rather than lstat so a user's
+    // `pptx@ → ~/ss/llm/skills/pptx/` reads through the link.
+    const fileStat = await stat(skillPath);
+    if (!fileStat.isFile()) return null;
+    const raw = await readFile(skillPath, "utf-8");
+    const parsed = parseSkillFrontmatter(raw);
+    if (!parsed) {
+      log.warn("skills", "SKILL.md has no usable frontmatter, skipping", {
+        name,
+        path: skillPath,
+      });
+      return null;
+    }
+    return {
+      name,
+      description: parsed.description,
+      body: parsed.body,
+      source,
+      path: skillPath,
+    };
+  } catch (err) {
+    // ENOENT = SKILL.md missing. Anything else is logged so a
+    // permissions issue is findable; we still treat the slot as
+    // "not a skill" rather than failing the whole list.
+    const error = err as { code?: string };
+    if (error.code !== "ENOENT") {
+      log.warn("skills", "failed to read SKILL.md, skipping", {
+        name,
+        path: skillPath,
+        error: String(err),
+      });
+    }
+    return null;
+  }
+}
+
+/**
+ * Scan one skills root (either the user or project location) and
+ * return every valid Skill. The root itself is allowed to not exist
+ * — we just return an empty list (a workspace with no .claude/skills/
+ * is the common case).
+ */
+export async function collectSkillsFromDir(root: string, source: SkillSource): Promise<Skill[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch (err) {
+    const error = err as { code?: string };
+    if (error.code === "ENOENT") return [];
+    log.warn("skills", "failed to list skills dir, returning empty", {
+      root,
+      error: String(err),
+    });
+    return [];
+  }
+
+  const results: Skill[] = [];
+  for (const name of entries) {
+    // Skip hidden entries (.DS_Store, .gitkeep, etc.) up front.
+    if (name.startsWith(".")) continue;
+    const skillDir = resolve(root, name);
+    let dirStat;
+    try {
+      // stat follows symlinks — supports `ln -s target skills/name`.
+      dirStat = await stat(skillDir);
+    } catch {
+      continue;
+    }
+    if (!dirStat.isDirectory()) continue;
+    const skill = await readSkillDir(skillDir, name, source);
+    if (skill) results.push(skill);
+  }
+  // Stable alphabetical order for the UI.
+  results.sort((a, b) => a.name.localeCompare(b.name));
+  return results;
+}
+
+export interface DiscoverSkillsOptions {
+  /** Absolute path to the user's ~/.claude/skills/. Overridable for
+   *  tests that point at mkdtempSync trees. */
+  userDir?: string;
+  /** Workspace root; project-level skills live at
+   *  `<workspaceRoot>/.claude/skills/`. Passing undefined skips the
+   *  project scope entirely. */
+  workspaceRoot?: string;
+}
+
+/**
+ * Discover every skill available to this workspace. Project-level
+ * skills (under `<workspace>/.claude/skills/`) override user-level
+ * skills of the same name.
+ */
+export async function discoverSkills(opts: DiscoverSkillsOptions = {}): Promise<Skill[]> {
+  const userDir = opts.userDir ?? USER_SKILLS_DIR;
+  const userSkills = await collectSkillsFromDir(userDir, "user");
+
+  const projectSkills = opts.workspaceRoot ? await collectSkillsFromDir(projectSkillsDir(opts.workspaceRoot), "project") : [];
+
+  // Project overrides user on name collision. Merge by building a
+  // map keyed by name, starting with user, overwriting with project.
+  const merged = new Map<string, Skill>();
+  for (const s of userSkills) merged.set(s.name, s);
+  for (const s of projectSkills) merged.set(s.name, s);
+
+  return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/server/workspace/skills/index.ts

@@ -0,0 +1,10 @@
+// Public API for the skills module. Discovery (read-only) is phase
+// 0; save + delete (project scope only) is phase 1.
+
+export { discoverSkills, collectSkillsFromDir } from "./discovery.js";
+export { parseSkillFrontmatter } from "./parser.js";
+export { saveProjectSkill, updateProjectSkill, deleteProjectSkill } from "./writer.js";
+export type { SaveResult, UpdateResult, DeleteResult } from "./writer.js";
+export { isValidSlug } from "../../utils/slug.js";
+export { projectSkillsDir, projectSkillPath, projectSkillDir } from "./paths.js";
+export type { Skill, SkillSource, SkillSummary } from "./types.js";

package/server/workspace/skills/parser.ts

@@ -0,0 +1,144 @@
+// Pure SKILL.md parser. Given the raw file content, return the
+// `description` (from YAML frontmatter) + body, plus optional
+// `schedule` and `roleId` for auto-scheduling (#357 Phase 2).
+//
+// Minimal YAML: we only care about a few keys, so rather than
+// pulling in a YAML parser we do line-by-line extraction.
+
+import { TIME_UNIT_MS, ONE_SECOND_MS } from "../../utils/time.js";
+import { SCHEDULE_TYPES } from "@receptron/task-scheduler";
+
+export interface SkillSchedule {
+  /** "daily HH:MM" or "interval Ns/Nm/Nh" */
+  raw: string;
+  /** Parsed into task-manager-compatible shape */
+  parsed: { type: typeof SCHEDULE_TYPES.daily; time: string } | { type: typeof SCHEDULE_TYPES.interval; intervalMs: number } | null;
+}
+
+export interface ParsedSkill {
+  description: string;
+  body: string;
+  /** If present, this skill should be auto-scheduled */
+  schedule?: SkillSchedule;
+  /** Role to use when running the scheduled skill (default: "general") */
+  roleId?: string;
+}
+
+// Match a YAML scalar value on a single line:
+//   description: Enable CI for a repository
+//   description: "Quoted with colons: inside"
+// Leading/trailing whitespace trimmed. Quoted values have their
+// outer quotes stripped but inner JSON-style escapes are NOT
+// reversed — SKILL.md descriptions in the wild are plain text.
+function parseScalar(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return "";
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * Parse schedule value from frontmatter.
+ * Supported formats:
+ *   "daily HH:MM"      → { type: "daily", time: "HH:MM" }
+ *   "interval 30m"     → { type: "interval", intervalMs: 1800000 }
+ *   "interval 2h"      → { type: "interval", intervalMs: 7200000 }
+ *   "interval 300s"    → { type: "interval", intervalMs: 300000 }
+ */
+// Minimum interval to prevent accidental runaway scheduling.
+const MIN_INTERVAL_MS = 10 * ONE_SECOND_MS;
+
+function parseScheduleValue(raw: string): SkillSchedule["parsed"] {
+  const trimmed = raw.trim();
+
+  // daily HH:MM — validate range: HH 00-23, MM 00-59
+  const dailyMatch = trimmed.match(/^daily\s+(\d{2}):(\d{2})$/);
+  if (dailyMatch) {
+    const hh = Number(dailyMatch[1]);
+    const mm = Number(dailyMatch[2]);
+    if (hh > 23 || mm > 59) return null;
+    return {
+      type: SCHEDULE_TYPES.daily,
+      time: `${dailyMatch[1]}:${dailyMatch[2]}`,
+    };
+  }
+
+  // interval Ns / Nm / Nh — must be >= MIN_INTERVAL_MS
+  const intervalMatch = trimmed.match(/^interval\s+(\d+)([smh])$/);
+  if (intervalMatch) {
+    const value = Number(intervalMatch[1]);
+    const unit = intervalMatch[2];
+    const ms = TIME_UNIT_MS[unit];
+    if (!ms) return null;
+    const intervalMs = value * ms;
+    if (intervalMs < MIN_INTERVAL_MS) return null;
+    return { type: SCHEDULE_TYPES.interval, intervalMs };
+  }
+
+  return null;
+}
+
+/**
+ * Parse a SKILL.md file. Returns null when:
+ *  - the file has no frontmatter (no leading `---` fence)
+ *  - the frontmatter is unterminated
+ *  - there is no `description:` key
+ *
+ * An empty body is allowed (the skill may be just metadata for now).
+ */
+// Extract key-value pairs from YAML frontmatter lines. Returns a
+// map of key → scalar value. Keeps parseSkillFrontmatter under the
+// cognitive-complexity threshold.
+function extractFrontmatterFields(lines: string[], startIdx: number, endIdx: number): Map<string, string> {
+  const fields = new Map<string, string>();
+  for (let i = startIdx; i < endIdx; i++) {
+    const line = lines[i];
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = parseScalar(line.slice(colonIdx + 1));
+    fields.set(key, value);
+  }
+  return fields;
+}
+
+export function parseSkillFrontmatter(raw: string): ParsedSkill | null {
+  const lines = raw.split(/\r?\n/);
+  if (lines.length === 0 || lines[0].trim() !== "---") return null;
+
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx === -1) return null;
+
+  const fields = extractFrontmatterFields(lines, 1, closeIdx);
+  const description = fields.get("description") ?? null;
+  if (description === null) return null;
+
+  const scheduleRaw = fields.get("schedule") ?? null;
+  const roleId = fields.get("roleId") ?? null;
+
+  // Body starts after the closing fence. Trim leading blank lines so
+  // the UI doesn't render an awkward gap above the first heading.
+  const body = lines
+    .slice(closeIdx + 1)
+    .join("\n")
+    .replace(/^(?:\s*\n)+/, "")
+    .trimEnd();
+
+  const result: ParsedSkill = { description, body };
+  if (scheduleRaw) {
+    result.schedule = {
+      raw: scheduleRaw,
+      parsed: parseScheduleValue(scheduleRaw),
+    };
+  }
+  if (roleId) result.roleId = roleId;
+  return result;
+}

package/server/workspace/skills/paths.ts

@@ -0,0 +1,41 @@
+// Path helpers and slug validation for the skills module.
+//
+// Skills live in two scopes:
+//   - user:    ~/.claude/skills/<slug>/SKILL.md        (read-only from MulmoClaude)
+//   - project: <workspaceRoot>/.claude/skills/<slug>/SKILL.md  (MulmoClaude can CRUD)
+//
+// The slug doubles as a filename and appears in Claude CLI slash
+// commands (`/<slug>`), so it has to be strict: no uppercase, no
+// spaces, no path separators, no leading/trailing hyphens, 1-64
+// chars. Same rule as `server/sources/paths.ts#isValidSlug` — keep
+// them in sync manually.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SKILL_FILE = "SKILL.md";
+
+/** `~/.claude/skills/` — user scope, read-only from MulmoClaude. */
+export const USER_SKILLS_DIR = join(homedir(), ".claude", "skills");
+
+/** `<workspaceRoot>/.claude/skills/` — project scope, writable. */
+export function projectSkillsDir(workspaceRoot: string): string {
+  return join(workspaceRoot, ".claude", "skills");
+}
+
+/** Full path to the project-scope SKILL.md for a given slug. */
+export function projectSkillPath(workspaceRoot: string, slug: string): string {
+  return join(projectSkillsDir(workspaceRoot), slug, SKILL_FILE);
+}
+
+/** Directory holding a project skill (one level above SKILL.md). */
+export function projectSkillDir(workspaceRoot: string, slug: string): string {
+  return join(projectSkillsDir(workspaceRoot), slug);
+}
+
+/**
+ * Strict slug validator. Rejects anything that could surprise the
+ * filesystem, the Claude CLI slash-command resolver, or the URL
+ * parser. Single source of truth for `save` / `delete` input.
+ */
+// isValidSlug moved to server/utils/slug.ts — import from there.

package/server/workspace/skills/scheduler.ts

@@ -0,0 +1,149 @@
+// Skill scheduling (#357 Phase 2). Scans all discovered skills for
+// `schedule:` frontmatter and registers matching ones with the
+// task-manager. Each scheduled skill fires `startChat()` with the
+// skill body as the message and the skill's `roleId` (or "general").
+//
+// `refreshScheduledSkills()` can be called at any time to re-scan
+// and update registrations (e.g. after a skill is saved/deleted
+// via the API). It unregisters stale tasks and registers new ones.
+
+import { discoverSkills } from "./discovery.js";
+import type { Skill } from "./types.js";
+import type { ITaskManager, TaskSchedule } from "../../events/task-manager/index.js";
+import { parseSkillFrontmatter } from "./parser.js";
+import { log } from "../../system/logger/index.js";
+import { readFileSync } from "fs";
+import { DEFAULT_ROLE_ID } from "../../../src/config/roles.js";
+import { SESSION_ORIGINS, type SessionOrigin } from "../../../src/types/session.js";
+
+interface SkillScheduleInfo {
+  schedule: TaskSchedule;
+  roleId: string;
+}
+
+interface StartChatResult {
+  kind: string;
+  error?: string;
+  status?: number;
+}
+
+export interface SkillSchedulerDeps {
+  taskManager: ITaskManager;
+  workspaceRoot: string;
+  startChat: (params: { message: string; roleId: string; chatSessionId: string; origin?: SessionOrigin }) => Promise<StartChatResult>;
+}
+
+const SKILL_TASK_PREFIX = "skill.";
+
+// Track registered skill task IDs so refresh can unregister stale ones.
+let registeredTaskIds = new Set<string>();
+let cachedDeps: SkillSchedulerDeps | null = null;
+
+// Mutex: serialize refresh calls so concurrent save/update/delete
+// API calls don't interleave register/unregister and corrupt state.
+let refreshMutex: Promise<number> = Promise.resolve(0);
+
+export async function registerScheduledSkills(deps: SkillSchedulerDeps): Promise<number> {
+  cachedDeps = deps;
+  return serializedRefresh(deps);
+}
+
+/**
+ * Re-scan skills and update task-manager registrations. Safe to call
+ * after a skill is saved, updated, or deleted — removes stale tasks
+ * and adds new ones without a server restart. Serialized: concurrent
+ * calls queue behind the in-flight one.
+ */
+export async function refreshScheduledSkills(): Promise<number> {
+  if (!cachedDeps) {
+    log.warn("skills", "refreshScheduledSkills called before initial register");
+    return 0;
+  }
+  return serializedRefresh(cachedDeps);
+}
+
+function serializedRefresh(deps: SkillSchedulerDeps): Promise<number> {
+  refreshMutex = refreshMutex.then(
+    () => doRegister(deps),
+    () => doRegister(deps),
+  );
+  return refreshMutex;
+}
+
+async function doRegister(deps: SkillSchedulerDeps): Promise<number> {
+  const { taskManager, workspaceRoot, startChat } = deps;
+
+  // Unregister all previously registered skill tasks
+  for (const taskId of registeredTaskIds) {
+    taskManager.removeTask(taskId);
+  }
+  const previousCount = registeredTaskIds.size;
+  registeredTaskIds = new Set<string>();
+
+  const skills = await discoverSkills({ workspaceRoot });
+  let registered = 0;
+
+  for (const skill of skills) {
+    const info = readSkillScheduleInfo(skill);
+    if (!info) continue;
+
+    const { schedule, roleId } = info;
+    const taskId = `${SKILL_TASK_PREFIX}${skill.name}`;
+
+    taskManager.registerTask({
+      id: taskId,
+      description: `Scheduled skill: ${skill.name} — ${skill.description}`,
+      schedule,
+      run: async () => {
+        const chatSessionId = crypto.randomUUID();
+        log.info("skills", "running scheduled skill", {
+          name: skill.name,
+          roleId,
+          chatSessionId,
+        });
+        const result = await startChat({
+          message: `/${skill.name}`,
+          roleId,
+          chatSessionId,
+          origin: SESSION_ORIGINS.skill,
+        });
+        if (result.kind === "error") {
+          throw new Error(`scheduled skill failed: ${result.error ?? "unknown"}`);
+        }
+        log.info("skills", "scheduled skill completed", {
+          name: skill.name,
+          kind: result.kind,
+        });
+      },
+    });
+
+    registeredTaskIds.add(taskId);
+    registered++;
+  }
+
+  if (previousCount > 0 || registered > 0) {
+    log.info("skills", "skill schedules refreshed", {
+      previous: previousCount,
+      current: registered,
+    });
+  }
+
+  return registered;
+}
+
+// Read schedule + roleId in one file read (avoid reading the same
+// SKILL.md twice). Returns null if no schedule is configured.
+function readSkillScheduleInfo(skill: Skill): SkillScheduleInfo | null {
+  try {
+    const raw = readFileSync(skill.path, "utf-8");
+    const parsed = parseSkillFrontmatter(raw);
+    const s = parsed?.schedule?.parsed;
+    if (!s) return null;
+    return {
+      schedule: s,
+      roleId: parsed?.roleId ?? DEFAULT_ROLE_ID,
+    };
+  } catch {
+    return null;
+  }
+}

package/server/workspace/skills/types.ts

@@ -0,0 +1,30 @@
+// Shared Skill type. A Skill is the parsed content of one
+// ~/.claude/skills/<name>/SKILL.md file (or the project-level
+// equivalent under <workspace>/.claude/skills/<name>/SKILL.md).
+//
+// Phase 0 is read-only: the server discovers and exposes skills
+// but never writes to them. Edits happen through the user's file
+// system or other tooling (e.g. their own skills repo).
+
+export type SkillSource = "user" | "project";
+
+export interface Skill {
+  /** Directory name under skills/, e.g. "ci_enable". */
+  name: string;
+  /** The `description` field from YAML frontmatter. Used as the
+   *  one-line summary in the UI list. */
+  description: string;
+  /** Markdown body after the frontmatter. Passed to Claude when the
+   *  user clicks "Run". */
+  body: string;
+  /** Which scope this skill was discovered in. Project overrides user
+   *  when names collide. */
+  source: SkillSource;
+  /** Absolute path to the SKILL.md file (post-symlink resolve). Used
+   *  to surface the origin in the detail view. */
+  path: string;
+}
+
+/** Lightweight summary for list endpoints — omits the full body so
+ *  GET /api/skills stays small even with many skills. */
+export type SkillSummary = Pick<Skill, "name" | "description" | "source">;