superdev-cli 0.2.0 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Superdev - tell it what you want to build, and it keeps the product map, documentation, decisions and status in step while specialist providers do the specialist work.",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "homepage": "https://github.com/superdev-ai/superdev"
   },
   "plugins": [
@@ -13,7 +13,7 @@
       "name": "superdev",
       "source": "./",
       "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence - plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "author": {
         "name": "Rahul Retnan"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
   "author": {
     "name": "Rahul Retnan"
@@ -16,6 +16,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.2.0"
+    "cli": "0.2.1"
   }
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard.",
   "author": {
     "name": "Rahul Retnan"
@@ -22,6 +22,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.2.0"
+    "cli": "0.2.1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Local-first product-building control system for humans and coding agents.",
   "author": "Rahul Retnan",

package/src/cli.mjs

@@ -242,6 +242,10 @@ Flags worth knowing
   feature specify --not <text>
                        What the feature deliberately does not do. Repeatable.
                        Its counterpart is --in, and --out stays global
+  ui | start --port <number>
+                       Serve on this port instead of 4317. Every project defaults
+                       to the same port, so the second one to start is refused
+                       and needs this
 
 Exit codes
   0 it worked, 1 something was found or refused, 2 the command was misused`;
@@ -757,6 +761,23 @@ const service = () => import("./service/manage.mjs");
 // later rename of one field cannot silently make `ui` claim nothing is running.
 const isRunning = (report) => report?.state === "running" || report?.running === true;
 
+/**
+ * The port to serve on, when the default one is taken.
+ *
+ * The refusal for a held port told the reader to start on another port and no
+ * command could. This is that flag, validated here rather than in two places:
+ * `ui` and `start` are the same decision made twice, and a port that is not a
+ * usable number has to be refused before a process is spawned against it.
+ */
+function portFrom(ctx) {
+  if (ctx.flags.port === undefined) return null;
+  const value = Number(ctx.flags.port);
+  if (!Number.isInteger(value) || value < 1024 || value > 65535) {
+    throw new UsageError(`--port takes a whole number between 1024 and 65535. ${JSON.stringify(String(ctx.flags.port))} is not one.`);
+  }
+  return value;
+}
+
 async function cmdUi(ctx) {
   const { serviceStatus, startService } = await service();
   const current = await serviceStatus(ctx.root);
@@ -769,21 +790,25 @@ async function cmdUi(ctx) {
       ]),
     };
   }
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(current, "start the control center",
-      R.wrap("The control center is not running. Starting it opens one local process for this project and listens on the loopback address only."));
+      R.wrap(`The control center is not running. Starting it opens one local process for this project and listens on the loopback address only${port ? `, on port ${port}` : ""}.`));
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Control center started", started) };
 }
 
 async function cmdStart(ctx) {
   const { startService, serviceStatus } = await service();
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(await serviceStatus(ctx.root), "start the local service",
-      "Starting the service opens one local process for this project.");
+      port
+        ? `Starting the service opens one local process for this project, on port ${port}.`
+        : "Starting the service opens one local process for this project.");
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Service started", started) };
 }
 

package/src/runtime/hooks.mjs

@@ -22,7 +22,7 @@
 // Secrets never reach the output: everything user facing goes through
 // sanitizeExternal, which strips secret-shaped values and home paths.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, writeSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, writeSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { paths, query } from "../db/store.mjs";
 import { availableMigrations } from "../db/migrate.mjs";
@@ -472,11 +472,28 @@ async function postToolUse(root, payload) {
   if (!MUTATING_TOOLS.has(tool) && !viaShell) return EMPTY;
 
   let file = payload?.tool_input?.file_path ?? payload?.tool_input?.notebook_path ?? payload?.tool_input?.path;
+  // Whether anything is newly changed, decided before the paths are marked.
+  //
+  // git reports a file as changed until it is committed, so a shell command run
+  // after a task is completed re-reported the very files that task had produced,
+  // and the readiness report raised its only high-severity warning about work
+  // that had just been finished, evidenced and recorded. Any redirect or heredoc
+  // is enough to make the hook look, so this happened on the first command after
+  // every completion.
+  //
+  // The paths already seen are the answer. Work noticed twice is one piece of
+  // work; a path not seen before is a genuine change. Computed here because
+  // markTouched below would otherwise record these paths and make every one of
+  // them look familiar.
+  let fresh = true;
   if (viaShell) {
     const changed = await changedFiles(root);
     // A command that looked like a write and changed nothing is not work.
     if (!changed.length) return EMPTY;
+    const moved = movedSince(root, changed, readTouched(root).attributed);
+    fresh = moved.length > 0;
     markTouched(root, changed);
+    attribute(root, moved);
     file = file ?? changed[0];
   }
   markTouched(root, [file]);
@@ -487,7 +504,7 @@ async function postToolUse(root, payload) {
   // files touched by the active task; when there is no active task, that
   // absence is the fact worth keeping. Rate limited so a long editing run
   // leaves one honest marker rather than one per keystroke.
-  await noteUntrackedWork(root, file).catch(() => {});
+  if (fresh) await noteUntrackedWork(root, file).catch(() => {});
   await markDocsPossiblyStale(root, file).catch(() => {});
   return EMPTY;
 }
@@ -521,9 +538,12 @@ function readTouched(root) {
       total: Number.isFinite(parsed.total) ? parsed.total : 0,
       since: typeof parsed.since === "string" ? parsed.since : null,
       lastEventAt: typeof parsed.lastEventAt === "string" ? parsed.lastEventAt : null,
+      // When each path was last accounted for, which `paths` cannot answer
+      // because a flush empties it.
+      attributed: parsed.attributed && typeof parsed.attributed === "object" ? parsed.attributed : {},
     };
   } catch {
-    return { paths: [], total: 0, since: null, lastEventAt: null };
+    return { paths: [], total: 0, since: null, lastEventAt: null, attributed: {} };
   }
 }
 
@@ -537,6 +557,61 @@ function writeTouched(root, state) {
   }
 }
 
+/**
+ * Whether a path is the product, rather than Superdev's own bookkeeping about it.
+ *
+ * markTouched has always skipped `.superdev/`, and the freshness comparison did
+ * not, so the runtime directory was picking up modification stamps. One of those
+ * files is the database write-ahead log, which moves on every single command, so
+ * every command would have looked like new work and the comparison would have
+ * decided nothing. Both callers now ask the same question in the same place.
+ */
+const isProjectWork = (rel) => Boolean(rel) && !rel.startsWith(".superdev/");
+
+/**
+ * Which of these paths have actually moved since they were last accounted for.
+ *
+ * git reports a file as changed until it is committed, so every shell command run
+ * between an edit and its commit re-reports the same files. That made the hook
+ * record fresh untracked work for edits a completed task had already produced and
+ * evidenced, and the readiness report then raised its only high-severity warning
+ * about work that was finished. Any redirect or heredoc is enough to make the hook
+ * look, so it happened on the first command after every completion.
+ *
+ * The pending path list cannot answer this, because a flush empties it. A
+ * modification time can: a path re-reported without moving is the same work seen
+ * again, and a path whose file has changed since is new work whoever is holding
+ * the task. Missing stats count as moved, because failing to notice real work is
+ * the worse mistake of the two.
+ */
+export function movedSince(root, candidates, attributed) {
+  candidates = candidates.filter(isProjectWork);
+  const moved = [];
+  for (const path of candidates) {
+    let stamp = null;
+    try {
+      stamp = statSync(join(root, path)).mtimeMs;
+    } catch {
+      // Deleted, or unreadable. Either way it is not the file we accounted for.
+      moved.push([path, Date.now()]);
+      continue;
+    }
+    if (stamp > (Number(attributed[path]) || 0)) moved.push([path, stamp]);
+  }
+  return moved;
+}
+
+/** Record that these paths are accounted for, at the state they are in now. */
+function attribute(root, moved) {
+  if (!moved.length) return;
+  const state = readTouched(root);
+  const next = { ...state.attributed };
+  for (const [path, stamp] of moved) next[path] = stamp;
+  // Bounded, oldest first, so a long-lived project does not grow this forever.
+  const entries = Object.entries(next).sort((a, b) => b[1] - a[1]).slice(0, MAX_TOUCHED);
+  writeTouched(root, { ...state, attributed: Object.fromEntries(entries) });
+}
+
 /**
  * Record which project-relative paths changed.
  *
@@ -550,7 +625,7 @@ export function markTouched(root, files) {
     if (!file) continue;
     const rel = relative(root, canonical(root, file)).split(sep).join("/");
     if (!rel || rel.startsWith("../") || isAbsolute(rel)) continue;
-    if (rel.startsWith(".superdev/")) continue; // Superdev's own runtime state is not project work.
+    if (!isProjectWork(rel)) continue;
     kept.push(rel);
   }
   if (!kept.length) return null;
@@ -562,6 +637,7 @@ export function markTouched(root, files) {
     total: state.total + kept.length,
     since: state.since ?? new Date().toISOString(),
     lastEventAt: state.lastEventAt,
+    attributed: state.attributed,
   };
   writeTouched(root, next);
   return next;
@@ -633,7 +709,10 @@ export async function flushTouched(root, { force = false } = {}) {
     metadata: { files: state.paths.length, changes: state.total },
   }).catch((err) => ({ recorded: false, reason: message(err) }));
 
-  writeTouched(root, { paths: [], total: 0, since: null, lastEventAt: new Date().toISOString() });
+  writeTouched(root, {
+    paths: [], total: 0, since: null, lastEventAt: new Date().toISOString(),
+    attributed: state.attributed,
+  });
   return result;
 }
 

package/src/service/manage.mjs

@@ -135,6 +135,19 @@ export function probeHealth(host, port, timeout = PROBE_TIMEOUT_MS) {
   });
 }
 
+/**
+ * A path a reader can retype, shortened at home so a long absolute path does not
+ * bury the part that identifies the project.
+ *
+ * Every message about a port used to describe it without saying whose it was,
+ * even though the health probe had already been handed the answer, so finding out
+ * meant opening candidate directories one at a time.
+ */
+export function displayRoot(path) {
+  const home = homedir();
+  return home && path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
+}
+
 /**
  * What is actually true for this project right now. Distinguishes a service we
  * manage from a stale lock, from a start in progress, from someone else holding
@@ -160,14 +173,31 @@ export async function inspect(root, { port = null, host = DEFAULTS.host } = {})
       };
     }
     if (health) {
+      // Not running, and the default port happens to be busy. Those are two
+      // separate facts and only the first one is about this project.
+      //
+      // This used to report `foreign`, which made both commands lie. `start`
+      // never blocked on it: the server scans forward from the requested port on
+      // EADDRINUSE, so a second project quietly lands on the next free one, and
+      // the message told the reader to do something the tool was already doing.
+      // `stop` did worse. On a project with nothing running it refused, and told
+      // the reader to go and stop a different project, which they have no reason
+      // to touch.
+      //
+      // Reserving `foreign` for the case that is genuinely somebody else's
+      // service in our place is what makes the word mean something.
       return {
-        state: "foreign",
+        state: "stopped",
         managed: false,
         lock: null,
         health,
-        port: candidate,
+        port: null,
         host,
-        explanation: `Port ${candidate} is held by a Superdev service for a different project. Start this one on another port.`,
+        portInUse: candidate,
+        heldBy: health.projectRoot ?? null,
+        explanation: `Nothing is running for this project. Port ${candidate} is held by ${
+          health.projectRoot ? `the Superdev service for ${displayRoot(health.projectRoot)}` : "another Superdev service"
+        }, so starting this one will use the next free port instead. Pass --port <number> to choose.`,
       };
     }
     return {
@@ -217,7 +247,9 @@ export async function inspect(root, { port = null, host = DEFAULTS.host } = {})
       health,
       port: lock.port,
       host: lock.host ?? host,
-      explanation: `Port ${lock.port} is answering, but it is not the service this lock file describes. Something else took the port.`,
+      explanation: `Port ${lock.port} is answering, but it is not the service this lock file describes${
+        health.projectRoot ? `: it belongs to ${displayRoot(health.projectRoot)}` : ""
+      }. This project's service is gone and something else took its port. Run \`superdev start --apply\` to bring this one back on a free port.`,
     };
   }
   return {
@@ -335,7 +367,12 @@ export async function startService(root, options = {}) {
   );
   if (!held) {
     if (view.state === "foreign") {
-      throw new ServiceError(E.FOREIGN, view.explanation, { port: view.port });
+      throw new ServiceError(E.FOREIGN, view.explanation, {
+        port: view.port,
+        // The caller cannot act on a refusal whose subject it cannot see, and the
+        // probe already knows it. `superdev services` prints it; a script reads it.
+        heldBy: view.health?.projectRoot ?? null,
+      });
     }
     return { ...summarize(root, view), alreadyRunning: true };
   }