@way_marks/cli 0.4.0

package/README.md

@@ -0,0 +1,213 @@
+# Waymark
+
+**Control what AI agents can do in your codebase.**
+
+Waymark sits between your team and any AI agent.
+Every file action is intercepted, logged, and checked
+against your policies before it executes.
+Dangerous commands are blocked. Sensitive paths
+require human approval. Everything is reversible.
+
+---
+
+## The Problem
+
+AI agents like Claude Code are powerful.
+They can also write to your .env, run rm -rf,
+or modify your database schema without asking.
+
+You find out after it happens.
+
+## The Solution
+
+Waymark intercepts every action before it runs:
+
+| Agent tries to...          | Waymark does...                        |
+|----------------------------|----------------------------------------|
+| Write to .env              | Blocks it instantly. Logged.           |
+| Run rm -rf                 | Blocks it instantly. Logged.           |
+| Pipe curl to bash          | Blocks it instantly. Logged.           |
+| Modify src/db/schema.ts    | Holds it. Asks for your approval.      |
+| Write to src/              | Allows it. Logged with full rollback.  |
+| Read any file              | Logged with path and content snapshot. |
+
+---
+
+## Install
+
+```bash
+cd your-project
+npx @way_marks/cli init
+npx @way_marks/cli start
+```
+
+Restart Claude Code. Done.
+Waymark is now active in this project.
+
+---
+
+## How It Works
+
+```
+Your Prompt
+    ↓
+Claude Code
+    ↓
+Waymark MCP Server  ← intercepts here
+    ↓
+Policy Engine
+    ↓
+allowed  → executes + logged
+blocked  → stopped + logged
+pending  → held + approval required
+    ↓
+Dashboard: http://localhost:3001
+```
+
+---
+
+## Dashboard
+
+Open **http://localhost:3001** after running
+`npx @way_marks/cli start`.
+
+- See every agent action in real time
+- Approve or reject pending actions
+- Roll back any write with one click
+- Filter by allowed / blocked / pending
+
+---
+
+## Configuration
+
+Edit `waymark.config.json` in your project root:
+
+```json
+{
+  "policies": {
+    "allowedPaths": [
+      "./src/**",
+      "./data/**",
+      "./README.md"
+    ],
+    "blockedPaths": [
+      "./.env",
+      "./.env.*",
+      "./package-lock.json",
+      "/etc/**"
+    ],
+    "blockedCommands": [
+      "rm -rf",
+      "DROP TABLE",
+      "regex:\\|\\s*bash",
+      "regex:\\$\\(curl"
+    ],
+    "requireApproval": [
+      "./src/db/**",
+      "./waymark.config.json"
+    ]
+  }
+}
+```
+
+### Policy Rules
+
+**allowedPaths** — Agent can read and write these.
+Supports glob patterns.
+
+**blockedPaths** — Agent can never touch these.
+Takes priority over allowedPaths.
+
+**blockedCommands** — Bash commands containing
+these strings are blocked. Prefix with `regex:`
+for pattern matching.
+
+**requireApproval** — Actions on these paths are
+held until a human approves from the dashboard.
+
+---
+
+## CLI Commands
+
+```bash
+npx @way_marks/cli init    # Set up Waymark in current project
+npx @way_marks/cli start   # Start dashboard + MCP server (background)
+npx @way_marks/cli stop    # Stop the running servers
+npx @way_marks/cli status  # Check if server is running
+npx @way_marks/cli logs    # View recent actions in terminal
+npx @way_marks/cli logs --pending   # Show only pending actions
+npx @way_marks/cli logs --blocked   # Show only blocked actions
+```
+
+---
+
+## Slack Notifications
+
+Get notified when an agent action needs approval:
+
+```bash
+# Add to .env in your project
+WAYMARK_SLACK_WEBHOOK_URL=https://hooks.slack.com/...
+WAYMARK_SLACK_CHANNEL=#engineering
+WAYMARK_BASE_URL=http://localhost:3001
+```
+
+Create a Slack webhook at:
+api.slack.com/apps → Incoming Webhooks
+
+---
+
+## Works With
+
+- **Claude Code** — native MCP integration,
+  zero configuration after init
+- **Any MCP-compatible agent** — register
+  the Waymark MCP server in your agent config
+- More integrations coming
+
+---
+
+## Requirements
+
+- Node.js 18 or higher
+- Claude Code (for MCP integration)
+- macOS or Linux (Windows support coming)
+
+---
+
+## Roadmap
+
+- [ ] Team approval routing
+  (assign approvals to specific teammates)
+- [ ] Session-level rollback
+  (undo an entire agent run at once)
+- [ ] CLI agent wrapping
+  (waymark run <any-agent-command>)
+- [ ] Proxy mode
+  (drop-in for any OpenAI-compatible agent)
+- [ ] Email notifications
+- [ ] Windows support
+
+---
+
+## Contributing
+
+Waymark is MIT licensed and open to contributions.
+
+1. Fork the repo
+2. Create a feature branch
+3. Open a pull request
+
+Please open an issue before starting large changes.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+Built for developers who want to use AI agents
+seriously — without giving them unsupervised
+access to production systems.

package/dist/commands/init.js

@@ -0,0 +1,325 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const readline = __importStar(require("readline"));
+const child_process_1 = require("child_process");
+const DEFAULT_CONFIG = {
+    version: '1',
+    policies: {
+        allowedPaths: [
+            './src/**',
+            './data/**',
+            './README.md',
+            './CLAUDE.md'
+        ],
+        blockedPaths: [
+            './.env',
+            './.env.*',
+            './package-lock.json',
+            '/etc/**',
+            '/usr/**'
+        ],
+        blockedCommands: [
+            'rm -rf',
+            'DROP TABLE',
+            'DROP DATABASE',
+            'chmod 777',
+            'regex:\\|\\s*bash',
+            'regex:\\|\\s*sh\\b',
+            'regex:\\$\\(curl',
+            'regex:\\$\\(wget',
+            'wget '
+        ],
+        requireApproval: [
+            './src/db/**',
+            './waymark.config.json'
+        ],
+        maxBashOutputBytes: 10000
+    }
+};
+const WAYMARK_MARKER = '<!-- waymark -->';
+function kebabCase(str) {
+    return str
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function generateClaudeMd(projectName, port) {
+    return `---
+# ⚠️ WAYMARK ACTIVE — MANDATORY INSTRUCTIONS
+
+## You are operating under Waymark agent control
+
+Waymark is active in this project (${projectName}).
+All file and shell operations MUST go through
+Waymark MCP tools. No exceptions.
+
+## MANDATORY tool usage
+
+You MUST replace ALL built-in file and shell
+operations with Waymark MCP equivalents:
+
+| Operation              | Built-in (DO NOT USE) | Waymark (ALWAYS USE) |
+|------------------------|-----------------------|----------------------|
+| Write or edit a file   | write_file            | mcp__waymark-${projectName}__write_file |
+| Read a file            | read_file             | mcp__waymark-${projectName}__read_file  |
+| Run shell commands     | bash / run_command    | mcp__waymark-${projectName}__bash       |
+
+This applies to ALL tasks in this project —
+refactoring, creating files, running tests,
+installing packages, git operations, everything.
+
+## What Waymark does with each action
+
+- Allowed paths → executes normally, logged
+- Blocked paths → stopped, you will see why
+- Sensitive paths → held for human approval,
+  do not retry, tell the user to check dashboard
+
+## If a Waymark tool returns a block decision
+
+Accept the block. Do not attempt to work around it
+using built-in tools. Tell the user what was blocked
+and why. Suggest they update waymark.config.json
+if the block was unintended.
+
+## If Waymark MCP tools are unavailable
+
+Do NOT fall back to built-in file tools.
+Stop and tell the user:
+
+"Waymark MCP server is not running for this project.
+Please run in your terminal:
+  npx @way_marks/cli start
+
+Then restart Claude Code and try again."
+
+## Dashboard
+
+All actions are visible at: http://localhost:${port}
+Approve pending actions there.
+Roll back any write there.
+
+## This file was generated by Waymark
+Do not delete or modify this file.
+It controls how Claude Code behaves in this project.
+---
+`;
+}
+function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(question, answer => { rl.close(); resolve(answer.trim()); });
+    });
+}
+function getClaudeDesktopConfigPath() {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    else if (platform === 'win32') {
+        return path.join(process.env.APPDATA || os.homedir(), 'Claude', 'claude_desktop_config.json');
+    }
+    else {
+        return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+    }
+}
+function resolveServerBin() {
+    try {
+        return require.resolve('@way_marks/server/dist/mcp/server.js');
+    }
+    catch {
+        return path.resolve(__dirname, '../../../server/dist/mcp/server.js');
+    }
+}
+async function run() {
+    const projectRoot = process.cwd();
+    const projectName = kebabCase(path.basename(projectRoot));
+    const mcpKey = `waymark-${projectName}`;
+    const dbPath = path.join(projectRoot, '.waymark', 'waymark.db');
+    const defaultPort = 3001;
+    console.log(`Initializing Waymark in: ${projectRoot}`);
+    // Step 1 — Detect project
+    const hasPackageJson = fs.existsSync(path.join(projectRoot, 'package.json'));
+    const hasGit = fs.existsSync(path.join(projectRoot, '.git'));
+    if (!hasPackageJson && !hasGit) {
+        console.warn('Warning: No package.json or .git found. Continuing anyway.');
+    }
+    // Step 2 — Install @way_marks/server (skip if already resolvable or in monorepo)
+    let serverBin;
+    try {
+        serverBin = require.resolve('@way_marks/server/dist/mcp/server.js');
+        console.log('✓ @way_marks/server already installed');
+    }
+    catch {
+        const monorepoFallback = path.resolve(__dirname, '../../../server/dist/mcp/server.js');
+        if (fs.existsSync(monorepoFallback)) {
+            serverBin = monorepoFallback;
+            console.log('✓ Using local @way_marks/server (monorepo)');
+        }
+        else {
+            console.log('Installing @way_marks/server...');
+            const result = (0, child_process_1.spawnSync)('npm', ['install', '--save-dev', '@way_marks/server'], {
+                stdio: 'inherit',
+                cwd: projectRoot
+            });
+            if (result.status !== 0) {
+                console.error('Failed to install @way_marks/server');
+                process.exit(1);
+            }
+            serverBin = resolveServerBin();
+        }
+    }
+    // Step 3 — Create waymark.config.json
+    const configPath = path.join(projectRoot, 'waymark.config.json');
+    if (fs.existsSync(configPath)) {
+        const answer = await prompt('waymark.config.json exists. Overwrite? (y/N) ');
+        if (answer.toLowerCase() !== 'y') {
+            console.log('Keeping existing waymark.config.json');
+        }
+        else {
+            fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+            console.log('✓ Created waymark.config.json');
+        }
+    }
+    else {
+        fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+        console.log('✓ Created waymark.config.json');
+    }
+    // Step 4 — Create/append CLAUDE.md
+    const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+    const claudeMdContent = generateClaudeMd(projectName, defaultPort);
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, 'utf8');
+        if (existing.includes(WAYMARK_MARKER)) {
+            console.log('✓ CLAUDE.md already has Waymark section');
+        }
+        else {
+            fs.appendFileSync(claudeMdPath, `\n${WAYMARK_MARKER}\n${claudeMdContent}`);
+            console.log('✓ Appended Waymark section to CLAUDE.md');
+        }
+    }
+    else {
+        fs.writeFileSync(claudeMdPath, `${WAYMARK_MARKER}\n${claudeMdContent}`);
+        console.log('✓ Created CLAUDE.md — Claude Code will now use Waymark automatically');
+    }
+    // Step 5 — Update .gitignore
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const gitignoreContent = fs.existsSync(gitignorePath)
+        ? fs.readFileSync(gitignorePath, 'utf8')
+        : '';
+    const linesToAdd = ['.waymark/', 'waymark.db', 'data/waymark.db']
+        .filter(line => !gitignoreContent.includes(line));
+    if (linesToAdd.length > 0) {
+        const section = '\n# Waymark\n' + linesToAdd.join('\n') + '\n';
+        fs.appendFileSync(gitignorePath, section);
+        console.log('✓ Updated .gitignore');
+    }
+    else {
+        console.log('✓ .gitignore already up to date');
+    }
+    // Step 6 — Register MCP in both Claude configs
+    const nodeBin = process.execPath;
+    const mcpEntry = {
+        command: nodeBin,
+        args: [serverBin, '--project-root', projectRoot, '--db-path', dbPath]
+    };
+    // Claude Desktop config — add/update this project's entry only
+    const desktopConfigPath = getClaudeDesktopConfigPath();
+    try {
+        const desktopDir = path.dirname(desktopConfigPath);
+        if (!fs.existsSync(desktopDir))
+            fs.mkdirSync(desktopDir, { recursive: true });
+        const desktopConfig = fs.existsSync(desktopConfigPath)
+            ? JSON.parse(fs.readFileSync(desktopConfigPath, 'utf8'))
+            : { mcpServers: {} };
+        if (!desktopConfig.mcpServers)
+            desktopConfig.mcpServers = {};
+        desktopConfig.mcpServers[mcpKey] = mcpEntry;
+        fs.writeFileSync(desktopConfigPath, JSON.stringify(desktopConfig, null, 2) + '\n');
+        console.log(`✓ Registered MCP server "${mcpKey}" in Claude Desktop config`);
+    }
+    catch (err) {
+        console.warn(`Warning: Could not update Claude Desktop config: ${err.message}`);
+    }
+    // .mcp.json (Claude Code project-level)
+    const mcpJsonPath = path.join(projectRoot, '.mcp.json');
+    try {
+        const mcpJson = fs.existsSync(mcpJsonPath)
+            ? JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'))
+            : { mcpServers: {} };
+        if (!mcpJson.mcpServers)
+            mcpJson.mcpServers = {};
+        mcpJson.mcpServers[mcpKey] = { type: 'stdio', ...mcpEntry, cwd: projectRoot };
+        fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + '\n');
+        console.log(`✓ Created/updated .mcp.json for Claude Code`);
+    }
+    catch (err) {
+        console.warn(`Warning: Could not update .mcp.json: ${err.message}`);
+    }
+    // Step 7 — Success summary
+    const col = 43;
+    const pad = (s) => s + ' '.repeat(Math.max(0, col - 2 - s.length));
+    console.log('');
+    console.log('┌' + '─'.repeat(col) + '┐');
+    console.log(`│ ${pad('✅ Waymark initialized')} │`);
+    console.log(`│ ${pad('')} │`);
+    console.log(`│ ${pad(`Project: ${projectName}`)} │`);
+    console.log(`│ ${pad('Database: .waymark/waymark.db')} │`);
+    console.log(`│ ${pad(`MCP key: ${mcpKey}`)} │`);
+    console.log(`│ ${pad('')} │`);
+    console.log(`│ ${pad('Files created:')} │`);
+    console.log(`│ ${pad('  waymark.config.json')} │`);
+    console.log(`│ ${pad('  CLAUDE.md')} │`);
+    console.log(`│ ${pad('  .waymark/ (gitignored)')} │`);
+    console.log(`│ ${pad('')} │`);
+    console.log(`│ ${pad('Next steps:')} │`);
+    console.log(`│ ${pad('1. Run: npx @way_marks/cli start')} │`);
+    console.log(`│ ${pad('2. Restart Claude Code')} │`);
+    console.log(`│ ${pad('3. Open this project in Claude')} │`);
+    console.log(`│ ${pad('4. Dashboard: http://localhost:3001')} │`);
+    console.log(`│ ${pad('   (port may differ if 3001 is taken)')} │`);
+    console.log(`│ ${pad('')} │`);
+    console.log(`│ ${pad('Waymark is now always-on in this')} │`);
+    console.log(`│ ${pad('project. Claude will use Waymark')} │`);
+    console.log(`│ ${pad('tools automatically via CLAUDE.md')} │`);
+    console.log('└' + '─'.repeat(col) + '┘');
+}

package/dist/commands/logs.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const BASE = 'http://localhost:3001';
+function parseIso(iso) {
+    const normalized = iso.includes('T') ? iso : iso.replace(' ', 'T');
+    const withZ = normalized.endsWith('Z') ? normalized : normalized + 'Z';
+    return new Date(withZ);
+}
+function relativeTime(iso) {
+    const diffMs = Date.now() - parseIso(iso).getTime();
+    const mins = Math.floor(diffMs / 60000);
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+function truncate(str, len) {
+    if (!str)
+        return '—';
+    const s = str.split('/').pop() || str;
+    return s.length > len ? s.slice(0, len - 1) + '…' : s;
+}
+function pad(str, len) {
+    return str.padEnd(len).slice(0, len);
+}
+async function run() {
+    const args = process.argv.slice(3);
+    const limitIdx = args.indexOf('--limit');
+    const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) || 20 : 20;
+    const pendingOnly = args.includes('--pending');
+    const blockedOnly = args.includes('--blocked');
+    let rows;
+    try {
+        const res = await fetch(`${BASE}/api/actions`);
+        if (!res.ok)
+            throw new Error('Bad response');
+        rows = await res.json();
+    }
+    catch {
+        console.log('Waymark is not running. Start with: npx @way_marks/cli start');
+        return;
+    }
+    if (pendingOnly)
+        rows = rows.filter((r) => r.status === 'pending');
+    if (blockedOnly)
+        rows = rows.filter((r) => r.status === 'blocked');
+    rows = rows.slice(0, limit);
+    if (rows.length === 0) {
+        console.log('No actions found.');
+        return;
+    }
+    console.log(pad('Time', 10) + '  ' +
+        pad('Tool', 12) + '  ' +
+        pad('Path / Command', 40) + '  ' +
+        pad('Decision', 10) + '  ' +
+        'Status');
+    console.log('─'.repeat(86));
+    for (const r of rows) {
+        const target = r.target_path
+            ? truncate(r.target_path, 40)
+            : (() => {
+                try {
+                    return truncate(JSON.parse(r.input_payload || '{}').command || '—', 40);
+                }
+                catch {
+                    return '—';
+                }
+            })();
+        console.log(pad(relativeTime(r.created_at), 10) + '  ' +
+            pad(r.tool_name, 12) + '  ' +
+            pad(target, 40) + '  ' +
+            pad(r.decision || '—', 10) + '  ' +
+            r.status);
+    }
+}

package/dist/commands/start.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const net = __importStar(require("net"));
+const child_process_1 = require("child_process");
+function resolveServerBin(name) {
+    const file = name === 'mcp' ? 'mcp/server.js' : 'api/server.js';
+    try {
+        return require.resolve(`@way_marks/server/dist/${file}`);
+    }
+    catch {
+        return path.resolve(__dirname, `../../../server/dist/${file}`);
+    }
+}
+function openBrowser(url) {
+    try {
+        const cmd = process.platform === 'darwin' ? 'open'
+            : process.platform === 'win32' ? 'start'
+                : 'xdg-open';
+        (0, child_process_1.execSync)(`${cmd} ${url}`, { stdio: 'ignore' });
+    }
+    catch {
+        // ignore — browser open is best-effort
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function kebabCase(str) {
+    return str
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function findAvailablePort(preferred) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.listen(preferred, () => {
+            const port = server.address().port;
+            server.close(() => resolve(port));
+        });
+        server.on('error', () => {
+            if (preferred >= 3010) {
+                console.error('No available ports found between 3001-3010. Stop other Waymark projects first.');
+                process.exit(1);
+            }
+            resolve(findAvailablePort(preferred + 1));
+        });
+    });
+}
+async function run() {
+    const projectRoot = process.cwd();
+    const configPath = path.join(projectRoot, 'waymark.config.json');
+    const waymarkDir = path.join(projectRoot, '.waymark');
+    const pidFile = path.join(waymarkDir, 'waymark.pid');
+    if (!fs.existsSync(configPath)) {
+        console.error('waymark.config.json not found. Run: npx @way_marks/cli init');
+        process.exit(1);
+    }
+    // Guard: already running
+    if (fs.existsSync(pidFile)) {
+        try {
+            const saved = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+            if (isAlive(saved.api) || isAlive(saved.mcp)) {
+                const port = saved.port || 3001;
+                console.log('Waymark is already running.');
+                console.log(`Dashboard:  http://localhost:${port}`);
+                console.log('Run "npx @way_marks/cli stop" to stop it.');
+                process.exit(0);
+            }
+        }
+        catch {
+            // stale/corrupt PID file — continue to start
+        }
+    }
+    const port = await findAvailablePort(3001);
+    const dbPath = path.join(projectRoot, '.waymark', 'waymark.db');
+    const projectName = kebabCase(path.basename(projectRoot));
+    const nodeBin = process.execPath;
+    const mcpBin = resolveServerBin('mcp');
+    const apiBin = resolveServerBin('api');
+    const env = {
+        ...process.env,
+        WAYMARK_PROJECT_ROOT: projectRoot,
+        WAYMARK_DB_PATH: dbPath,
+        WAYMARK_PORT: String(port),
+    };
+    const apiProc = (0, child_process_1.spawn)(nodeBin, [apiBin], {
+        env,
+        stdio: 'ignore',
+        detached: true
+    });
+    const mcpProc = (0, child_process_1.spawn)(nodeBin, [
+        mcpBin,
+        '--project-root', projectRoot,
+        '--db-path', dbPath,
+        '--port', String(port),
+    ], {
+        env,
+        stdio: 'ignore',
+        detached: true
+    });
+    apiProc.unref();
+    mcpProc.unref();
+    // Ensure .waymark directory exists
+    if (!fs.existsSync(waymarkDir))
+        fs.mkdirSync(waymarkDir, { recursive: true });
+    // Write .waymark/config.json
+    fs.writeFileSync(path.join(waymarkDir, 'config.json'), JSON.stringify({ port, projectRoot, projectName, startedAt: new Date().toISOString() }, null, 2) + '\n');
+    // Write PID file
+    fs.writeFileSync(pidFile, JSON.stringify({
+        api: apiProc.pid,
+        mcp: mcpProc.pid,
+        port,
+        startedAt: new Date().toISOString()
+    }, null, 2) + '\n');
+    // Open browser after short delay for server startup
+    setTimeout(() => {
+        openBrowser(`http://localhost:${port}`);
+        console.log('Waymark started (background)');
+        console.log(`Dashboard:  http://localhost:${port}`);
+        console.log('MCP server: active (stdio)');
+        console.log('Run "npx @way_marks/cli stop" to stop.');
+    }, 1500);
+}

package/dist/commands/status.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+async function run() {
+    const projectRoot = process.cwd();
+    const configPath = path.join(projectRoot, '.waymark', 'config.json');
+    if (!fs.existsSync(configPath)) {
+        console.log('Waymark not initialized in this directory.');
+        console.log('Run: npx @way_marks/cli init');
+        return;
+    }
+    let waymarkConfig;
+    try {
+        waymarkConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        console.log('Waymark config is corrupt. Re-run: npx @way_marks/cli init');
+        return;
+    }
+    const { port, projectName, startedAt } = waymarkConfig;
+    const mcpKey = `waymark-${projectName}`;
+    const base = `http://localhost:${port}`;
+    // Check if server is running (2s timeout)
+    let running = false;
+    let pending = 0;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch(`${base}/api/actions?count=true`, { signal: controller.signal });
+        clearTimeout(timer);
+        if (res.ok) {
+            running = true;
+            const data = await res.json();
+            pending = data.count;
+        }
+    }
+    catch { /* not running */ }
+    console.log('Waymark — Project Status');
+    console.log('─'.repeat(35));
+    console.log(`Project:    ${projectName}`);
+    console.log(`Root:       ${projectRoot}`);
+    console.log(`Database:   .waymark/waymark.db`);
+    console.log(`Port:       ${port}`);
+    console.log(`Dashboard:  ${base}`);
+    console.log(`MCP key:    ${mcpKey}`);
+    console.log('─'.repeat(35));
+    console.log(`Server:     ${running ? 'running ✅' : 'not running ❌'}`);
+    if (running)
+        console.log(`Pending:    ${pending} actions`);
+    if (!running)
+        console.log(`Start with: npx @way_marks/cli start`);
+    if (startedAt)
+        console.log(`Started:    ${startedAt}`);
+}

package/dist/commands/stop.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function tryKill(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function run() {
+    const pidFile = path.join(process.cwd(), '.waymark', 'waymark.pid');
+    if (!fs.existsSync(pidFile)) {
+        console.log('Waymark is not running.');
+        return;
+    }
+    let saved;
+    try {
+        saved = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+    }
+    catch {
+        fs.unlinkSync(pidFile);
+        console.log('Waymark is not running.');
+        return;
+    }
+    const killedApi = tryKill(saved.api);
+    const killedMcp = tryKill(saved.mcp);
+    try {
+        fs.unlinkSync(pidFile);
+    }
+    catch { /* already gone */ }
+    if (killedApi || killedMcp) {
+        console.log('Waymark stopped.');
+    }
+    else {
+        console.log('Waymark was not running (stale PID file removed).');
+    }
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+const command = process.argv[2];
+switch (command) {
+    case 'init':
+        require('./commands/init').run();
+        break;
+    case 'start':
+        require('./commands/start').run();
+        break;
+    case 'stop':
+        require('./commands/stop').run();
+        break;
+    case 'status':
+        require('./commands/status').run();
+        break;
+    case 'logs':
+        require('./commands/logs').run();
+        break;
+    default:
+        console.log('Usage: npx @way_marks/cli <init|start|stop|status|logs>');
+        console.log('');
+        console.log('Commands:');
+        console.log('  init    Set up Waymark in the current project');
+        console.log('  start   Start the Waymark dashboard and MCP server');
+        console.log('  stop    Stop the running Waymark servers');
+        console.log('  status  Show current Waymark status and pending count');
+        console.log('  logs    Show recent action log');
+        process.exit(command ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@way_marks/cli",
+  "version": "0.4.0",
+  "description": "Control what AI agents can do in your codebase",
+  "author": "Waymark <hello@waymarks.dev>",
+  "license": "MIT",
+  "homepage": "https://github.com/waymarks/waymark",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/waymarks/waymark.git"
+  },
+  "bugs": {
+    "url": "https://github.com/waymarks/waymark/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "claude-code",
+    "mcp",
+    "security",
+    "developer-tools",
+    "llm",
+    "agent-control"
+  ],
+  "bin": {
+    "waymark": "./dist/index.js"
+  },
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@way_marks/server": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "typescript": "^5.3.3"
+  }
+}