@safetnsr/md-pipe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 safetnsr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# md-pipe
+
+Event-driven automation for markdown directories.
+`entr` watches files. `md-pipe` understands them.
+
+12 lines of YAML → your markdown folder auto-publishes, auto-indexes, and auto-archives based on frontmatter changes. Works with any `.md` directory — Obsidian vaults, agent workspaces, docs-as-code repos, digital gardens.
+
+## Install
+
+```bash
+npx @safetnsr/md-pipe init
+```
+
+Or install globally:
+
+```bash
+npm install -g @safetnsr/md-pipe
+```
+
+## Quick Start
+
+```bash
+# 1. Create config
+md-pipe init
+
+# 2. Edit .md-pipe.yml with your triggers
+
+# 3. Start watching
+md-pipe watch
+```
+
+## Config (.md-pipe.yml)
+
+```yaml
+watch: ./docs
+
+triggers:
+  - name: publish
+    match:
+      path: "posts/**"
+      frontmatter:
+        status: publish
+    run: "./scripts/deploy.sh $FILE"
+
+  - name: reindex
+    match:
+      frontmatter_changed:
+        - title
+        - tags
+        - category
+    run: "./scripts/reindex.sh $FILE"
+
+  - name: urgent-notify
+    match:
+      tags:
+        - urgent
+    run: "curl -X POST $WEBHOOK -d '{\"file\": \"$FILE\"}'"
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `md-pipe init` | Scaffold a `.md-pipe.yml` config file |
+| `md-pipe watch` | Start watching for changes and trigger actions |
+| `md-pipe once` | Run triggers against current files (CI/batch mode) |
+| `md-pipe test <file>` | Show which triggers match a specific file |
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `--config, -c <path>` | Path to config file |
+| `--dry-run` | Show matches without executing actions |
+| `--json` | Output in JSON format |
+| `--verbose` | Show detailed output |
+| `--version, -v` | Show version |
+| `--help, -h` | Show help |
+
+## Trigger Matchers
+
+### `path` — glob pattern matching
+```yaml
+match:
+  path: "posts/**/*.md"
+```
+
+### `frontmatter` — match specific frontmatter values
+```yaml
+match:
+  frontmatter:
+    status: publish
+    type: blog
+```
+
+### `frontmatter_changed` — fires when specific fields change
+```yaml
+match:
+  frontmatter_changed:
+    - title
+    - tags
+```
+This is the key differentiator over generic file watchers. `md-pipe` tracks frontmatter state and only triggers when the fields you care about actually change.
+
+### `tags` — match files with specific tags
+```yaml
+match:
+  tags:
+    - urgent
+    - review
+```
+
+Matchers can be combined — all conditions must match for the trigger to fire.
+
+## Environment Variables
+
+Scripts receive these env vars:
+
+| Variable | Description |
+|---|---|
+| `$FILE` | Absolute path to the changed file |
+| `$DIR` | Directory containing the file |
+| `$BASENAME` | Filename without directory |
+| `$RELATIVE` | Path relative to watch directory |
+| `$FRONTMATTER` | JSON string of all frontmatter |
+| `$DIFF` | JSON string of changed frontmatter fields |
+| `$TAGS` | Comma-separated list of tags |
+
+## Agent Interface (--json)
+
+```bash
+md-pipe once --json
+```
+
+```json
+{
+  "total": 42,
+  "matched": 3,
+  "actions": [
+    {
+      "triggerName": "publish",
+      "filePath": "/docs/posts/hello.md",
+      "command": "./scripts/deploy.sh /docs/posts/hello.md",
+      "exitCode": 0,
+      "stdout": "deployed",
+      "stderr": "",
+      "durationMs": 150
+    }
+  ],
+  "errors": []
+}
+```
+
+```bash
+md-pipe watch --json
+# streams one JSON object per triggered action
+```
+
+## Use Cases
+
+**Docs-as-code auto-deploy** — publish pages when `status: publish` is set in frontmatter
+
+**Agent workspace automation** — trigger reindexing when an agent updates `AGENTS.md` or `NOW.md`
+
+**Obsidian vault pipeline** — auto-archive notes, generate backlinks, push to git on tag changes
+
+**Digital garden** — auto-generate RSS feed when new posts are added
+
+**CI/CD for markdown** — `md-pipe once` in your CI pipeline to validate or transform docs
+
+## Pair With
+
+- [`@safetnsr/md-kit`](https://github.com/safetnsr/md-kit) — markdown workspace toolkit (wikilinks, broken links, backlink maps)
+- [`@safetnsr/ai-ready`](https://github.com/safetnsr/ai-ready) — AI-compatibility score for your codebase
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_js_1 = require("./core/config.js");
+const watcher_js_1 = require("./core/watcher.js");
+const once_js_1 = require("./core/once.js");
+const test_file_js_1 = require("./core/test-file.js");
+const VERSION = '0.1.0';
+function printHelp() {
+    console.log(`
+${chalk_1.default.bold('md-pipe')} — event-driven automation for markdown directories
+${chalk_1.default.dim('entr watches files. md-pipe understands them.')}
+
+${chalk_1.default.bold('Usage:')}
+  md-pipe init              Scaffold a .md-pipe.yml config file
+  md-pipe watch             Start watching for changes and trigger actions
+  md-pipe once              Run triggers against current files (CI/batch mode)
+  md-pipe test <file>       Show which triggers match a specific file
+
+${chalk_1.default.bold('Flags:')}
+  --config, -c <path>       Path to config file (default: .md-pipe.yml)
+  --dry-run                 Show matches without executing actions
+  --json                    Output in JSON format
+  --verbose                 Show detailed output
+  --version, -v             Show version
+  --help, -h                Show this help
+
+${chalk_1.default.bold('Config (.md-pipe.yml):')}
+  watch: ./docs
+  triggers:
+    - name: publish
+      match:
+        path: "posts/**"
+        frontmatter: { status: publish }
+      run: "echo Publishing $FILE"
+
+${chalk_1.default.bold('Env vars passed to scripts:')}
+  $FILE          Absolute path to the changed file
+  $DIR           Directory containing the file
+  $BASENAME      Filename without directory
+  $RELATIVE      Path relative to watch directory
+  $FRONTMATTER   JSON string of all frontmatter
+  $DIFF          JSON string of changed frontmatter fields
+  $TAGS          Comma-separated list of tags
+
+${chalk_1.default.bold('More:')} https://github.com/safetnsr/md-pipe
+`);
+}
+function parseArgs(args) {
+    let command = '';
+    let file;
+    let config;
+    let dryRun = false;
+    let json = false;
+    let verbose = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        if (arg === '--version' || arg === '-v') {
+            console.log(VERSION);
+            process.exit(0);
+        }
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--verbose') {
+            verbose = true;
+            continue;
+        }
+        if (arg === '--config' || arg === '-c') {
+            config = args[++i];
+            continue;
+        }
+        if (!command) {
+            command = arg;
+            continue;
+        }
+        if (command === 'test' && !file) {
+            file = arg;
+            continue;
+        }
+    }
+    return { command: command || 'help', file, config, dryRun, json, verbose };
+}
+function getConfig(configPath) {
+    const cwd = process.cwd();
+    const cfgPath = configPath || (0, config_js_1.findConfigFile)(cwd);
+    if (!cfgPath) {
+        console.error(chalk_1.default.red('No .md-pipe.yml found. Run `md-pipe init` to create one.'));
+        process.exit(1);
+    }
+    return (0, config_js_1.loadConfig)(cfgPath);
+}
+async function cmdInit() {
+    const target = (0, path_1.resolve)(process.cwd(), '.md-pipe.yml');
+    if ((0, fs_1.existsSync)(target)) {
+        console.error(chalk_1.default.yellow('.md-pipe.yml already exists. Delete it first to re-initialize.'));
+        process.exit(1);
+    }
+    (0, fs_1.writeFileSync)(target, (0, config_js_1.generateDefaultConfig)(), 'utf-8');
+    console.log(chalk_1.default.green('✓') + ' Created .md-pipe.yml');
+    console.log(chalk_1.default.dim('  Edit the config, then run: md-pipe watch'));
+}
+async function cmdWatch(opts) {
+    const config = getConfig(opts.config);
+    const watcher = new watcher_js_1.MdPipeWatcher(config, opts.dryRun);
+    if (!(0, fs_1.existsSync)(config.watch)) {
+        console.error(chalk_1.default.red(`Watch directory not found: ${config.watch}`));
+        process.exit(1);
+    }
+    watcher.on('ready', () => {
+        console.log(chalk_1.default.green('✓') + ` Watching ${config.watch}`);
+        console.log(chalk_1.default.dim(`  ${config.triggers.length} trigger(s) loaded`));
+        if (opts.dryRun)
+            console.log(chalk_1.default.yellow('  [dry-run mode — actions will not execute]'));
+        console.log(chalk_1.default.dim('  Press Ctrl+C to stop\n'));
+    });
+    watcher.on('match', (result) => {
+        if (opts.json)
+            return; // json mode outputs on action
+        const ts = new Date().toLocaleTimeString();
+        console.log(chalk_1.default.dim(`[${ts}]`) + ' ' +
+            chalk_1.default.cyan(`▸ ${result.trigger.name}`) + ' ' +
+            chalk_1.default.dim('matched') + ' ' +
+            result.file.relativePath);
+    });
+    watcher.on('action', (result) => {
+        if (opts.json) {
+            console.log(JSON.stringify(result));
+            return;
+        }
+        const status = result.exitCode === 0
+            ? chalk_1.default.green('✓')
+            : chalk_1.default.red(`✗ exit ${result.exitCode}`);
+        console.log(`  ${status} ${chalk_1.default.dim(result.command)}`);
+        if (result.stdout && opts.verbose) {
+            console.log(chalk_1.default.dim('    ' + result.stdout.replace(/\n/g, '\n    ')));
+        }
+        if (result.stderr) {
+            console.log(chalk_1.default.red('    ' + result.stderr.replace(/\n/g, '\n    ')));
+        }
+    });
+    watcher.on('error', (err, filePath) => {
+        console.error(chalk_1.default.red(`Error${filePath ? ` (${filePath})` : ''}: ${err.message}`));
+    });
+    // Graceful shutdown
+    process.on('SIGINT', async () => {
+        console.log(chalk_1.default.dim('\nStopping watcher...'));
+        await watcher.stop();
+        process.exit(0);
+    });
+    await watcher.start();
+}
+function cmdOnce(opts) {
+    const config = getConfig(opts.config);
+    if (!(0, fs_1.existsSync)(config.watch)) {
+        console.error(chalk_1.default.red(`Watch directory not found: ${config.watch}`));
+        process.exit(1);
+    }
+    const result = (0, once_js_1.runOnce)(config, opts.dryRun);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(chalk_1.default.bold('md-pipe once'));
+    console.log(chalk_1.default.dim(`  Scanned ${result.total} files, ${result.matched} trigger match(es)\n`));
+    if (opts.dryRun) {
+        console.log(chalk_1.default.yellow('  [dry-run mode — actions were not executed]\n'));
+    }
+    for (const action of result.actions) {
+        const status = action.exitCode === 0
+            ? chalk_1.default.green('✓')
+            : chalk_1.default.red(`✗ exit ${action.exitCode}`);
+        console.log(`${status} ${chalk_1.default.cyan(action.triggerName)} → ${chalk_1.default.dim(action.command)}`);
+        if (action.stdout && opts.verbose) {
+            console.log(chalk_1.default.dim('  ' + action.stdout));
+        }
+        if (action.stderr) {
+            console.log(chalk_1.default.red('  ' + action.stderr));
+        }
+    }
+    for (const err of result.errors) {
+        console.error(chalk_1.default.red(err));
+    }
+    if (result.errors.length > 0)
+        process.exit(1);
+}
+function cmdTest(opts) {
+    if (!opts.file) {
+        console.error(chalk_1.default.red('Usage: md-pipe test <file>'));
+        process.exit(1);
+    }
+    const config = getConfig(opts.config);
+    const result = (0, test_file_js_1.testFile)(config, opts.file);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(chalk_1.default.bold(`Testing: ${result.relativePath}`));
+    console.log(chalk_1.default.dim(`  Frontmatter: ${JSON.stringify(result.frontmatter)}`));
+    console.log(chalk_1.default.dim(`  Tags: [${result.tags.join(', ')}]\n`));
+    if (result.matches.length === 0) {
+        console.log(chalk_1.default.yellow('  No triggers matched this file.'));
+        return;
+    }
+    for (const m of result.matches) {
+        console.log(chalk_1.default.green('  ✓') + ` ${chalk_1.default.cyan(m.triggerName)}: ${m.reason}`);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const opts = parseArgs(args);
+    try {
+        switch (opts.command) {
+            case 'init':
+                await cmdInit();
+                break;
+            case 'watch':
+                await cmdWatch(opts);
+                break;
+            case 'once':
+                cmdOnce(opts);
+                break;
+            case 'test':
+                cmdTest(opts);
+                break;
+            case 'help':
+                printHelp();
+                break;
+            default:
+                console.error(chalk_1.default.red(`Unknown command: ${opts.command}`));
+                printHelp();
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(chalk_1.default.red(`Error: ${err.message}`));
+        process.exit(1);
+    }
+}
+main();

package/dist/core/config.d.ts

@@ -0,0 +1,18 @@
+export interface TriggerMatch {
+    path?: string;
+    frontmatter?: Record<string, unknown>;
+    frontmatter_changed?: string[];
+    tags?: string[];
+}
+export interface TriggerDef {
+    name: string;
+    match: TriggerMatch;
+    run: string;
+}
+export interface MdPipeConfig {
+    watch: string;
+    triggers: TriggerDef[];
+}
+export declare function findConfigFile(dir: string): string | null;
+export declare function loadConfig(configPath: string): MdPipeConfig;
+export declare function generateDefaultConfig(): string;

package/dist/core/config.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findConfigFile = findConfigFile;
+exports.loadConfig = loadConfig;
+exports.generateDefaultConfig = generateDefaultConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = __importDefault(require("yaml"));
+const CONFIG_FILENAMES = ['.md-pipe.yml', '.md-pipe.yaml', 'md-pipe.yml', 'md-pipe.yaml'];
+function findConfigFile(dir) {
+    for (const name of CONFIG_FILENAMES) {
+        const p = (0, path_1.resolve)(dir, name);
+        if ((0, fs_1.existsSync)(p))
+            return p;
+    }
+    return null;
+}
+function loadConfig(configPath) {
+    const raw = (0, fs_1.readFileSync)(configPath, 'utf-8');
+    const parsed = yaml_1.default.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Invalid config: expected YAML object in ${configPath}`);
+    }
+    if (!parsed.watch || typeof parsed.watch !== 'string') {
+        throw new Error(`Config error: 'watch' must be a string path (e.g. "./docs")`);
+    }
+    if (!Array.isArray(parsed.triggers) || parsed.triggers.length === 0) {
+        throw new Error(`Config error: 'triggers' must be a non-empty array`);
+    }
+    const triggers = [];
+    for (let i = 0; i < parsed.triggers.length; i++) {
+        const t = parsed.triggers[i];
+        if (!t.name || typeof t.name !== 'string') {
+            throw new Error(`Config error: trigger[${i}] must have a 'name' string`);
+        }
+        if (!t.match || typeof t.match !== 'object') {
+            throw new Error(`Config error: trigger '${t.name}' must have a 'match' object`);
+        }
+        if (!t.run || typeof t.run !== 'string') {
+            throw new Error(`Config error: trigger '${t.name}' must have a 'run' string`);
+        }
+        const match = {};
+        if (t.match.path)
+            match.path = String(t.match.path);
+        if (t.match.frontmatter)
+            match.frontmatter = t.match.frontmatter;
+        if (t.match.frontmatter_changed) {
+            if (!Array.isArray(t.match.frontmatter_changed)) {
+                throw new Error(`Config error: trigger '${t.name}' frontmatter_changed must be an array`);
+            }
+            match.frontmatter_changed = t.match.frontmatter_changed.map(String);
+        }
+        if (t.match.tags) {
+            if (!Array.isArray(t.match.tags)) {
+                throw new Error(`Config error: trigger '${t.name}' tags must be an array`);
+            }
+            match.tags = t.match.tags.map(String);
+        }
+        triggers.push({ name: t.name, match, run: t.run });
+    }
+    // Resolve watch path relative to config file directory
+    const configDir = (0, path_1.dirname)(configPath);
+    const watchPath = (0, path_1.resolve)(configDir, parsed.watch);
+    return { watch: watchPath, triggers };
+}
+function generateDefaultConfig() {
+    return `# md-pipe configuration
+# docs: https://github.com/safetnsr/md-pipe
+
+watch: ./docs
+
+triggers:
+  - name: publish
+    match:
+      path: "posts/**"
+      frontmatter:
+        status: publish
+    run: "echo Publishing $FILE"
+
+  - name: reindex
+    match:
+      frontmatter_changed:
+        - title
+        - tags
+        - category
+    run: "echo Reindexing $FILE — changed fields: $DIFF"
+
+  - name: urgent-notify
+    match:
+      tags:
+        - urgent
+    run: "echo URGENT: $FILE needs attention"
+`;
+}

package/dist/core/matcher.d.ts

@@ -0,0 +1,26 @@
+import { TriggerDef } from './config.js';
+export interface FileState {
+    filePath: string;
+    relativePath: string;
+    content: string;
+    frontmatter: Record<string, unknown>;
+    tags: string[];
+}
+export interface MatchResult {
+    trigger: TriggerDef;
+    file: FileState;
+    diff: Record<string, {
+        old: unknown;
+        new: unknown;
+    }> | null;
+}
+export declare function parseMarkdownFile(filePath: string, relativePath: string): FileState;
+export declare function parseMarkdownContent(content: string, filePath: string, relativePath: string): FileState;
+export declare function matchPath(relativePath: string, pattern: string): boolean;
+export declare function matchFrontmatter(frontmatter: Record<string, unknown>, expected: Record<string, unknown>): boolean;
+export declare function matchTags(fileTags: string[], requiredTags: string[]): boolean;
+export declare function computeFrontmatterDiff(oldFm: Record<string, unknown>, newFm: Record<string, unknown>, watchFields: string[]): Record<string, {
+    old: unknown;
+    new: unknown;
+}> | null;
+export declare function evaluateTrigger(trigger: TriggerDef, file: FileState, previousFrontmatter?: Record<string, unknown>): MatchResult | null;

package/dist/core/matcher.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMarkdownFile = parseMarkdownFile;
+exports.parseMarkdownContent = parseMarkdownContent;
+exports.matchPath = matchPath;
+exports.matchFrontmatter = matchFrontmatter;
+exports.matchTags = matchTags;
+exports.computeFrontmatterDiff = computeFrontmatterDiff;
+exports.evaluateTrigger = evaluateTrigger;
+const micromatch_1 = __importDefault(require("micromatch"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const fs_1 = require("fs");
+function parseMarkdownFile(filePath, relativePath) {
+    const raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    return parseMarkdownContent(raw, filePath, relativePath);
+}
+function parseMarkdownContent(content, filePath, relativePath) {
+    let frontmatter = {};
+    let tags = [];
+    try {
+        const parsed = (0, gray_matter_1.default)(content);
+        frontmatter = parsed.data || {};
+        // Extract tags from frontmatter
+        if (Array.isArray(frontmatter.tags)) {
+            tags = frontmatter.tags.map(String);
+        }
+    }
+    catch {
+        // File has no valid frontmatter — that's fine
+    }
+    return { filePath, relativePath, content, frontmatter, tags };
+}
+function matchPath(relativePath, pattern) {
+    return micromatch_1.default.isMatch(relativePath, pattern);
+}
+function matchFrontmatter(frontmatter, expected) {
+    for (const [key, val] of Object.entries(expected)) {
+        const actual = frontmatter[key];
+        if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+            if (typeof actual !== 'object' || actual === null || Array.isArray(actual))
+                return false;
+            if (!matchFrontmatter(actual, val))
+                return false;
+        }
+        else if (Array.isArray(val)) {
+            if (!Array.isArray(actual))
+                return false;
+            // Check that expected array is a subset of actual
+            for (const item of val) {
+                if (!actual.includes(item))
+                    return false;
+            }
+        }
+        else {
+            // Loose equality for string/number comparison
+            if (String(actual) !== String(val))
+                return false;
+        }
+    }
+    return true;
+}
+function matchTags(fileTags, requiredTags) {
+    const normalized = fileTags.map(t => t.replace(/^#/, '').toLowerCase());
+    return requiredTags.every(tag => {
+        const norm = tag.replace(/^#/, '').toLowerCase();
+        return normalized.includes(norm);
+    });
+}
+function computeFrontmatterDiff(oldFm, newFm, watchFields) {
+    const diff = {};
+    for (const field of watchFields) {
+        const oldVal = oldFm[field];
+        const newVal = newFm[field];
+        if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+            diff[field] = { old: oldVal ?? null, new: newVal ?? null };
+        }
+    }
+    return Object.keys(diff).length > 0 ? diff : null;
+}
+function evaluateTrigger(trigger, file, previousFrontmatter) {
+    const { match } = trigger;
+    let diff = null;
+    // Check path pattern
+    if (match.path) {
+        if (!matchPath(file.relativePath, match.path))
+            return null;
+    }
+    // Check frontmatter values
+    if (match.frontmatter) {
+        if (!matchFrontmatter(file.frontmatter, match.frontmatter))
+            return null;
+    }
+    // Check tags
+    if (match.tags) {
+        if (!matchTags(file.tags, match.tags))
+            return null;
+    }
+    // Check frontmatter_changed (requires previous state)
+    if (match.frontmatter_changed) {
+        if (!previousFrontmatter) {
+            // No previous state — treat as "all fields changed" (new file)
+            diff = {};
+            for (const field of match.frontmatter_changed) {
+                if (file.frontmatter[field] !== undefined) {
+                    diff[field] = { old: null, new: file.frontmatter[field] };
+                }
+            }
+            if (Object.keys(diff).length === 0)
+                return null;
+        }
+        else {
+            diff = computeFrontmatterDiff(previousFrontmatter, file.frontmatter, match.frontmatter_changed);
+            if (!diff)
+                return null;
+        }
+    }
+    return { trigger, file, diff };
+}

package/dist/core/once.d.ts

@@ -0,0 +1,9 @@
+import { MdPipeConfig } from './config.js';
+import { RunResult } from './runner.js';
+export interface OnceResult {
+    total: number;
+    matched: number;
+    actions: RunResult[];
+    errors: string[];
+}
+export declare function runOnce(config: MdPipeConfig, dryRun?: boolean): OnceResult;

package/dist/core/once.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOnce = runOnce;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const matcher_js_1 = require("./matcher.js");
+const runner_js_1 = require("./runner.js");
+function findMarkdownFiles(dir) {
+    const results = [];
+    function walk(current) {
+        const entries = (0, fs_1.readdirSync)(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = (0, path_1.resolve)(current, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+function runOnce(config, dryRun = false) {
+    const files = findMarkdownFiles(config.watch);
+    const actions = [];
+    const errors = [];
+    let matched = 0;
+    for (const filePath of files) {
+        const relativePath = (0, path_1.relative)(config.watch, filePath);
+        let file;
+        try {
+            file = (0, matcher_js_1.parseMarkdownFile)(filePath, relativePath);
+        }
+        catch (err) {
+            errors.push(`Error parsing ${filePath}: ${err}`);
+            continue;
+        }
+        for (const trigger of config.triggers) {
+            // For once mode, skip frontmatter_changed triggers (no previous state to diff)
+            if (trigger.match.frontmatter_changed)
+                continue;
+            const match = (0, matcher_js_1.evaluateTrigger)(trigger, file);
+            if (match) {
+                matched++;
+                const result = (0, runner_js_1.executeAction)(match, dryRun);
+                actions.push(result);
+            }
+        }
+    }
+    return { total: files.length, matched, actions, errors };
+}

package/dist/core/runner.d.ts

@@ -0,0 +1,11 @@
+import { MatchResult } from './matcher.js';
+export interface RunResult {
+    triggerName: string;
+    filePath: string;
+    command: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}
+export declare function executeAction(match: MatchResult, dryRun?: boolean): RunResult;

package/dist/core/runner.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAction = executeAction;
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+function interpolateCommand(template, match) {
+    const { file, diff } = match;
+    const dir = (0, path_1.dirname)(file.filePath);
+    const tags = file.tags.join(',');
+    const fmJson = JSON.stringify(file.frontmatter);
+    const diffJson = diff ? JSON.stringify(diff) : '{}';
+    return template
+        .replace(/\$FILE/g, file.filePath)
+        .replace(/\$DIR/g, dir)
+        .replace(/\$BASENAME/g, (0, path_1.basename)(file.filePath))
+        .replace(/\$RELATIVE/g, file.relativePath)
+        .replace(/\$FRONTMATTER/g, fmJson)
+        .replace(/\$DIFF/g, diffJson)
+        .replace(/\$TAGS/g, tags);
+}
+function executeAction(match, dryRun = false) {
+    const command = interpolateCommand(match.trigger.run, match);
+    const triggerName = match.trigger.name;
+    const filePath = match.file.filePath;
+    if (dryRun) {
+        return {
+            triggerName,
+            filePath,
+            command,
+            exitCode: 0,
+            stdout: '[dry run]',
+            stderr: '',
+            durationMs: 0,
+        };
+    }
+    const start = Date.now();
+    try {
+        const stdout = (0, child_process_1.execSync)(command, {
+            cwd: (0, path_1.dirname)(match.file.filePath),
+            timeout: 30000,
+            encoding: 'utf-8',
+            env: {
+                ...process.env,
+                FILE: match.file.filePath,
+                DIR: (0, path_1.dirname)(match.file.filePath),
+                BASENAME: (0, path_1.basename)(match.file.filePath),
+                RELATIVE: match.file.relativePath,
+                FRONTMATTER: JSON.stringify(match.file.frontmatter),
+                DIFF: match.diff ? JSON.stringify(match.diff) : '{}',
+                TAGS: match.file.tags.join(','),
+            },
+        });
+        return {
+            triggerName,
+            filePath,
+            command,
+            exitCode: 0,
+            stdout: stdout.trim(),
+            stderr: '',
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        return {
+            triggerName,
+            filePath,
+            command,
+            exitCode: err.status ?? 1,
+            stdout: err.stdout?.trim() ?? '',
+            stderr: err.stderr?.trim() ?? '',
+            durationMs: Date.now() - start,
+        };
+    }
+}

package/dist/core/test-file.d.ts

@@ -0,0 +1,12 @@
+import { MdPipeConfig } from './config.js';
+export interface TestResult {
+    filePath: string;
+    relativePath: string;
+    frontmatter: Record<string, unknown>;
+    tags: string[];
+    matches: Array<{
+        triggerName: string;
+        reason: string;
+    }>;
+}
+export declare function testFile(config: MdPipeConfig, filePath: string): TestResult;

package/dist/core/test-file.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testFile = testFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const matcher_js_1 = require("./matcher.js");
+function testFile(config, filePath) {
+    const absPath = (0, path_1.resolve)(filePath);
+    if (!(0, fs_1.existsSync)(absPath)) {
+        throw new Error(`File not found: ${absPath}`);
+    }
+    const relativePath = (0, path_1.relative)(config.watch, absPath);
+    const file = (0, matcher_js_1.parseMarkdownFile)(absPath, relativePath);
+    const matches = [];
+    for (const trigger of config.triggers) {
+        // Skip frontmatter_changed in test mode (no previous state)
+        if (trigger.match.frontmatter_changed) {
+            matches.push({
+                triggerName: trigger.name,
+                reason: `frontmatter_changed: would fire on changes to [${trigger.match.frontmatter_changed.join(', ')}] (no previous state to diff in test mode)`,
+            });
+            continue;
+        }
+        const result = (0, matcher_js_1.evaluateTrigger)(trigger, file);
+        if (result) {
+            const reasons = [];
+            if (trigger.match.path)
+                reasons.push(`path matches "${trigger.match.path}"`);
+            if (trigger.match.frontmatter)
+                reasons.push(`frontmatter matches ${JSON.stringify(trigger.match.frontmatter)}`);
+            if (trigger.match.tags)
+                reasons.push(`has tags [${trigger.match.tags.join(', ')}]`);
+            matches.push({
+                triggerName: trigger.name,
+                reason: reasons.join(' + ') || 'all conditions matched',
+            });
+        }
+    }
+    return {
+        filePath: absPath,
+        relativePath,
+        frontmatter: file.frontmatter,
+        tags: file.tags,
+        matches,
+    };
+}

package/dist/core/watcher.d.ts

@@ -0,0 +1,20 @@
+import { EventEmitter } from 'events';
+import { MdPipeConfig } from './config.js';
+import { MatchResult } from './matcher.js';
+import { RunResult } from './runner.js';
+export interface WatcherEvents {
+    match: (result: MatchResult) => void;
+    action: (result: RunResult) => void;
+    error: (error: Error, filePath?: string) => void;
+    ready: () => void;
+}
+export declare class MdPipeWatcher extends EventEmitter {
+    private config;
+    private fsWatcher;
+    private frontmatterCache;
+    private dryRun;
+    constructor(config: MdPipeConfig, dryRun?: boolean);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleFile;
+}

package/dist/core/watcher.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MdPipeWatcher = void 0;
+const chokidar_1 = require("chokidar");
+const path_1 = require("path");
+const events_1 = require("events");
+const matcher_js_1 = require("./matcher.js");
+const runner_js_1 = require("./runner.js");
+class MdPipeWatcher extends events_1.EventEmitter {
+    config;
+    fsWatcher = null;
+    frontmatterCache = new Map();
+    dryRun;
+    constructor(config, dryRun = false) {
+        super();
+        this.config = config;
+        this.dryRun = dryRun;
+    }
+    async start() {
+        const watchDir = this.config.watch;
+        this.fsWatcher = (0, chokidar_1.watch)('**/*.md', {
+            cwd: watchDir,
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 200,
+                pollInterval: 50,
+            },
+        });
+        this.fsWatcher.on('add', (relPath) => this.handleFile(relPath, 'add'));
+        this.fsWatcher.on('change', (relPath) => this.handleFile(relPath, 'change'));
+        this.fsWatcher.on('ready', () => this.emit('ready'));
+        this.fsWatcher.on('error', (err) => this.emit('error', err instanceof Error ? err : new Error(String(err))));
+    }
+    async stop() {
+        if (this.fsWatcher) {
+            await this.fsWatcher.close();
+            this.fsWatcher = null;
+        }
+    }
+    handleFile(relativePath, event) {
+        const absolutePath = (0, path_1.resolve)(this.config.watch, relativePath);
+        let file;
+        try {
+            file = (0, matcher_js_1.parseMarkdownFile)(absolutePath, relativePath);
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)), absolutePath);
+            return;
+        }
+        const previousFm = this.frontmatterCache.get(relativePath);
+        // Run through triggers
+        for (const trigger of this.config.triggers) {
+            const match = (0, matcher_js_1.evaluateTrigger)(trigger, file, previousFm);
+            if (match) {
+                this.emit('match', match);
+                const result = (0, runner_js_1.executeAction)(match, this.dryRun);
+                this.emit('action', result);
+            }
+        }
+        // Cache frontmatter for diff tracking
+        this.frontmatterCache.set(relativePath, { ...file.frontmatter });
+    }
+}
+exports.MdPipeWatcher = MdPipeWatcher;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@safetnsr/md-pipe",
+  "version": "0.1.0",
+  "description": "Event-driven automation for markdown directories. entr watches files. md-pipe understands them.",
+  "main": "./dist/cli.js",
+  "bin": {
+    "md-pipe": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test build/tests/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "markdown",
+    "frontmatter",
+    "automation",
+    "file-watcher",
+    "cli",
+    "ai",
+    "agents",
+    "obsidian",
+    "docs-as-code",
+    "pipeline"
+  ],
+  "author": "safetnsr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/safetnsr/md-pipe.git"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "chokidar": "^4.0.3",
+    "gray-matter": "^4.0.3",
+    "micromatch": "^4.0.8",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}