declare-cc 1.0.3 → 1.0.5

package/README.md

@@ -37,7 +37,7 @@ Run it:
 npm run plan
 ```
 
-This auto-initializes a `.planning/` directory if one doesn't exist, starts the Declare server, writes the port to `.planning/server.port`, and opens the dashboard in your browser.
+This auto-initializes a `.planning/` directory if one doesn't exist, starts the Declare server on a random free port, writes the port to `.planning/server.port`, and prints the dashboard URL.
 
 Or run directly:
 
@@ -59,7 +59,7 @@ You declare present-tense statements of fact about your project's future. The sy
 
 ## How It Works
 
-Everything happens through the dashboard. `dcl` opens it, and you drive the workflow with keyboard shortcuts and card-based UI.
+Everything happens through the dashboard. `dcl` starts the server and prints the URL — click it to open.
 
 ### 1. Declare Futures
 
@@ -125,9 +125,94 @@ Cards are grouped into stages at each level:
 | **Ctrl+Shift+A** | Approve all visible |
 | **C** | Command bar |
 
-### Server Discovery
+---
+
+## Server & Port Discovery
+
+The Declare server uses OS-assigned ports so multiple projects can run simultaneously without collisions.
+
+### How it works
+
+1. `dcl` (or `dcl serve`) starts the server on **port 0** — the OS assigns a random free port
+2. After the server is listening, it writes the port number to `.planning/server.port` (plain text, e.g. `62964`)
+3. On shutdown (SIGINT, SIGTERM, process exit), the file is deleted
+4. Next time `dcl` runs, it reads the port file. If the server is still alive, it reuses it. If the file is stale (server crashed), it cleans up and starts fresh.
+
+### For external tools
+
+To discover a running Declare server for a project:
+
+```js
+const port = fs.readFileSync('<project>/.planning/server.port', 'utf8').trim();
+// Verify it's alive:
+// GET http://localhost:<port>/api/graph → 200 = running
+// Embed dashboard:
+// <iframe src="http://localhost:<port>/" />
+```
+
+If the file doesn't exist, the server isn't running. Start it:
+
+```bash
+cd <project> && npx dcl serve
+```
+
+Then poll for `.planning/server.port` to appear (~1 second).
+
+### Explicit port
+
+If you need a specific port:
+
+```bash
+dcl serve --port 4000
+```
+
+---
+
+## For Agents
+
+If you're an AI agent (Claude Code, Cursor, etc.) working in a project that uses Declare, here's what you need to know:
+
+### Project state lives in `.planning/`
+
+- **`FUTURE.md`** — Declared futures (present-tense statements about what's true when the project succeeds)
+- **`MILESTONES.md`** — Milestones derived backward from futures
+- **`.planning/milestones/M-XX-slug/PLAN.md`** — Actions for each milestone (title, produces, causes)
+- **`.planning/STATE.md`** — Current project state and decisions
+- **`.planning/PROJECT.md`** — Project context and background
+
+### The DAG structure
+
+Declarations (D-XX) → Milestones (M-XX) → Actions (A-XX). Each layer links to the one above via `realizes` (milestones → declarations) and `causes` (actions → milestones). Read the graph with:
+
+```bash
+node_modules/.bin/declare-cc load-graph
+```
+
+Returns JSON with `declarations`, `milestones`, `actions` arrays.
+
+### Slash commands available to you
+
+If you're running inside Claude Code with declare-cc installed, these slash commands are available:
+
+- `/declare:status` — See where the project stands
+- `/declare:execute M-XX` — Execute actions for a milestone
+- `/declare:verify M-XX` — Validate deliverables
+- `/declare:trace A-XX` — Understand why an action exists (walk the why-chain)
+- `/declare:progress` — Find the next thing to work on
+- `/declare:help` — See all commands
+
+### Dashboard API
+
+If the server is running (check `.planning/server.port`), you can use the HTTP API:
 
-On startup, the server writes the port number to `.planning/server.port` (plain text, e.g. `3847`). On shutdown, it deletes this file. External tools can read this file to embed the dashboard in an iframe.
+| Method | Path | Returns |
+|--------|------|---------|
+| GET | `/api/graph` | Full DAG (declarations, milestones, actions) |
+| GET | `/api/status` | Integrity/alignment metrics |
+| GET | `/api/agents` | Running/completed agents |
+| GET | `/api/events` | SSE stream (real-time updates) |
+| POST | `/api/review` | Approve/reject a node |
+| POST | `/api/action/:id/execute` | Execute an action |
 
 ---
 
@@ -145,7 +230,7 @@ The dashboard is the primary interface. All operations are also available as sla
 | `/declare:audit M-XX` | Cross-reference against declarations |
 | `/declare:trace A-XX` | Walk the why-chain to its declaration |
 | `/declare:status` | Graph health and layer counts |
-| `/declare:dashboard` | Open the dashboard |
+| `/declare:dashboard` | Start server and print URL |
 | `/declare:help` | Show all commands |
 
 ---

package/dist/declare-tools.cjs

@@ -1552,7 +1552,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "1.0.3"
+        version: "1.0.5"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -8905,13 +8905,17 @@ data: ${JSON.stringify({ reason: "delete", nodeId: id })}
       });
     }
     async function startServer(cwd, port) {
-      const preferredPort = port || parseInt(process.env.PORT || "", 10) || 3847;
-      const resolvedPort = await findFreePort(preferredPort);
-      const server = createServer(cwd, resolvedPort);
-      await new Promise((resolve) => {
-        server.listen(resolvedPort, "127.0.0.1", () => {
+      const preferredPort = port || parseInt(process.env.PORT || "", 10) || 0;
+      const listenPort = preferredPort === 0 ? 0 : await findFreePort(preferredPort);
+      const server = createServer(cwd, listenPort);
+      const resolvedPort = await new Promise((resolve) => {
+        server.listen(listenPort, "127.0.0.1", () => {
+          const assigned = (
+            /** @type {import('net').AddressInfo} */
+            server.address().port
+          );
           watchPlanning(cwd);
-          resolve(void 0);
+          resolve(assigned);
         });
       });
       const portFilePath = require("path").join(cwd, ".planning", "server.port");
@@ -8941,7 +8945,6 @@ data: ${JSON.stringify({ reason: "delete", nodeId: id })}
 var require_serve = __commonJS({
   "src/commands/serve.js"(exports2, module2) {
     "use strict";
-    var { spawn } = require("child_process");
     var { startServer } = require_server();
     function parsePortFlag(args) {
       const idx = args.indexOf("--port");
@@ -8950,13 +8953,8 @@ var require_serve = __commonJS({
       return Number.isNaN(value) ? void 0 : value;
     }
     async function runServe2(cwd, args) {
-      const port = parsePortFlag(args) || parseInt(process.env.PORT || "", 10) || 3847;
+      const port = parsePortFlag(args);
       const { server, port: resolvedPort, url } = await startServer(cwd, port);
-      const noOpen = args.includes("--no-open") || process.env.DECLARE_NO_OPEN;
-      if (!noOpen) {
-        const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-        spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
-      }
       process.on("SIGINT", () => {
         server.close(() => process.exit(0));
       });
@@ -8991,12 +8989,17 @@ var require_open = __commonJS({
         });
       });
     }
-    async function waitForServer(port, maxAttempts = 10, intervalMs = 100) {
+    async function waitForPortFile(portFile, maxAttempts = 30, intervalMs = 200) {
       for (let i = 0; i < maxAttempts; i++) {
-        if (await checkServer(port)) return true;
+        try {
+          const content = fs.readFileSync(portFile, "utf8").trim();
+          const port = parseInt(content, 10);
+          if (!isNaN(port) && port > 0) return port;
+        } catch (_) {
+        }
         await new Promise((r) => setTimeout(r, intervalMs));
       }
-      return false;
+      return null;
     }
     async function runOpen2(cwd, args) {
       const planningDir = path.join(cwd, ".planning");
@@ -9008,25 +9011,33 @@ var require_open = __commonJS({
         }
       }
       const portFile = path.join(cwd, ".planning", "server.port");
-      const port = fs.existsSync(portFile) ? parseInt(fs.readFileSync(portFile, "utf8").trim(), 10) : 3847;
-      const isRunning = await checkServer(port);
-      if (!isRunning) {
-        const bundlePath = path.resolve(__dirname, "declare-tools.cjs");
-        const child = spawn(process.execPath, [bundlePath, "serve", "--port", String(port)], {
-          cwd,
-          detached: true,
-          stdio: "ignore"
-        });
-        child.unref();
-        const ready = await waitForServer(port);
-        if (!ready) {
-          console.error("[declare] Warning: server may not be ready yet");
+      if (fs.existsSync(portFile)) {
+        const existingPort = parseInt(fs.readFileSync(portFile, "utf8").trim(), 10);
+        if (!isNaN(existingPort) && existingPort > 0) {
+          const isRunning = await checkServer(existingPort);
+          if (isRunning) {
+            console.log(`Dashboard: http://localhost:${existingPort}`);
+            return;
+          }
+          try {
+            fs.unlinkSync(portFile);
+          } catch (_) {
+          }
         }
       }
-      const url = `http://localhost:${port}`;
-      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-      spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
-      console.log(`Dashboard: ${url}`);
+      const bundlePath = path.resolve(__dirname, "declare-tools.cjs");
+      const child = spawn(process.execPath, [bundlePath, "serve"], {
+        cwd,
+        detached: true,
+        stdio: "ignore"
+      });
+      child.unref();
+      const port = await waitForPortFile(portFile);
+      if (!port) {
+        console.error("[declare] Server failed to start (no port file after 6s)");
+        process.exit(1);
+      }
+      console.log(`Dashboard: http://localhost:${port}`);
     }
     module2.exports = { runOpen: runOpen2 };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
   "bin": {
     "declare-cc": "bin/install.js",

package/scripts/release.js

@@ -40,7 +40,7 @@ run('npm run build');
 // 3. Commit + tag
 run(`git add package.json package-lock.json dist/`);
 run(`git commit -m "chore: bump version to ${version}"`);
-run(`git tag v${version}`);
+run(`git tag -f v${version}`);
 
 console.log(`
 Done. To publish: