@way_marks/cli 2.0.3 → 4.0.0

package/dist/commands/init.js

@@ -83,7 +83,7 @@ function kebabCase(str) {
         .replace(/-+/g, '-')
         .replace(/^-|-$/g, '');
 }
-function generateClaudeMd(projectName, port) {
+function generateClaudeMd(projectName) {
     return `---
 # ⚠️ WAYMARK ACTIVE — MANDATORY INSTRUCTIONS
 
@@ -135,9 +135,10 @@ 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.
+Pending and recent actions are visible in the
+Waymark dashboard. Run \`npx @way_marks/cli status\`
+to see the current dashboard URL for this project.
+Approve pending actions there. Roll back any write there.
 
 ## This file was generated by Waymark
 Do not delete or modify this file.
@@ -208,7 +209,6 @@ async function run() {
     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'));
@@ -263,7 +263,7 @@ async function run() {
     // Step 4 — Create/append CLAUDE.md (only if Claude selected)
     if (selectedPlatforms.includes('claude')) {
         const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
-        const claudeMdContent = generateClaudeMd(projectName, defaultPort);
+        const claudeMdContent = generateClaudeMd(projectName);
         if (fs.existsSync(claudeMdPath)) {
             const existing = fs.readFileSync(claudeMdPath, 'utf8');
             if (existing.includes(WAYMARK_MARKER)) {
@@ -379,9 +379,9 @@ async function run() {
     if (selectedPlatforms.includes('claude')) {
         console.log(`│ ${pad('Next steps (Claude):')} │`);
         console.log(`│ ${pad('1. Run: npx @way_marks/cli start')} │`);
+        console.log(`│ ${pad('   (it will print the dashboard URL)')} │`);
         console.log(`│ ${pad('2. Restart Claude Code')} │`);
         console.log(`│ ${pad('3. Open project in Claude')} │`);
-        console.log(`│ ${pad('4. Dashboard: http://localhost:3001')} │`);
     }
     if (selectedPlatforms.includes('copilot-cli')) {
         if (selectedPlatforms.includes('claude')) {

package/dist/commands/logs.js

@@ -1,7 +1,58 @@
 "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 BASE = 'http://localhost:3001';
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Resolve the dashboard URL for the current project by reading the live port
+ * out of `<cwd>/.waymark/config.json` (written by `waymark start`).
+ * Returns null when the project hasn't been started yet.
+ */
+function resolveBaseUrl() {
+    const configPath = path.join(process.cwd(), '.waymark', 'config.json');
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return cfg.port ? `http://localhost:${cfg.port}` : null;
+    }
+    catch {
+        return null;
+    }
+}
 function parseIso(iso) {
     const normalized = iso.includes('T') ? iso : iso.replace(' ', 'T');
     const withZ = normalized.endsWith('Z') ? normalized : normalized + 'Z';
@@ -34,15 +85,20 @@ async function run() {
     const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) || 20 : 20;
     const pendingOnly = args.includes('--pending');
     const blockedOnly = args.includes('--blocked');
+    const base = resolveBaseUrl();
+    if (!base) {
+        console.log('Waymark is not running for this project. Start with: npx @way_marks/cli start');
+        return;
+    }
     let rows;
     try {
-        const res = await fetch(`${BASE}/api/actions`);
+        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');
+        console.log(`Waymark is not reachable at ${base}. Start with: npx @way_marks/cli start`);
         return;
     }
     if (pendingOnly)

package/dist/commands/start.js

@@ -82,7 +82,7 @@ function findAvailablePort(preferred) {
         return Promise.resolve((0, registry_1.findAvailablePort)(preferred));
     }
     catch {
-        // Fallback: old logic (Phase 1 compatibility)
+        // Fallback: kernel-level probe (registry corrupt or absent)
         return new Promise((resolve) => {
             const server = net.createServer();
             server.listen(preferred, () => {
@@ -90,8 +90,9 @@ function findAvailablePort(preferred) {
                 server.close(() => resolve(port));
             });
             server.on('error', () => {
-                if (preferred >= 4000) {
-                    console.error('No available ports found between 3001-4000. Stop other Waymark projects first.');
+                if (preferred >= registry_1.PORT_RANGE_END) {
+                    console.error(`No available ports found between ${registry_1.PORT_RANGE_START}-${registry_1.PORT_RANGE_END}. ` +
+                        `Stop other Waymark projects first.`);
                     process.exit(1);
                 }
                 resolve(findAvailablePort(preferred + 1));
@@ -99,6 +100,37 @@ function findAvailablePort(preferred) {
         });
     }
 }
+/**
+ * Probe whether `port` is currently free. We listen exactly the same way the
+ * real server does (no explicit host → all interfaces, dual-stack), so this
+ * matches what would happen at actual bind time and catches IPv4/IPv6
+ * dual-stack collisions.
+ */
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port);
+    });
+}
+/**
+ * Parse `--port <n>` from process.argv. Returns null when not provided.
+ * Validates the value is a positive integer < 65536. Exits with a readable
+ * error on garbage input rather than silently ignoring.
+ */
+function parsePortFlag(argv) {
+    const idx = argv.indexOf('--port');
+    if (idx === -1)
+        return null;
+    const raw = argv[idx + 1];
+    const port = Number.parseInt(raw, 10);
+    if (!Number.isInteger(port) || port <= 0 || port >= 65536 || String(port) !== raw) {
+        console.error(`Invalid --port value: "${raw}". Expected an integer 1-65535.`);
+        process.exit(1);
+    }
+    return port;
+}
 async function run() {
     const projectRoot = process.cwd();
     const configPath = path.join(projectRoot, 'waymark.config.json');
@@ -113,7 +145,7 @@ async function run() {
         try {
             const saved = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
             if (isAlive(saved.api) || isAlive(saved.mcp)) {
-                const port = saved.port || 3001;
+                const port = saved.port || registry_1.PORT_RANGE_START;
                 console.log('Waymark is already running.');
                 console.log(`Dashboard:  http://localhost:${port}`);
                 console.log('Run "npx @way_marks/cli stop" to stop it.');
@@ -124,9 +156,96 @@ async function run() {
             // 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 dbPath = path.join(projectRoot, '.waymark', 'waymark.db');
+    // Load project config — used for the optional `port` pin.
+    let projectConfig = {};
+    try {
+        projectConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch (err) {
+        console.error(`Failed to parse waymark.config.json: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // Port resolution precedence: --port flag > config.port > auto-allocate.
+    const flagPort = parsePortFlag(process.argv.slice(3));
+    const configPort = typeof projectConfig.port === 'number' ? projectConfig.port : null;
+    const pinnedPort = flagPort ?? configPort;
+    const pinnedSource = flagPort !== null ? 'flag' : configPort !== null ? 'config' : null;
+    let port;
+    if (pinnedPort !== null) {
+        if (!(await isPortFree(pinnedPort))) {
+            const existing = (0, registry_1.findProjectByPath)(projectRoot);
+            const owner = (() => {
+                // Best-effort: try to identify which Waymark project owns the port.
+                // We can't reach into other processes; just advise `waymark list`.
+                return null;
+            })();
+            console.error(`Port ${pinnedPort} is already in use ` +
+                `(pinned via ${pinnedSource === 'flag' ? '--port flag' : 'waymark.config.json'}).\n` +
+                `  → Run "npx @way_marks/cli list" to see other Waymark projects.\n` +
+                `  → Or remove the pin to auto-allocate from ${registry_1.PORT_RANGE_START}-${registry_1.PORT_RANGE_END}.`);
+            void existing;
+            void owner; // reserved for future "owner is project X" diagnostics
+            process.exit(1);
+        }
+        port = pinnedPort;
+    }
+    else {
+        // Migration notice: if this project's prior registry entry used a legacy port,
+        // the auto-allocator may pick a fresh modern port instead. Emit a one-line
+        // notice so the user understands why their bookmark might shift.
+        const prior = (0, registry_1.findProjectByPath)(projectRoot);
+        const newPort = await findAvailablePort(registry_1.PORT_RANGE_START);
+        if (prior &&
+            typeof prior.port === 'number' &&
+            prior.port < registry_1.LEGACY_PORT_BOUNDARY &&
+            newPort !== prior.port) {
+            console.log(`[waymark] Reallocating from legacy port :${prior.port} to :${newPort}.\n` +
+                `          Set "port": ${prior.port} in waymark.config.json to keep the old one.`);
+        }
+        port = newPort;
+    }
+    // Pre-flight: surface any project-id collision *before* spawning children,
+    // so we never leave orphan processes when registration would fail.
+    const colliding = (() => {
+        try {
+            // Probe by performing a fake registerProject() that we immediately undo
+            // would risk corrupting the file; instead read directly via findProjectByPath
+            // and check the registry's keying contract here.
+            const otherAtSamePath = (0, registry_1.findProjectByPath)(projectRoot);
+            if (otherAtSamePath && otherAtSamePath.id === projectName)
+                return null;
+            // Different path with same id → ask registry for the entry by id.
+            // findProjectByPath already returned null, so we need a different lookup.
+            // Use require-time access to the same module's getProject.
+            const reg = require('../registry');
+            const sameId = reg.getProject(projectName);
+            if (sameId &&
+                path.resolve(sameId.projectRoot) !== path.resolve(projectRoot) &&
+                ((sameId.mcp_pid != null && (() => { try {
+                    process.kill(sameId.mcp_pid, 0);
+                    return true;
+                }
+                catch {
+                    return false;
+                } })()) ||
+                    sameId.status === 'running')) {
+                return sameId;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (colliding) {
+        console.error(`Another running Waymark project named "${projectName}" is registered at ${colliding.projectRoot}.\n` +
+            `This start request is at ${projectRoot}.\n` +
+            `  → Stop the other project first ("npx @way_marks/cli stop" in ${colliding.projectRoot}),\n` +
+            `  → or rename one of the directories so the project ids differ.`);
+        process.exit(1);
+    }
     const nodeBin = process.execPath;
     const mcpBin = resolveServerBin('mcp');
     const apiBin = resolveServerBin('api');
@@ -181,6 +300,24 @@ async function run() {
         });
     }
     catch (err) {
+        if (err instanceof registry_1.ProjectIdCollisionError) {
+            // Race: another start landed between our pre-flight and registration.
+            // Tear down the children we just spawned so we don't leak processes.
+            try {
+                apiProc.pid && process.kill(apiProc.pid);
+            }
+            catch { }
+            try {
+                mcpProc.pid && process.kill(mcpProc.pid);
+            }
+            catch { }
+            try {
+                fs.unlinkSync(pidFile);
+            }
+            catch { }
+            console.error(err.message);
+            process.exit(1);
+        }
         console.warn('Warning: failed to register in global registry:', err instanceof Error ? err.message : String(err));
         // Continue anyway — registry is optional (backward compat)
     }

package/dist/index.js

@@ -33,14 +33,19 @@ switch (command) {
         console.log('Usage: npx @way_marks/cli <init|start|stop|pause|resume|status|logs|list|open>');
         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('  pause   Pause a project (keep port allocated)');
-        console.log('  resume  Resume a paused project');
-        console.log('  status  Show current Waymark status and pending count');
-        console.log('  logs    Show recent action log');
-        console.log('  list    List all registered Waymark projects');
-        console.log('  open    Open a project dashboard or start it');
+        console.log('  init                  Set up Waymark in the current project');
+        console.log('  start [--port <n>]    Start the Waymark dashboard and MCP server');
+        console.log('  stop                  Stop the running Waymark servers');
+        console.log('  pause                 Pause a project (keep port allocated)');
+        console.log('  resume                Resume a paused project');
+        console.log('  status                Show current Waymark status and pending count');
+        console.log('  logs                  Show recent action log');
+        console.log('  list                  List all registered Waymark projects');
+        console.log('  open                  Open a project dashboard or start it');
+        console.log('');
+        console.log('Notes:');
+        console.log('  • Default port range is 47000-47999 (avoids collisions with dev servers).');
+        console.log('  • Pin a port per-project: add "port": 47100 to waymark.config.json.');
+        console.log('  • Override at runtime: waymark start --port 47200');
         process.exit(command ? 1 : 0);
 }

package/dist/registry.js

@@ -45,6 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_PORT_BOUNDARY = exports.PORT_RANGE_END = exports.PORT_RANGE_START = exports.ProjectIdCollisionError = void 0;
 exports.getRegistry = getRegistry;
 exports.registerProject = registerProject;
 exports.unregisterProject = unregisterProject;
@@ -96,11 +97,51 @@ function ensureRegistry() {
 function getRegistry() {
     return ensureRegistry();
 }
+/**
+ * Error thrown when two projects with the same kebab-cased basename are running
+ * at different paths. Caller (start.ts) catches this and emits a user-facing
+ * message instead of silently overwriting the registry.
+ */
+class ProjectIdCollisionError extends Error {
+    constructor(id, existingRoot, newRoot) {
+        super(`Another running Waymark project named "${id}" is registered at ${existingRoot}. ` +
+            `This start request is at ${newRoot}. ` +
+            `Stop the other project first ("npx @way_marks/cli stop" in ${existingRoot}), ` +
+            `or rename one of the directories so the project ids differ.`);
+        this.name = 'ProjectIdCollisionError';
+        this.id = id;
+        this.existingRoot = existingRoot;
+        this.newRoot = newRoot;
+    }
+}
+exports.ProjectIdCollisionError = ProjectIdCollisionError;
 /**
  * Register a project (called on `waymark start`)
+ *
+ * Surfaces a `ProjectIdCollisionError` when an entry with the same `id`
+ * already exists at a *different* path AND its process is still alive.
+ * Same-path re-registration (the resume case) overwrites silently.
+ * Stale entries (process gone) are also overwritten — caller will start fresh.
  */
 function registerProject(entry) {
     const registry = ensureRegistry();
+    const existing = registry.projects[entry.id];
+    if (existing && path.resolve(existing.projectRoot) !== path.resolve(entry.projectRoot)) {
+        const aliveByPid = existing.mcp_pid != null && (() => {
+            try {
+                process.kill(existing.mcp_pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        const aliveByStatus = existing.status === 'running';
+        if (aliveByPid || aliveByStatus) {
+            throw new ProjectIdCollisionError(entry.id, existing.projectRoot, entry.projectRoot);
+        }
+        // Stale entry at a different path — fall through and overwrite.
+    }
     entry.startedAt = entry.startedAt || new Date().toISOString();
     entry.status = entry.status || 'running';
     entry.hostname = entry.hostname || os.hostname();
@@ -186,35 +227,64 @@ function listProjects(filter) {
     return entries;
 }
 /**
- * Find available port in the 3001-4000 range
- * (Phase 2 future: will be replaced by central port broker)
+ * Default port range for new Waymark projects.
+ *
+ * 47000-47999 is in the IANA "user ports" range and avoids collisions with the
+ * most common dev-server defaults (3000 Next.js, 3001 fallback, 5173 Vite,
+ * 4200 Angular, 8080 generic, 1337 Strapi, etc.). Existing projects on the
+ * legacy 3001-4000 range keep working until they're stopped — see start.ts
+ * for the migration notice.
  */
-function findAvailablePort(preferred = 3001) {
+exports.PORT_RANGE_START = 47000;
+exports.PORT_RANGE_END = 47999;
+exports.LEGACY_PORT_BOUNDARY = 47000; // anything below this is "legacy"
+/**
+ * Find an available port for a new Waymark instance.
+ *
+ * Order:
+ *   1. Reuse a freed port from the releasedPorts queue (when not in use).
+ *   2. Use `preferred` if free.
+ *   3. Scan 47000..47999 for the first free port.
+ */
+function findAvailablePort(preferred = exports.PORT_RANGE_START) {
     const registry = ensureRegistry();
     const usedPorts = new Set(Object.values(registry.projects)
         .filter(p => p.status === 'running')
         .map(p => p.port));
-    // Phase 4: Check if we have a released port to reuse first
+    // Reuse a released port if one is available — but skip any legacy ports
+    // (< LEGACY_PORT_BOUNDARY) so the v3.1 migration cleanly transitions every
+    // project off the old range over time. Legacy ports are simply discarded.
     if (registry.releasedPorts && registry.releasedPorts.length > 0) {
-        const releasedPort = registry.releasedPorts.shift();
-        if (releasedPort && !usedPorts.has(releasedPort)) {
-            // Save updated registry with shifted port
+        let mutated = false;
+        while (registry.releasedPorts.length > 0) {
+            const candidate = registry.releasedPorts.shift();
+            mutated = true;
+            if (candidate == null)
+                continue;
+            if (candidate < exports.LEGACY_PORT_BOUNDARY)
+                continue; // drop legacy
+            if (usedPorts.has(candidate))
+                continue;
+            registry.lastUpdated = new Date().toISOString();
+            fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+            return candidate;
+        }
+        if (mutated) {
             registry.lastUpdated = new Date().toISOString();
             fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
-            return releasedPort;
         }
     }
     // Check if preferred is available
     if (!usedPorts.has(preferred)) {
         return preferred;
     }
-    // Find next available
-    for (let port = 3001; port <= 4000; port++) {
+    // Find next available in the modern range
+    for (let port = exports.PORT_RANGE_START; port <= exports.PORT_RANGE_END; port++) {
         if (!usedPorts.has(port)) {
             return port;
         }
     }
-    throw new Error('No available ports in range 3001-4000');
+    throw new Error(`No available ports in range ${exports.PORT_RANGE_START}-${exports.PORT_RANGE_END}. Stop other Waymark projects first.`);
 }
 /**
  * Clean up stale entries (processes that are dead but not unregistered)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@way_marks/cli",
-  "version": "2.0.3",
+  "version": "4.0.0",
   "description": "Control what AI agents can do in your codebase",
   "author": "Waymark <hello@waymarks.dev>",
   "license": "MIT",
@@ -40,7 +40,7 @@
     ]
   },
   "dependencies": {
-    "@way_marks/server": "0.5.2"
+    "@way_marks/server": "4.0.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",