@stackmemoryai/stackmemory 1.8.1 → 1.10.2

package/dist/src/cli/commands/skill.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    throw new Error("No YAML frontmatter found (expected --- delimiters)");
+  }
+  const yamlBlock = match[1];
+  const body = match[2];
+  const fm = {};
+  let currentKey = null;
+  let currentArray = null;
+  for (const line of yamlBlock.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("- ") && currentKey && currentArray !== null) {
+      currentArray.push(trimmed.slice(2).trim());
+      continue;
+    }
+    if (currentKey && currentArray !== null) {
+      fm[currentKey] = currentArray;
+      currentArray = null;
+      currentKey = null;
+    }
+    const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    const val = kvMatch[2].trim();
+    if (val === "" || val === "[]") {
+      currentKey = key;
+      currentArray = [];
+    } else if (val.startsWith("[") && val.endsWith("]")) {
+      fm[key] = val.slice(1, -1).split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
+    } else {
+      fm[key] = val.replace(/^['"]|['"]$/g, "");
+    }
+  }
+  if (currentKey && currentArray !== null) {
+    fm[currentKey] = currentArray;
+  }
+  return {
+    frontmatter: {
+      name: fm["name"] || "unknown",
+      version: fm["version"] || "0.0.0",
+      domain: fm["domain"] || "general",
+      expires: fm["expires"] || "",
+      activates_on: fm["activates_on"] || [],
+      sources: fm["sources"] || [],
+      context7: fm["context7"]
+    },
+    body
+  };
+}
+function getSkillDirs() {
+  const dirs = [];
+  const globalDir = path.join(os.homedir(), ".claude", "skills", "knowledge");
+  if (fs.existsSync(globalDir)) {
+    dirs.push({ dir: globalDir, scope: "global" });
+  }
+  const projectDir = path.join(process.cwd(), ".claude", "skills", "knowledge");
+  if (fs.existsSync(projectDir)) {
+    dirs.push({ dir: projectDir, scope: "project" });
+  }
+  return dirs;
+}
+function discoverSkills() {
+  const skills = [];
+  const now = /* @__PURE__ */ new Date();
+  for (const { dir, scope } of getSkillDirs()) {
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith(".skill.md"));
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { frontmatter, body } = parseFrontmatter(content);
+        const stale = frontmatter.expires ? new Date(frontmatter.expires) < now : false;
+        skills.push({ path: filePath, scope, frontmatter, body, stale });
+      } catch {
+      }
+    }
+  }
+  return skills;
+}
+function matchSkills(prompt, skills) {
+  const words = new Set(prompt.toLowerCase().split(/\s+/));
+  const results = [];
+  for (const skill of skills) {
+    const matched = [];
+    for (const keyword of skill.frontmatter.activates_on) {
+      const kw = keyword.toLowerCase();
+      if (words.has(kw) || prompt.toLowerCase().includes(kw)) {
+        matched.push(keyword);
+      }
+    }
+    if (matched.length > 0) {
+      const ratio = matched.length / skill.frontmatter.activates_on.length;
+      const scopeBoost = skill.scope === "project" ? 0.1 : 0;
+      const stalepenalty = skill.stale ? -0.2 : 0;
+      results.push({
+        skill,
+        score: Math.min(1, ratio + scopeBoost + stalepenalty),
+        matchedKeywords: matched
+      });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score);
+}
+function createSkillCommand() {
+  const cmd = new Command("skill").description(
+    "Manage knowledge skills (.skill.md) \u2014 domain expertise for AI agents"
+  );
+  cmd.command("list").description("List all discovered knowledge skills").option("--stale", "Show only stale (expired) skills").option("--json", "Output as JSON").action((options) => {
+    let skills = discoverSkills();
+    if (options.stale) {
+      skills = skills.filter((s) => s.stale);
+    }
+    if (options.json) {
+      const out = skills.map((s) => ({
+        name: s.frontmatter.name,
+        domain: s.frontmatter.domain,
+        version: s.frontmatter.version,
+        scope: s.scope,
+        expires: s.frontmatter.expires,
+        stale: s.stale,
+        keywords: s.frontmatter.activates_on.length,
+        path: s.path
+      }));
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+    if (skills.length === 0) {
+      console.log(chalk.yellow("No knowledge skills found."));
+      console.log(`  Global: ~/.claude/skills/knowledge/*.skill.md`);
+      console.log(`  Project: .claude/skills/knowledge/*.skill.md`);
+      return;
+    }
+    console.log(chalk.bold(`
+  Knowledge Skills (${skills.length})
+`));
+    for (const s of skills) {
+      const status = s.stale ? chalk.red("expired") : chalk.green("active");
+      const scope = s.scope === "global" ? chalk.dim("global") : chalk.cyan("project");
+      const keywords = chalk.dim(
+        `[${s.frontmatter.activates_on.slice(0, 5).join(", ")}${s.frontmatter.activates_on.length > 5 ? "..." : ""}]`
+      );
+      console.log(
+        `  ${chalk.bold(s.frontmatter.name.padEnd(20))} ${s.frontmatter.domain.padEnd(12)} ${s.frontmatter.version.padEnd(14)} ${scope.padEnd(18)} ${status}  ${keywords}`
+      );
+    }
+    const staleCount = skills.filter((s) => s.stale).length;
+    if (staleCount > 0) {
+      console.log(
+        chalk.yellow(
+          `
+  ${staleCount} skill(s) expired \u2014 run ${chalk.bold("stackmemory skill refresh")} to update`
+        )
+      );
+    }
+    console.log();
+  });
+  cmd.command("match <prompt>").description("Find skills matching a prompt (keyword match)").option("-n, --limit <n>", "Max results", "5").option("--json", "Output as JSON").action((prompt, options) => {
+    const skills = discoverSkills();
+    const matches = matchSkills(prompt, skills).slice(
+      0,
+      parseInt(options.limit, 10)
+    );
+    if (options.json) {
+      const out = matches.map((m) => ({
+        name: m.skill.frontmatter.name,
+        domain: m.skill.frontmatter.domain,
+        score: Math.round(m.score * 100),
+        stale: m.skill.stale,
+        matchedKeywords: m.matchedKeywords,
+        path: m.skill.path
+      }));
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+    if (matches.length === 0) {
+      console.log(chalk.yellow(`No skills match: "${prompt}"`));
+      return;
+    }
+    console.log(chalk.bold(`
+  Matches for: "${prompt}"
+`));
+    for (const m of matches) {
+      const pct = Math.round(m.score * 100);
+      const bar = pct >= 50 ? chalk.green(`${pct}%`) : chalk.yellow(`${pct}%`);
+      const staleTag = m.skill.stale ? chalk.red(" [stale]") : "";
+      console.log(
+        `  ${bar.padEnd(16)} ${chalk.bold(m.skill.frontmatter.name.padEnd(20))} ${chalk.dim(m.matchedKeywords.join(", "))}${staleTag}`
+      );
+    }
+    console.log();
+  });
+  cmd.command("show <name>").description("Display a skill's full content").action((name) => {
+    const skills = discoverSkills();
+    const skill = skills.find((s) => s.frontmatter.name === name);
+    if (!skill) {
+      console.error(chalk.red(`Skill not found: ${name}`));
+      console.log(
+        `Available: ${skills.map((s) => s.frontmatter.name).join(", ")}`
+      );
+      process.exit(1);
+    }
+    const status = skill.stale ? chalk.red("EXPIRED") : chalk.green("active");
+    console.log(
+      chalk.bold(`
+  ${skill.frontmatter.name}`) + ` (${skill.frontmatter.domain}) ${status}`
+    );
+    console.log(
+      chalk.dim(
+        `  v${skill.frontmatter.version} | expires ${skill.frontmatter.expires} | ${skill.scope}`
+      )
+    );
+    console.log(chalk.dim(`  ${skill.path}`));
+    if (skill.frontmatter.context7) {
+      console.log(chalk.dim(`  context7: ${skill.frontmatter.context7}`));
+    }
+    console.log(
+      chalk.dim(`  keywords: ${skill.frontmatter.activates_on.join(", ")}`)
+    );
+    console.log(chalk.dim(`  sources:`));
+    for (const src of skill.frontmatter.sources) {
+      console.log(chalk.dim(`    - ${src}`));
+    }
+    console.log();
+    console.log(skill.body);
+  });
+  cmd.command("add <source>").description("Add a knowledge skill from a local file or URL").option(
+    "--global",
+    "Install to ~/.claude/skills/knowledge/ (default: project)"
+  ).option("--name <name>", "Override skill name").action(
+    async (source, options) => {
+      let content = "";
+      if (source.startsWith("http://") || source.startsWith("https://")) {
+        try {
+          const res = await fetch(source);
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          content = await res.text();
+        } catch (err) {
+          console.error(chalk.red(`Failed to fetch: ${source}`));
+          console.error(err.message);
+          process.exit(1);
+          return;
+        }
+      } else {
+        const resolved = path.resolve(source);
+        if (!fs.existsSync(resolved)) {
+          console.error(chalk.red(`File not found: ${resolved}`));
+          process.exit(1);
+          return;
+        }
+        content = fs.readFileSync(resolved, "utf-8");
+      }
+      let parsed;
+      try {
+        parsed = parseFrontmatter(content);
+      } catch (err) {
+        console.error(
+          chalk.red(`Invalid skill file: ${err.message}`)
+        );
+        process.exit(1);
+        return;
+      }
+      if (!parsed) return;
+      const skillName = options.name ?? parsed.frontmatter.name;
+      const targetDir = options.global ? path.join(os.homedir(), ".claude", "skills", "knowledge") : path.join(process.cwd(), ".claude", "skills", "knowledge");
+      fs.mkdirSync(targetDir, { recursive: true });
+      const targetPath = path.join(targetDir, `${skillName}.skill.md`);
+      const exists = fs.existsSync(targetPath);
+      fs.writeFileSync(targetPath, content, "utf-8");
+      const action = exists ? "Updated" : "Added";
+      const scope = options.global ? "global" : "project";
+      console.log(
+        chalk.green(`${action} ${chalk.bold(skillName)} (${scope})`)
+      );
+      console.log(chalk.dim(`  ${targetPath}`));
+      console.log(
+        chalk.dim(
+          `  domain: ${parsed.frontmatter.domain} | keywords: ${parsed.frontmatter.activates_on.length} | expires: ${parsed.frontmatter.expires}`
+        )
+      );
+    }
+  );
+  cmd.command("refresh [name]").description("Check freshness and show stale skills that need updating").option("--fetch", "Attempt to fetch source URLs and show diff summary").action(async (name, options) => {
+    let skills = discoverSkills();
+    if (name) {
+      skills = skills.filter((s) => s.frontmatter.name === name);
+      if (skills.length === 0) {
+        console.error(chalk.red(`Skill not found: ${name}`));
+        process.exit(1);
+      }
+    }
+    const stale = skills.filter((s) => s.stale);
+    const fresh = skills.filter((s) => !s.stale);
+    console.log(chalk.bold(`
+  Skill Freshness Report
+`));
+    console.log(
+      `  ${chalk.green(String(fresh.length))} active  ${chalk.red(String(stale.length))} expired  ${skills.length} total
+`
+    );
+    if (stale.length === 0) {
+      console.log(chalk.green("  All skills are fresh."));
+      console.log();
+      return;
+    }
+    for (const s of stale) {
+      const daysPast = Math.floor(
+        (Date.now() - new Date(s.frontmatter.expires).getTime()) / 864e5
+      );
+      console.log(
+        `  ${chalk.red("expired")} ${chalk.bold(s.frontmatter.name.padEnd(20))} ${chalk.dim(`${daysPast}d ago`)}  ${s.scope}`
+      );
+      if (s.frontmatter.context7) {
+        console.log(
+          chalk.dim(`           context7: ${s.frontmatter.context7}`)
+        );
+      }
+      for (const src of s.frontmatter.sources) {
+        console.log(chalk.dim(`           source: ${src}`));
+      }
+      if (options.fetch && s.frontmatter.sources.length > 0) {
+        const url = s.frontmatter.sources[0];
+        try {
+          const res = await fetch(url, { method: "HEAD" });
+          console.log(
+            res.ok ? chalk.green(`           ${url} \u2014 reachable (${res.status})`) : chalk.yellow(`           ${url} \u2014 ${res.status}`)
+          );
+        } catch {
+          console.log(chalk.red(`           ${url} \u2014 unreachable`));
+        }
+      }
+    }
+    console.log(
+      chalk.yellow(
+        `
+  To update: edit the .skill.md file and bump the version + expires date.`
+      )
+    );
+    if (!options.fetch) {
+      console.log(
+        chalk.dim(`  Run with --fetch to check source URL reachability.`)
+      );
+    }
+    console.log();
+  });
+  cmd.command("init <name>").description("Scaffold a new .skill.md file").option("--global", "Create in ~/.claude/skills/knowledge/").option("--domain <domain>", "Skill domain", "general").action((name, options) => {
+    const targetDir = options.global ? path.join(os.homedir(), ".claude", "skills", "knowledge") : path.join(process.cwd(), ".claude", "skills", "knowledge");
+    fs.mkdirSync(targetDir, { recursive: true });
+    const targetPath = path.join(targetDir, `${name}.skill.md`);
+    if (fs.existsSync(targetPath)) {
+      console.error(chalk.red(`Already exists: ${targetPath}`));
+      process.exit(1);
+    }
+    const sixMonths = /* @__PURE__ */ new Date();
+    sixMonths.setMonth(sixMonths.getMonth() + 6);
+    const expiresDate = sixMonths.toISOString().slice(0, 10);
+    const template = `---
+name: ${name}
+version: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10).replace(/-/g, ".")}
+domain: ${options.domain}
+expires: ${expiresDate}
+activates_on: [${name}]
+sources:
+  - https://docs.example.com
+context7:
+---
+
+# ${name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, " ")}
+
+## Current SDK & Versions
+- TODO: add current versions
+
+## Preferred Patterns
+- TODO: document the right way to do things
+
+## Gotchas
+- TODO: things LLMs consistently get wrong
+
+## Entry Points
+- TODO: canonical doc URLs
+`;
+    fs.writeFileSync(targetPath, template, "utf-8");
+    console.log(chalk.green(`Created ${chalk.bold(name)} skill`));
+    console.log(chalk.dim(`  ${targetPath}`));
+    console.log(
+      chalk.dim(
+        `  Edit the file to add domain knowledge, then update activates_on keywords.`
+      )
+    );
+  });
+  return cmd;
+}
+export {
+  createSkillCommand
+};

package/dist/src/cli/index.js

@@ -59,8 +59,10 @@ import { createTeamCommands } from "./commands/team.js";
 import { createDesiresCommands } from "./commands/desires.js";
 import { createConductorCommands } from "./commands/orchestrate.js";
 import { createPreflightCommand } from "./commands/preflight.js";
+import { createRulesCommand } from "./commands/rules.js";
 import { createSnapshotCommand } from "./commands/snapshot.js";
 import { createLoopCommand } from "./commands/loop.js";
+import { createSkillCommand } from "./commands/skill.js";
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -478,6 +480,45 @@ program.addCommand(createMemoryCommand());
 program.addCommand(clearCommand);
 program.addCommand(serviceCommand);
 program.addCommand(createHooksCommand());
+program.command("board").description("Open the StackMemory Board (agent kanban + diff viewer)").option("-p, --port <port>", "Port to serve on", "3456").option("--no-open", "Do not auto-open browser").action(async (options) => {
+  const { spawn: spawnProc } = await import("child_process");
+  const { join: join2 } = await import("path");
+  const { existsSync: existsSync2 } = await import("fs");
+  const candidates = [
+    join2(process.cwd(), "tools", "agent-viewer", "server.js"),
+    join2(
+      process.env.PROVENANTAI_ROOT || "",
+      "tools",
+      "agent-viewer",
+      "server.js"
+    ),
+    join2(
+      process.env.HOME || "",
+      "Dev",
+      "provenantai",
+      "tools",
+      "agent-viewer",
+      "server.js"
+    )
+  ];
+  const serverPath = candidates.find((c) => existsSync2(c));
+  if (!serverPath) {
+    console.error(
+      "Board server not found. Run from a repo with tools/agent-viewer/server.js"
+    );
+    process.exit(1);
+  }
+  console.log(`Starting StackMemory Board on port ${options.port}...`);
+  const child = spawnProc("node", [serverPath, "--port", options.port], {
+    stdio: "inherit",
+    env: { ...process.env, FORCE_COLOR: "1" }
+  });
+  child.on("close", (code) => process.exit(code || 0));
+  process.on("SIGINT", () => {
+    child.kill("SIGINT");
+    process.exit(0);
+  });
+});
 const lazyCommands = [];
 if (isFeatureEnabled("skills")) {
   lazyCommands.push(
@@ -515,6 +556,8 @@ program.addCommand(createConductorCommands());
 program.addCommand(createPreflightCommand());
 program.addCommand(createSnapshotCommand());
 program.addCommand(createLoopCommand());
+program.addCommand(createRulesCommand());
+program.addCommand(createSkillCommand());
 registerSetupCommands(program);
 program.command("mm-spike").description(
   "Run multi-agent planning/implementation spike (planner/implementer/critic)"