praxis-mcp 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# Praxis MCP Server
+
+MCP (Model Context Protocol) server for the [Praxis](https://github.com/LuisFaxas/praxis) AI development methodology. Gives any MCP-compatible AI agent structured tools for session management, work order lifecycle, context chain operations, validation, and project scaffolding.
+
+## Quick Start
+
+```bash
+cd praxis-mcp
+npm install
+npm run build
+```
+
+### Register with Claude Code
+
+Add to `.mcp.json` at your project root:
+
+```json
+{
+  "mcpServers": {
+    "praxis": {
+      "command": "node",
+      "args": ["/absolute/path/to/praxis-mcp/build/index.js"],
+      "env": {
+        "PRAXIS_PROJECT_DIR": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+### Register with Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.praxis]
+command = "node"
+args = ["/absolute/path/to/praxis-mcp/build/index.js"]
+
+[mcp_servers.praxis.env]
+PRAXIS_PROJECT_DIR = "/absolute/path/to/your/project"
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+## Tools (12)
+
+All tools are prefixed as `mcp__praxis__<tool>` by the MCP protocol.
+
+### Session Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `session_start` | Read the full context chain + pending work orders in canonical Praxis order. Returns a complete project state snapshot. |
+| `session_end` | Validate that context documents were updated during this session. Returns a compliance report. |
+| `detect_project` | Detect adoption tier, operational mode, configured providers, and structural completeness. |
+
+### Context Chain
+
+| Tool | Description |
+|------|-------------|
+| `read_context` | Read one or all context documents (SOT, capsule, checkpoint) with metadata. |
+| `update_capsule` | Patch the Context Capsule with structured fields (active task, session summary, next steps). |
+| `update_checkpoint` | Append a milestone to the Checkpoint document. Auto-numbers the entry. |
+
+### Work Orders
+
+| Tool | Description |
+|------|-------------|
+| `list_work_orders` | List work orders with status/agent filters. Handles solo and triangle modes. |
+| `read_work_order` | Read and parse a specific work order by number or filename. |
+| `create_work_order` | Create a new work order with naming convention enforcement and auto-numbering. |
+| `complete_work_order` | Validate all acceptance criteria are checked, then move WO to executed/. |
+
+### Validation
+
+| Tool | Description |
+|------|-------------|
+| `lint` | Run praxis-lint.sh (50 checks, 7 categories) and return structured JSON findings. |
+
+### Scaffolding
+
+| Tool | Description |
+|------|-------------|
+| `scaffold` | Create the Praxis dev/ folder structure based on tier and mode. Safe to run multiple times. |
+
+## Configuration
+
+The server reads `PRAXIS_PROJECT_DIR` from the environment to determine the project root. All tools accept an optional `project_path` parameter to override this default.
+
+## Architecture
+
+- **Stateless**: No in-memory state between calls. The filesystem is the state.
+- **Provider-agnostic**: Uses `*_INIT.md` globs and `wo_*/` patterns, never hardcoded provider names.
+- **Zero dependencies**: Beyond the MCP SDK and Zod (both required by the protocol).
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerSessionTools } from "./tools/session.js";
+import { registerContextTools } from "./tools/context.js";
+import { registerWorkOrderTools } from "./tools/work-orders.js";
+import { registerLintTool } from "./tools/lint.js";
+import { registerScaffoldTool } from "./tools/scaffold.js";
+const server = new McpServer({
+    name: "praxis",
+    version: "1.0.0",
+});
+// Register all tool categories
+registerSessionTools(server);
+registerContextTools(server);
+registerWorkOrderTools(server);
+registerLintTool(server);
+registerScaffoldTool(server);
+// Start the server with stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,+BAA+B;AAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACzB,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAE7B,wCAAwC;AACxC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/build/lib/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Praxis MCP — Constants
+ *
+ * Tier folder maps, core document paths, WO template, naming patterns.
+ * All paths are relative to the project's dev/ folder.
+ */
+export declare const CORE_DOCS: readonly ["source_of_truth.md", "context_capsule.md", "checkpoint.md"];
+export declare const TIER_FOLDERS: Record<string, string[]>;
+export declare const PRAXIS_INIT_FILENAME = "PRAXIS_INIT.md";
+export declare const INIT_FILE_SUFFIX = "_INIT.md";
+export declare const NAMING_REGEX: RegExp;
+export declare const WO_TEMPLATE = "# Work Order: {TITLE}\n\n- **WO#:** {NUMBER}\n- **Date Created:** {DATE}\n- **Status:** Pending\n- **Assigned To:** {ASSIGNED_TO}\n- **Priority:** {PRIORITY}\n\n## Description\n\n{DESCRIPTION}\n\n## Acceptance Criteria\n\n{CRITERIA}\n\n## Notes\n\n";
+export declare const CAPSULE_SECTIONS: readonly ["Active Task", "In-Progress Notes", "Critical Rules", "Key Workspace Paths", "Last Session Summary"];
+export declare const CHECKPOINT_TABLE_HEADER = "| # | Milestone | Date | Status |";
+export declare const CHECKPOINT_TABLE_SEPARATOR = "|---|-----------|------|--------|";
+//# sourceMappingURL=constants.d.ts.map

package/build/lib/constants.js

@@ -0,0 +1,88 @@
+/**
+ * Praxis MCP — Constants
+ *
+ * Tier folder maps, core document paths, WO template, naming patterns.
+ * All paths are relative to the project's dev/ folder.
+ */
+// Core context documents (always required, regardless of tier)
+export const CORE_DOCS = [
+    "source_of_truth.md",
+    "context_capsule.md",
+    "checkpoint.md",
+];
+// Folders required at each tier level
+export const TIER_FOLDERS = {
+    starter: [
+        "work-orders",
+        "work-orders/executed",
+    ],
+    standard: [
+        "work-orders",
+        "work-orders/executed",
+        "research/active",
+        "research/archive",
+        "planning/master-plan/draft",
+        "planning/master-plan/approved",
+        "commands/active",
+        "commands/executed",
+    ],
+    full: [
+        "work-orders",
+        "work-orders/executed",
+        "research/active",
+        "research/archive",
+        "planning/master-plan/draft",
+        "planning/master-plan/approved",
+        "commands/active",
+        "commands/executed",
+        "audit/current",
+        "audit/legacy",
+        "reports/draft/html",
+        "reports/draft/written",
+        "reports/published/html",
+        "reports/published/written",
+        "design/audit/screenshots",
+        "design/language",
+        "design/resources",
+        "archive",
+        "private",
+    ],
+};
+// The generic init file name (excluded from provider counting)
+export const PRAXIS_INIT_FILENAME = "PRAXIS_INIT.md";
+// Init file suffix for detecting provider-specific inits
+export const INIT_FILE_SUFFIX = "_INIT.md";
+// Work order file naming pattern: {number}_{YYYY-MM-DD}_{DESCRIPTION}.md
+export const NAMING_REGEX = /^(\d+)_(\d{4}-\d{2}-\d{2})_(.+)\.md$/;
+// Work order template used by create_work_order
+export const WO_TEMPLATE = `# Work Order: {TITLE}
+
+- **WO#:** {NUMBER}
+- **Date Created:** {DATE}
+- **Status:** Pending
+- **Assigned To:** {ASSIGNED_TO}
+- **Priority:** {PRIORITY}
+
+## Description
+
+{DESCRIPTION}
+
+## Acceptance Criteria
+
+{CRITERIA}
+
+## Notes
+
+`;
+// Context capsule section headers (used for section-aware updates)
+export const CAPSULE_SECTIONS = [
+    "Active Task",
+    "In-Progress Notes",
+    "Critical Rules",
+    "Key Workspace Paths",
+    "Last Session Summary",
+];
+// Checkpoint milestone table header
+export const CHECKPOINT_TABLE_HEADER = "| # | Milestone | Date | Status |";
+export const CHECKPOINT_TABLE_SEPARATOR = "|---|-----------|------|--------|";
+//# sourceMappingURL=constants.js.map

package/build/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,oBAAoB;IACpB,oBAAoB;IACpB,eAAe;CACP,CAAC;AAEX,sCAAsC;AACtC,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,OAAO,EAAE;QACP,aAAa;QACb,sBAAsB;KACvB;IACD,QAAQ,EAAE;QACR,aAAa;QACb,sBAAsB;QACtB,iBAAiB;QACjB,kBAAkB;QAClB,4BAA4B;QAC5B,+BAA+B;QAC/B,iBAAiB;QACjB,mBAAmB;KACpB;IACD,IAAI,EAAE;QACJ,aAAa;QACb,sBAAsB;QACtB,iBAAiB;QACjB,kBAAkB;QAClB,4BAA4B;QAC5B,+BAA+B;QAC/B,iBAAiB;QACjB,mBAAmB;QACnB,eAAe;QACf,cAAc;QACd,oBAAoB;QACpB,uBAAuB;QACvB,wBAAwB;QACxB,2BAA2B;QAC3B,0BAA0B;QAC1B,iBAAiB;QACjB,kBAAkB;QAClB,SAAS;QACT,SAAS;KACV;CACF,CAAC;AAEF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAErD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,YAAY,GAAG,sCAAsC,CAAC;AAEnE,gDAAgD;AAChD,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;CAkB1B,CAAC;AAEF,mEAAmE;AACnE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,aAAa;IACb,mBAAmB;IACnB,gBAAgB;IAChB,qBAAqB;IACrB,sBAAsB;CACd,CAAC;AAEX,oCAAoC;AACpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,mCAAmC,CAAC;AAC3E,MAAM,CAAC,MAAM,0BAA0B,GAAG,mCAAmC,CAAC"}

package/build/lib/detection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Praxis MCP — Project Detection
+ *
+ * Detects adoption tier, operational mode, and configured providers.
+ * Ports the detection logic from praxis-lint.sh (lines 212-245) to TypeScript.
+ */
+export type Tier = "starter" | "standard" | "full" | "none";
+export type Mode = "solo" | "triangle";
+export interface ProjectDetection {
+    hasDevFolder: boolean;
+    tier: Tier;
+    mode: Mode;
+    providers: string[];
+    coreDocs: {
+        sourceOfTruth: boolean;
+        contextCapsule: boolean;
+        checkpoint: boolean;
+    };
+    hasLinter: boolean;
+}
+/**
+ * Detect the project's adoption tier based on which folders exist.
+ * Matches praxis-lint.sh detect_tier() exactly.
+ */
+export declare function detectTier(projectPath: string): Promise<Tier>;
+/**
+ * Detect solo vs triangle mode by counting provider init files.
+ * Matches praxis-lint.sh detect_triangle_mode() exactly.
+ *
+ * Logic: count *_INIT.md files in dev/init/, excluding PRAXIS_INIT.md.
+ * 2+ provider init files = triangle mode.
+ */
+export declare function detectMode(projectPath: string): Promise<Mode>;
+/**
+ * Detect which AI providers are configured by reading init file names.
+ * Extracts the provider name from the filename pattern: {PROVIDER}_INIT.md
+ */
+export declare function detectProviders(projectPath: string): Promise<string[]>;
+/**
+ * Full project detection — combines tier, mode, providers, and core doc checks.
+ */
+export declare function detectProject(projectPath: string): Promise<ProjectDetection>;
+//# sourceMappingURL=detection.d.ts.map

package/build/lib/detection.js

@@ -0,0 +1,123 @@
+/**
+ * Praxis MCP — Project Detection
+ *
+ * Detects adoption tier, operational mode, and configured providers.
+ * Ports the detection logic from praxis-lint.sh (lines 212-245) to TypeScript.
+ */
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+import { isDirectory, fileExists, resolveDevPath } from "./fs-helpers.js";
+import { PRAXIS_INIT_FILENAME, INIT_FILE_SUFFIX } from "./constants.js";
+/**
+ * Detect the project's adoption tier based on which folders exist.
+ * Matches praxis-lint.sh detect_tier() exactly.
+ */
+export async function detectTier(projectPath) {
+    const dev = resolveDevPath(projectPath);
+    if (!(await isDirectory(dev)))
+        return "none";
+    const hasAudit = await isDirectory(join(dev, "audit"));
+    const hasReports = await isDirectory(join(dev, "reports"));
+    const hasDesign = await isDirectory(join(dev, "design"));
+    const hasResearch = await isDirectory(join(dev, "research"));
+    const hasPlanning = await isDirectory(join(dev, "planning"));
+    if (hasAudit && hasReports && hasDesign)
+        return "full";
+    if (hasResearch && hasPlanning)
+        return "standard";
+    return "starter";
+}
+/**
+ * Detect solo vs triangle mode by counting provider init files.
+ * Matches praxis-lint.sh detect_triangle_mode() exactly.
+ *
+ * Logic: count *_INIT.md files in dev/init/, excluding PRAXIS_INIT.md.
+ * 2+ provider init files = triangle mode.
+ */
+export async function detectMode(projectPath) {
+    const initDir = join(resolveDevPath(projectPath), "init");
+    if (!(await isDirectory(initDir)))
+        return "solo";
+    let providerCount = 0;
+    try {
+        const entries = await readdir(initDir);
+        for (const entry of entries) {
+            if (!entry.endsWith(INIT_FILE_SUFFIX))
+                continue;
+            if (entry === PRAXIS_INIT_FILENAME)
+                continue;
+            providerCount++;
+        }
+    }
+    catch {
+        return "solo";
+    }
+    return providerCount >= 2 ? "triangle" : "solo";
+}
+/**
+ * Detect which AI providers are configured by reading init file names.
+ * Extracts the provider name from the filename pattern: {PROVIDER}_INIT.md
+ */
+export async function detectProviders(projectPath) {
+    const initDir = join(resolveDevPath(projectPath), "init");
+    if (!(await isDirectory(initDir)))
+        return [];
+    const providers = [];
+    try {
+        const entries = await readdir(initDir);
+        for (const entry of entries) {
+            if (!entry.endsWith(INIT_FILE_SUFFIX))
+                continue;
+            if (entry === PRAXIS_INIT_FILENAME)
+                continue;
+            // Extract provider name: "CLAUDE_INIT.md" -> "claude"
+            const name = entry.replace(INIT_FILE_SUFFIX, "").toLowerCase();
+            providers.push(name);
+        }
+    }
+    catch {
+        // Return empty on error
+    }
+    return providers;
+}
+/**
+ * Full project detection — combines tier, mode, providers, and core doc checks.
+ */
+export async function detectProject(projectPath) {
+    const dev = resolveDevPath(projectPath);
+    const hasDevFolder = await isDirectory(dev);
+    if (!hasDevFolder) {
+        return {
+            hasDevFolder: false,
+            tier: "none",
+            mode: "solo",
+            providers: [],
+            coreDocs: { sourceOfTruth: false, contextCapsule: false, checkpoint: false },
+            hasLinter: false,
+        };
+    }
+    const [tier, mode, providers] = await Promise.all([
+        detectTier(projectPath),
+        detectMode(projectPath),
+        detectProviders(projectPath),
+    ]);
+    const [sotExists, capsuleExists, checkpointExists, linterExists] = await Promise.all([
+        fileExists(join(dev, "source_of_truth.md")),
+        fileExists(join(dev, "context_capsule.md")),
+        fileExists(join(dev, "checkpoint.md")),
+        fileExists(join(projectPath, ".praxis", "praxis-lint.sh")),
+    ]);
+    return {
+        hasDevFolder: true,
+        tier,
+        mode,
+        providers,
+        coreDocs: {
+            sourceOfTruth: sotExists,
+            contextCapsule: capsuleExists,
+            checkpoint: checkpointExists,
+        },
+        hasLinter: linterExists,
+    };
+}
+//# sourceMappingURL=detection.js.map

package/build/lib/detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.js","sourceRoot":"","sources":["../../src/lib/detection.ts"],"names":[],"mappings":"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"}

package/build/lib/fs-helpers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Praxis MCP — Filesystem Helpers
+ *
+ * Safe file operations that never throw on missing files.
+ * All functions are stateless and work with absolute paths.
+ */
+/**
+ * Read a file safely. Returns null if the file doesn't exist or can't be read.
+ */
+export declare function readFileSafe(filePath: string): Promise<string | null>;
+/**
+ * Write a file safely, creating parent directories if needed.
+ */
+export declare function writeFileSafe(filePath: string, content: string): Promise<void>;
+/**
+ * Get file age in days. Returns null if the file doesn't exist.
+ */
+export declare function getFileAgeDays(filePath: string): Promise<number | null>;
+/**
+ * Check if a file or directory exists.
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Check if a path is a directory.
+ */
+export declare function isDirectory(filePath: string): Promise<boolean>;
+/**
+ * List markdown files in a directory. Returns empty array if dir doesn't exist.
+ * Skips files starting with "0_" (reserved for READMEs/examples).
+ */
+export declare function listMarkdownFiles(dirPath: string, options?: {
+    includeExamples?: boolean;
+}): Promise<string[]>;
+/**
+ * List subdirectories matching a pattern in a directory.
+ */
+export declare function listSubdirectories(dirPath: string, prefix?: string): Promise<string[]>;
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ * Returns true if the directory was created, false if it already existed.
+ */
+export declare function ensureDir(dirPath: string): Promise<boolean>;
+/**
+ * Move a file from one path to another. Creates target directory if needed.
+ */
+export declare function moveFile(fromPath: string, toPath: string): Promise<void>;
+/**
+ * Get file size in bytes. Returns 0 if file doesn't exist.
+ */
+export declare function getFileSize(filePath: string): Promise<number>;
+/**
+ * Check if a file was modified today (local timezone).
+ */
+export declare function wasModifiedToday(filePath: string): Promise<boolean>;
+/**
+ * Resolve the dev/ folder path from a project root.
+ */
+export declare function resolveDevPath(projectPath: string): string;
+//# sourceMappingURL=fs-helpers.d.ts.map

package/build/lib/fs-helpers.js

@@ -0,0 +1,151 @@
+/**
+ * Praxis MCP — Filesystem Helpers
+ *
+ * Safe file operations that never throw on missing files.
+ * All functions are stateless and work with absolute paths.
+ */
+import { readFile, writeFile, stat, readdir, mkdir, rename } from "node:fs/promises";
+import { join, dirname } from "node:path";
+/**
+ * Read a file safely. Returns null if the file doesn't exist or can't be read.
+ */
+export async function readFileSafe(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a file safely, creating parent directories if needed.
+ */
+export async function writeFileSafe(filePath, content) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, "utf-8");
+}
+/**
+ * Get file age in days. Returns null if the file doesn't exist.
+ */
+export async function getFileAgeDays(filePath) {
+    try {
+        const stats = await stat(filePath);
+        const now = Date.now();
+        const mtime = stats.mtimeMs;
+        return Math.floor((now - mtime) / (1000 * 60 * 60 * 24));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a file or directory exists.
+ */
+export async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a path is a directory.
+ */
+export async function isDirectory(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List markdown files in a directory. Returns empty array if dir doesn't exist.
+ * Skips files starting with "0_" (reserved for READMEs/examples).
+ */
+export async function listMarkdownFiles(dirPath, options = {}) {
+    try {
+        const entries = await readdir(dirPath);
+        return entries.filter((f) => {
+            if (!f.endsWith(".md"))
+                return false;
+            if (!options.includeExamples && f.startsWith("0_"))
+                return false;
+            return true;
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List subdirectories matching a pattern in a directory.
+ */
+export async function listSubdirectories(dirPath, prefix) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && (!prefix || e.name.startsWith(prefix)))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ * Returns true if the directory was created, false if it already existed.
+ */
+export async function ensureDir(dirPath) {
+    const existed = await isDirectory(dirPath);
+    if (!existed) {
+        await mkdir(dirPath, { recursive: true });
+        return true;
+    }
+    return false;
+}
+/**
+ * Move a file from one path to another. Creates target directory if needed.
+ */
+export async function moveFile(fromPath, toPath) {
+    await mkdir(dirname(toPath), { recursive: true });
+    await rename(fromPath, toPath);
+}
+/**
+ * Get file size in bytes. Returns 0 if file doesn't exist.
+ */
+export async function getFileSize(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Check if a file was modified today (local timezone).
+ */
+export async function wasModifiedToday(filePath) {
+    try {
+        const stats = await stat(filePath);
+        const mtime = new Date(stats.mtimeMs);
+        const today = new Date();
+        return (mtime.getFullYear() === today.getFullYear() &&
+            mtime.getMonth() === today.getMonth() &&
+            mtime.getDate() === today.getDate());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the dev/ folder path from a project root.
+ */
+export function resolveDevPath(projectPath) {
+    return join(projectPath, "dev");
+}
+//# sourceMappingURL=fs-helpers.js.map

package/build/lib/fs-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-helpers.js","sourceRoot":"","sources":["../../src/lib/fs-helpers.ts"],"names":[],"mappings":"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"}

package/build/lib/naming.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Praxis MCP — Naming Utilities
+ *
+ * File naming convention enforcement and work order numbering.
+ * Convention: {number}_{YYYY-MM-DD}_{DESCRIPTION}.{ext}
+ */
+/**
+ * Get today's date in ISO format (YYYY-MM-DD).
+ */
+export declare function todayISO(): string;
+/**
+ * Convert a title string to UPPER_SNAKE_CASE.
+ * "Fix the authentication bug" -> "FIX_THE_AUTHENTICATION_BUG"
+ */
+export declare function toUpperSnakeCase(title: string): string;
+/**
+ * Determine the next work order number from a list of existing filenames.
+ * Scans for the highest number prefix and returns highest + 1.
+ * Skips 0 (reserved for READMEs/examples). Minimum return is 1.
+ */
+export declare function nextWoNumber(existingFiles: string[]): number;
+/**
+ * Format a filename per Praxis naming convention.
+ * Returns: "{number}_{YYYY-MM-DD}_{DESCRIPTION}.md"
+ */
+export declare function formatFilename(number: number, date: string, description: string): string;
+/**
+ * Validate whether a filename matches the Praxis naming convention.
+ */
+export declare function isValidPraxisFilename(filename: string): boolean;
+/**
+ * Extract the number from a Praxis-convention filename.
+ * Returns null if the filename doesn't match the convention.
+ */
+export declare function extractNumber(filename: string): number | null;
+//# sourceMappingURL=naming.d.ts.map