@vaultctl/core 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,167 @@
+# @vaultctl/core
+
+Core library for structured Obsidian vault operations. Provides frontmatter parsing, wikilink resolution, tag management, search, health checks, and template rendering — all as pure TypeScript with zero CLI dependencies.
+
+This is the library package. For the CLI tool, see [`vaultctl`](https://www.npmjs.com/package/vaultctl).
+
+## Install
+
+```bash
+npm install @vaultctl/core
+```
+
+## Usage
+
+```typescript
+import {
+  loadVault,
+  searchNotes,
+  listTags,
+  findByTag,
+  addTag,
+  removeTag,
+  renameTag,
+  checkHealth,
+  listTemplates,
+  renderTemplate,
+  parseNote,
+  safeJoin,
+} from '@vaultctl/core';
+
+// Load all notes from a vault
+const notes = await loadVault('/path/to/vault');
+
+// Search notes by content and frontmatter
+const results = searchNotes(notes, {
+  query: 'meeting notes',
+  type: 'project',
+  status: 'active',
+  tag: 'work',
+});
+
+// Tag operations
+const tags = listTags(notes);           // all tags with counts
+const tagged = findByTag(notes, 'status/active');
+await addTag('/path/to/vault', '01_Projects/my-project.md', 'priority/high');
+await removeTag('/path/to/vault', '01_Projects/my-project.md', 'priority/high');
+const renamed = await renameTag('/path/to/vault', notes, 'old-tag', 'new-tag');
+
+// Health checks
+const issues = await checkHealth('/path/to/vault', notes);
+const linksOnly = await checkHealth('/path/to/vault', notes, ['broken-links']);
+
+// Templates
+const templates = await listTemplates('/path/to/vault');
+const content = await renderTemplate('/path/to/vault', 'project', 'My Project');
+
+// Parse a single note
+const note = parseNote('/path/to/vault', 'relative/path.md', fileContent);
+
+// Safe path joining (prevents path traversal)
+const safePath = safeJoin('/path/to/vault', 'notes/file.md');
+```
+
+## API
+
+### Vault
+
+| Function | Description |
+|----------|-------------|
+| `loadVault(path)` | Load and parse all `.md` files in a vault |
+| `resolveVaultPath(options?)` | Find vault root via flag, env, or directory walk |
+| `safeJoin(vaultPath, relativePath)` | Join paths with traversal protection |
+
+### Search
+
+| Function | Description |
+|----------|-------------|
+| `searchNotes(notes, options)` | Filter notes by query, type, status, and/or tag |
+
+**`SearchOptions`**: `{ query?, type?, status?, tag? }`
+
+### Tags
+
+| Function | Description |
+|----------|-------------|
+| `listTags(notes)` | List all tags with usage counts |
+| `findByTag(notes, tag)` | Find notes containing a tag |
+| `addTag(vault, path, tag)` | Add a tag to a note's frontmatter |
+| `removeTag(vault, path, tag)` | Remove a tag from a note |
+| `renameTag(vault, notes, old, new)` | Rename a tag across the vault |
+
+Tags are validated on write — must start with a letter and contain only letters, numbers, hyphens, underscores, or `/` for hierarchy.
+
+### Health
+
+| Function | Description |
+|----------|-------------|
+| `checkHealth(vault, notes, checks?)` | Run health checks on the vault |
+
+**`CheckName`**: `'broken-links' | 'orphans' | 'stale' | 'frontmatter'`
+
+### Templates
+
+| Function | Description |
+|----------|-------------|
+| `listTemplates(vault)` | List available `_templates/tpl-*.md` templates |
+| `renderTemplate(vault, name, title?)` | Render a template with date/title substitution |
+
+### Parsing
+
+| Function | Description |
+|----------|-------------|
+| `parseNote(vault, path, content)` | Parse a markdown file into a `Note` object |
+| `parseFrontmatter(content)` | Extract YAML frontmatter |
+| `stringifyFrontmatter(fm, body)` | Serialize frontmatter + body back to markdown |
+| `parseWikilinks(content)` | Extract `[[wikilinks]]` from content |
+| `parseInlineTags(content)` | Extract `#hashtags` from content |
+
+## Types
+
+```typescript
+interface Note {
+  path: string;
+  filename: string;
+  folder: string;
+  frontmatter: Frontmatter;
+  body: string;
+  wikilinks: WikiLink[];
+  inlineTags: string[];
+}
+
+interface Frontmatter {
+  type?: string;
+  status?: string;
+  tags?: string[];
+  created?: string;
+  updated?: string;
+  [key: string]: unknown;
+}
+
+interface WikiLink {
+  raw: string;
+  target: string;
+  alias?: string;
+  resolved?: string | null;
+}
+
+interface HealthIssue {
+  check: string;
+  path: string;
+  message: string;
+  severity: 'error' | 'warning' | 'info';
+}
+
+interface VaultStats {
+  totalNotes: number;
+  notesByType: Record<string, number>;
+  notesByStatus: Record<string, number>;
+  totalTags: number;
+  brokenLinks: number;
+  orphanedNotes: number;
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultctl/core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Core library for structured Obsidian vault operations — frontmatter, wikilinks, tags, search, and health checks",
   "type": "module",
   "license": "MIT",