clawvault 2.2.0 → 2.3.0

package/dist/chunk-NGVAEFT2.js

@@ -0,0 +1,352 @@
+// src/lib/task-utils.ts
+import * as fs from "fs";
+import * as path from "path";
+import matter from "gray-matter";
+function slugify(text) {
+  return text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").trim();
+}
+function getTasksDir(vaultPath) {
+  return path.join(path.resolve(vaultPath), "tasks");
+}
+function getBacklogDir(vaultPath) {
+  return path.join(path.resolve(vaultPath), "backlog");
+}
+function ensureTasksDir(vaultPath) {
+  const tasksDir = getTasksDir(vaultPath);
+  if (!fs.existsSync(tasksDir)) {
+    fs.mkdirSync(tasksDir, { recursive: true });
+  }
+}
+function ensureBacklogDir(vaultPath) {
+  const backlogDir = getBacklogDir(vaultPath);
+  if (!fs.existsSync(backlogDir)) {
+    fs.mkdirSync(backlogDir, { recursive: true });
+  }
+}
+function getTaskPath(vaultPath, slug) {
+  return path.join(getTasksDir(vaultPath), `${slug}.md`);
+}
+function getBacklogPath(vaultPath, slug) {
+  return path.join(getBacklogDir(vaultPath), `${slug}.md`);
+}
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : "";
+}
+function readTask(vaultPath, slug) {
+  const taskPath = getTaskPath(vaultPath, slug);
+  if (!fs.existsSync(taskPath)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(taskPath, "utf-8");
+    const { data, content } = matter(raw);
+    const title = extractTitle(content) || slug;
+    return {
+      slug,
+      title,
+      content,
+      frontmatter: data,
+      path: taskPath
+    };
+  } catch {
+    return null;
+  }
+}
+function readBacklogItem(vaultPath, slug) {
+  const backlogPath = getBacklogPath(vaultPath, slug);
+  if (!fs.existsSync(backlogPath)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(backlogPath, "utf-8");
+    const { data, content } = matter(raw);
+    const title = extractTitle(content) || slug;
+    return {
+      slug,
+      title,
+      content,
+      frontmatter: data,
+      path: backlogPath
+    };
+  } catch {
+    return null;
+  }
+}
+function listTasks(vaultPath, filters) {
+  const tasksDir = getTasksDir(vaultPath);
+  if (!fs.existsSync(tasksDir)) {
+    return [];
+  }
+  const tasks = [];
+  const entries = fs.readdirSync(tasksDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+    const slug = entry.name.replace(/\.md$/, "");
+    const task = readTask(vaultPath, slug);
+    if (!task) continue;
+    if (filters) {
+      if (filters.status && task.frontmatter.status !== filters.status) continue;
+      if (filters.owner && task.frontmatter.owner !== filters.owner) continue;
+      if (filters.project && task.frontmatter.project !== filters.project) continue;
+      if (filters.priority && task.frontmatter.priority !== filters.priority) continue;
+    }
+    tasks.push(task);
+  }
+  const priorityOrder = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3
+  };
+  return tasks.sort((a, b) => {
+    const aPriority = priorityOrder[a.frontmatter.priority || "low"];
+    const bPriority = priorityOrder[b.frontmatter.priority || "low"];
+    if (aPriority !== bPriority) {
+      return aPriority - bPriority;
+    }
+    return new Date(b.frontmatter.created).getTime() - new Date(a.frontmatter.created).getTime();
+  });
+}
+function listBacklogItems(vaultPath, filters) {
+  const backlogDir = getBacklogDir(vaultPath);
+  if (!fs.existsSync(backlogDir)) {
+    return [];
+  }
+  const items = [];
+  const entries = fs.readdirSync(backlogDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+    const slug = entry.name.replace(/\.md$/, "");
+    const item = readBacklogItem(vaultPath, slug);
+    if (!item) continue;
+    if (filters) {
+      if (filters.project && item.frontmatter.project !== filters.project) continue;
+      if (filters.source && item.frontmatter.source !== filters.source) continue;
+    }
+    items.push(item);
+  }
+  return items.sort((a, b) => {
+    return new Date(b.frontmatter.created).getTime() - new Date(a.frontmatter.created).getTime();
+  });
+}
+function createTask(vaultPath, title, options = {}) {
+  ensureTasksDir(vaultPath);
+  const slug = slugify(title);
+  const taskPath = getTaskPath(vaultPath, slug);
+  if (fs.existsSync(taskPath)) {
+    throw new Error(`Task already exists: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const frontmatter = {
+    status: "open",
+    created: now,
+    updated: now
+  };
+  if (options.owner) frontmatter.owner = options.owner;
+  if (options.project) frontmatter.project = options.project;
+  if (options.priority) frontmatter.priority = options.priority;
+  if (options.due) frontmatter.due = options.due;
+  if (options.tags && options.tags.length > 0) frontmatter.tags = options.tags;
+  let content = `# ${title}
+`;
+  const links = [];
+  if (options.owner) links.push(`[[${options.owner}]]`);
+  if (options.project) links.push(`[[${options.project}]]`);
+  if (links.length > 0) {
+    content += `
+${links.join(" | ")}
+`;
+  }
+  if (options.content) {
+    content += `
+${options.content}
+`;
+  }
+  const fileContent = matter.stringify(content, frontmatter);
+  fs.writeFileSync(taskPath, fileContent);
+  return {
+    slug,
+    title,
+    content,
+    frontmatter,
+    path: taskPath
+  };
+}
+function updateTask(vaultPath, slug, updates) {
+  const task = readTask(vaultPath, slug);
+  if (!task) {
+    throw new Error(`Task not found: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const newFrontmatter = {
+    ...task.frontmatter,
+    updated: now
+  };
+  if (updates.status !== void 0) newFrontmatter.status = updates.status;
+  if (updates.owner !== void 0) newFrontmatter.owner = updates.owner;
+  if (updates.project !== void 0) newFrontmatter.project = updates.project;
+  if (updates.priority !== void 0) newFrontmatter.priority = updates.priority;
+  if (updates.due !== void 0) newFrontmatter.due = updates.due;
+  if (updates.tags !== void 0) newFrontmatter.tags = updates.tags;
+  if (updates.blocked_by !== void 0) {
+    newFrontmatter.blocked_by = updates.blocked_by;
+  } else if (updates.status && updates.status !== "blocked") {
+    delete newFrontmatter.blocked_by;
+  }
+  const fileContent = matter.stringify(task.content, newFrontmatter);
+  fs.writeFileSync(task.path, fileContent);
+  return {
+    ...task,
+    frontmatter: newFrontmatter
+  };
+}
+function completeTask(vaultPath, slug) {
+  const task = readTask(vaultPath, slug);
+  if (!task) {
+    throw new Error(`Task not found: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const newFrontmatter = {
+    ...task.frontmatter,
+    status: "done",
+    updated: now,
+    completed: now
+  };
+  delete newFrontmatter.blocked_by;
+  const fileContent = matter.stringify(task.content, newFrontmatter);
+  fs.writeFileSync(task.path, fileContent);
+  return {
+    ...task,
+    frontmatter: newFrontmatter
+  };
+}
+function createBacklogItem(vaultPath, title, options = {}) {
+  ensureBacklogDir(vaultPath);
+  const slug = slugify(title);
+  const backlogPath = getBacklogPath(vaultPath, slug);
+  if (fs.existsSync(backlogPath)) {
+    throw new Error(`Backlog item already exists: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const frontmatter = {
+    created: now
+  };
+  if (options.source) frontmatter.source = options.source;
+  if (options.project) frontmatter.project = options.project;
+  if (options.tags && options.tags.length > 0) frontmatter.tags = options.tags;
+  let content = `# ${title}
+`;
+  const links = [];
+  if (options.source) links.push(`[[${options.source}]]`);
+  if (options.project) links.push(`[[${options.project}]]`);
+  if (links.length > 0) {
+    content += `
+${links.join(" | ")}
+`;
+  }
+  if (options.content) {
+    content += `
+${options.content}
+`;
+  }
+  const fileContent = matter.stringify(content, frontmatter);
+  fs.writeFileSync(backlogPath, fileContent);
+  return {
+    slug,
+    title,
+    content,
+    frontmatter,
+    path: backlogPath
+  };
+}
+function promoteBacklogItem(vaultPath, slug, options = {}) {
+  const backlogItem = readBacklogItem(vaultPath, slug);
+  if (!backlogItem) {
+    throw new Error(`Backlog item not found: ${slug}`);
+  }
+  const task = createTask(vaultPath, backlogItem.title, {
+    owner: options.owner,
+    project: backlogItem.frontmatter.project,
+    priority: options.priority,
+    due: options.due,
+    content: backlogItem.content.replace(/^#\s+.+\n/, "").trim(),
+    // Remove title from content
+    tags: backlogItem.frontmatter.tags
+  });
+  fs.unlinkSync(backlogItem.path);
+  return task;
+}
+function getBlockedTasks(vaultPath, project) {
+  const filters = { status: "blocked" };
+  if (project) filters.project = project;
+  return listTasks(vaultPath, filters);
+}
+function getActiveTasks(vaultPath, filters) {
+  const allTasks = listTasks(vaultPath, filters);
+  return allTasks.filter((t) => t.frontmatter.status === "open" || t.frontmatter.status === "in-progress");
+}
+function getRecentlyCompletedTasks(vaultPath, limit = 10) {
+  const allTasks = listTasks(vaultPath, { status: "done" });
+  return allTasks.filter((t) => t.frontmatter.completed).sort((a, b) => {
+    const aCompleted = new Date(a.frontmatter.completed || 0).getTime();
+    const bCompleted = new Date(b.frontmatter.completed || 0).getTime();
+    return bCompleted - aCompleted;
+  }).slice(0, limit);
+}
+function getStatusIcon(status) {
+  switch (status) {
+    case "in-progress":
+      return "\u25CF";
+    case "blocked":
+      return "\u25A0";
+    case "open":
+      return "\u25CB";
+    case "done":
+      return "\u2713";
+    default:
+      return "\u25CB";
+  }
+}
+function getStatusDisplay(status) {
+  switch (status) {
+    case "in-progress":
+      return "active";
+    case "blocked":
+      return "blocked";
+    case "open":
+      return "open";
+    case "done":
+      return "done";
+    default:
+      return status;
+  }
+}
+
+export {
+  slugify,
+  getTasksDir,
+  getBacklogDir,
+  ensureTasksDir,
+  ensureBacklogDir,
+  getTaskPath,
+  getBacklogPath,
+  readTask,
+  readBacklogItem,
+  listTasks,
+  listBacklogItems,
+  createTask,
+  updateTask,
+  completeTask,
+  createBacklogItem,
+  promoteBacklogItem,
+  getBlockedTasks,
+  getActiveTasks,
+  getRecentlyCompletedTasks,
+  getStatusIcon,
+  getStatusDisplay
+};

package/dist/{chunk-IFGDPIFI.js → chunk-OTQW3OMC.js}

@@ -8,7 +8,7 @@ import {
   hasQmd,
   qmdEmbed,
   qmdUpdate
-} from "./chunk-DHBDH4DN.js";
+} from "./chunk-FDJIZKCW.js";
 import {
   buildOrUpdateMemoryGraphIndex
 } from "./chunk-ZZA73MFY.js";
@@ -58,11 +58,19 @@ var ClawVault = class {
         fs.mkdirSync(catPath, { recursive: true });
       }
     }
+    const ledgerDirs = ["ledger/raw", "ledger/observations", "ledger/reflections"];
+    for (const dir of ledgerDirs) {
+      const dirPath = path.join(vaultPath, dir);
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+      }
+    }
     await this.createTemplates();
     const readmePath = path.join(vaultPath, "README.md");
     if (!fs.existsSync(readmePath)) {
       fs.writeFileSync(readmePath, this.generateReadme());
     }
+    await this.createWelcomeNote();
     const configPath = path.join(vaultPath, CONFIG_FILE);
     const meta = {
       name: this.config.name,
@@ -628,6 +636,51 @@ var ClawVault = class {
       }
     }
   }
+  async createWelcomeNote() {
+    const inboxPath = path.join(this.config.path, "inbox", "welcome.md");
+    if (fs.existsSync(inboxPath)) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const content = `---
+title: "Welcome to ${this.config.name}"
+date: ${now}
+type: fact
+tags: [welcome, getting-started]
+---
+
+# Welcome to ${this.config.name}
+
+Your vault is ready. Here's what you can do:
+
+## Quick Start
+
+- **Capture a thought:** \`clawvault capture "your note here"\`
+- **Store structured memory:** \`clawvault store --category decisions --title "My Choice" --content "..."\`
+- **Search your vault:** \`clawvault search "query"\`
+- **See your knowledge graph:** \`clawvault graph\`
+- **Get context for a topic:** \`clawvault context "topic"\`
+
+## Vault Structure
+
+Your vault organizes memories by type \u2014 decisions, lessons, people, projects, and more.
+Each category is a folder. Each memory is a markdown file with frontmatter.
+
+## Observational Memory
+
+When connected to an AI agent (like OpenClaw), your vault can automatically observe
+conversations and extract important memories \u2014 decisions, lessons, commitments \u2014 without
+manual effort.
+
+## Wiki-Links
+
+Use \`[[double brackets]]\` to link between notes. Your memory graph tracks these
+connections, building a knowledge network that grows with you.
+
+---
+
+*Delete this file anytime. It's just here to say hello.*
+`;
+    fs.writeFileSync(inboxPath, content);
+  }
   async syncMemoryGraphIndex(options = {}) {
     try {
       await buildOrUpdateMemoryGraphIndex(this.config.path, options);
@@ -635,29 +688,51 @@ var ClawVault = class {
     }
   }
   generateReadme() {
-    return `# ${this.config.name} \u{1F418}
+    const coreCategories = this.config.categories.filter((c) => !["templates", "tasks", "backlog"].includes(c));
+    const workCategories = this.config.categories.filter((c) => ["tasks", "backlog"].includes(c));
+    return `# ${this.config.name}
 
 An elephant never forgets.
 
 ## Structure
 
-${this.config.categories.map((c) => `- \`/${c}/\` \u2014 ${this.getCategoryDescription(c)}`).join("\n")}
+### Memory Categories
+${coreCategories.map((c) => `- \`${c}/\` \u2014 ${this.getCategoryDescription(c)}`).join("\n")}
 
-## Quick Search
+### Work Tracking
+${workCategories.map((c) => `- \`${c}/\` \u2014 ${this.getCategoryDescription(c)}`).join("\n")}
+
+### Observational Memory
+- \`ledger/raw/\` \u2014 Raw session transcripts (source of truth)
+- \`ledger/observations/\` \u2014 Compressed observations with importance scores
+- \`ledger/reflections/\` \u2014 Weekly reflection summaries
+
+## Quick Reference
 
 \`\`\`bash
+# Capture a thought
+clawvault capture "important insight about X"
+
+# Store structured memory
+clawvault store --category decisions --title "Choice" --content "We chose X because..."
+
+# Search
 clawvault search "query"
-\`\`\`
+clawvault vsearch "semantic query"    # vector search
 
-## Quick Capture
+# Knowledge graph
+clawvault graph                       # vault stats
+clawvault context "topic"             # graph-aware context retrieval
 
-\`\`\`bash
-clawvault store --category inbox --title "note" --content "..."
+# Session lifecycle
+clawvault checkpoint --working-on "task"
+clawvault sleep "what I did" --next "what's next"
+clawvault wake                        # restore context on startup
 \`\`\`
 
 ---
 
-*Managed by [ClawVault](https://github.com/Versatly/clawvault)*
+*Managed by [ClawVault](https://clawvault.dev)*
 `;
   }
   getCategoryDescription(category) {
@@ -677,7 +752,11 @@ clawvault store --category inbox --title "note" --content "..."
       goals: "Long-term and short-term objectives",
       patterns: "Recurring behaviors (\u2192 lessons)",
       inbox: "Quick capture \u2192 process later",
-      templates: "Templates for each document type"
+      templates: "Templates for each document type",
+      agents: "Other agents \u2014 capabilities, trust levels, coordination notes",
+      research: "Deep dives, analysis, reference material",
+      tasks: "Active work items with status and context",
+      backlog: "Future work \u2014 ideas and tasks not yet started"
     };
     return descriptions[category] || category;
   }

package/dist/{chunk-6RIHODNR.js → chunk-SOTWYGH7.js}

@@ -1,15 +1,15 @@
+import {
+  ClawVault
+} from "./chunk-OTQW3OMC.js";
 import {
   parseObservationMarkdown
 } from "./chunk-K6XHCUFL.js";
-import {
-  listObservationFiles
-} from "./chunk-Z2XBWN7A.js";
-import {
-  ClawVault
-} from "./chunk-IFGDPIFI.js";
 import {
   getMemoryGraph
 } from "./chunk-ZZA73MFY.js";
+import {
+  listObservationFiles
+} from "./chunk-Z2XBWN7A.js";
 
 // src/commands/context.ts
 import * as path from "path";

package/dist/{chunk-KNDVXXKC.js → chunk-W463YRED.js}

@@ -1,7 +1,7 @@
 import {
   DEFAULT_CATEGORIES,
   hasQmd
-} from "./chunk-DHBDH4DN.js";
+} from "./chunk-FDJIZKCW.js";
 
 // src/commands/setup.ts
 import * as fs from "fs";

package/dist/commands/archive.js

@@ -3,8 +3,8 @@ import {
   registerArchiveCommand
 } from "../chunk-VR5NE7PZ.js";
 import "../chunk-MQUJNOHK.js";
-import "../chunk-Z2XBWN7A.js";
 import "../chunk-MXSSG3QU.js";
+import "../chunk-Z2XBWN7A.js";
 export {
   archiveCommand,
   registerArchiveCommand

package/dist/commands/backlog.d.ts

@@ -0,0 +1,53 @@
+import { TaskPriority, BacklogItem, Task } from '../lib/task-utils.js';
+
+/**
+ * Backlog command for ClawVault
+ * Manages backlog add/list/promote operations
+ */
+
+interface BacklogAddOptions {
+    source?: string;
+    project?: string;
+    content?: string;
+    tags?: string[];
+}
+interface BacklogListOptions {
+    project?: string;
+    json?: boolean;
+}
+interface BacklogPromoteOptions {
+    owner?: string;
+    priority?: TaskPriority;
+    due?: string;
+}
+/**
+ * Add a new backlog item
+ */
+declare function backlogAdd(vaultPath: string, title: string, options?: BacklogAddOptions): BacklogItem;
+/**
+ * List backlog items with optional filters
+ */
+declare function backlogList(vaultPath: string, options?: BacklogListOptions): BacklogItem[];
+/**
+ * Promote a backlog item to a task
+ */
+declare function backlogPromote(vaultPath: string, slug: string, options?: BacklogPromoteOptions): Task;
+/**
+ * Format backlog list for terminal display
+ */
+declare function formatBacklogList(items: BacklogItem[]): string;
+/**
+ * Format backlog item details for display
+ */
+declare function formatBacklogDetails(item: BacklogItem): string;
+/**
+ * Backlog command handler for CLI
+ * Note: The CLI uses "clawvault backlog <title>" as shorthand for add
+ */
+declare function backlogCommand(vaultPath: string, action: 'add' | 'list' | 'promote', args: {
+    title?: string;
+    slug?: string;
+    options?: BacklogAddOptions & BacklogListOptions & BacklogPromoteOptions;
+}): Promise<void>;
+
+export { type BacklogAddOptions, type BacklogListOptions, type BacklogPromoteOptions, backlogAdd, backlogCommand, backlogList, backlogPromote, formatBacklogDetails, formatBacklogList };