superdev-cli 0.1.2 → 0.2.1

package/src/service/assets/control-center.manifest.json

@@ -1,7 +1,7 @@
 {
   "source": "ui/",
-  "sourceHash": "57c0be5885fc42ef1aa0df9442a8128372ab0db907bc347bfcc7fe02b6e0f462",
-  "sourceFileCount": 84,
-  "bundleHash": "59cd09db3329c8937d2dce5e9c210df58feb9bcfb9d8874fb80cd54c1e0ff682",
-  "bundleBytes": 2002963
+  "sourceHash": "f542076f8b1126465fb2eed5f508a4aeacb00acee8a6b18541afd82081c9f8d7",
+  "sourceFileCount": 85,
+  "bundleHash": "6af5d685e8252a7259e163159fd31bc980e74268d645c4a3317c398920407f4c",
+  "bundleBytes": 2007051
 }

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 };
   }

package/src/service/mutations.mjs

@@ -317,12 +317,40 @@ function dependencyIds(payload) {
 
 // ----------------------------------------------------------------- questions
 
+/** The question's own options. The row is read unhydrated, so the JSON is text. */
+function offeredOptions(question) {
+  try {
+    const parsed = JSON.parse(question.alternatives_json ?? "[]");
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Answer a question, from its options or in the reader's own words.
+ *
+ * `selected` carries the options chosen; `answer` carries typed text. Either is
+ * enough, both together is fine (an option plus a qualification), neither is
+ * refused. A question that takes one answer refuses several, because a record
+ * saying "a single service, several services" says nothing.
+ *
+ * The work is delegated to the engine rather than repeated here. This handler
+ * used to write the answer and set the status itself, which looked equivalent and
+ * was not: the engine also settles the capability area the question belongs to,
+ * records a reversible assumption when the answer is "I do not know", and writes a
+ * project-level answer through to the field it exists to fill. So a question
+ * answered in the control centre left its readiness area awaiting a decision,
+ * while the same question answered from the command line settled it. One answer
+ * path is the fix; two that agree by coincidence is the defect.
+ */
 async function answerQuestion(root, payload) {
   const questionId = identifier(payload, "questionId", { required: true });
   const status = oneOf(payload, "status", ["answered", "deferred", "withdrawn"], {
     fallback: "answered",
   });
-  const answer = text(payload, "answer", { required: status === "answered" });
+  const selected = list(payload, "selected") ?? [];
+  const typed = text(payload, "answer", { required: status === "answered" && !selected.length });
   const deferralReason = text(payload, "deferralReason", {
     required: status === "deferred",
     max: LIMIT.prose,
@@ -330,40 +358,60 @@ async function answerQuestion(root, payload) {
   const answeredBy = text(payload, "answeredBy", { max: LIMIT.actor });
   const actor = actorOf(payload);
 
-  return mutate(root, async (db) => {
-    const question = await db.get("SELECT * FROM questions WHERE id = ?", questionId);
-    if (!question) throw new MutationError(E.NOT_FOUND, `There is no question ${questionId}.`);
-    if (question.status !== "open" && question.status !== "deferred") {
+  const question = await query(root, (db) => db.get("SELECT * FROM questions WHERE id = ?", questionId));
+  if (!question) throw new MutationError(E.NOT_FOUND, `There is no question ${questionId}.`);
+  if (question.status !== "open" && question.status !== "deferred") {
+    throw new MutationError(
+      E.INVALID_TRANSITION,
+      `${questionId} is already ${question.status} and is not waiting on an answer.`,
+    );
+  }
+
+  if (selected.length) {
+    const offered = offeredOptions(question);
+    const unknown = selected.filter((choice) => !offered.includes(choice));
+    if (unknown.length) {
       throw new MutationError(
-        E.INVALID_TRANSITION,
-        `${questionId} is already ${question.status} and is not waiting on an answer.`,
+        E.INVALID_PAYLOAD,
+        `${questionId} does not offer ${unknown.map((u) => JSON.stringify(u)).join(", ")}. Choose from its own options, or type an answer instead.`,
       );
     }
-    const project = await currentProject(db);
-    await patch(
-      db,
-      "question",
-      questionId,
-      question.version,
-      pick(
-        {
-          answer,
-          answered_by: answeredBy ?? actor,
-          answered_at: new Date().toISOString(),
-          deferral_reason: deferralReason,
-        },
-        ["answer", "answered_by", "answered_at", "deferral_reason"],
-      ),
-      { projectId: project.id, actor, activity: false },
-    );
-    return setStatus(db, "question", questionId, status, {
-      projectId: project.id,
-      actor,
-      note: answer ?? deferralReason,
-      activityType: "specification_changed",
-      activitySummary: `${questionId} ${status}: ${(answer ?? deferralReason ?? "").slice(0, 160)}`,
+    if (question.select_mode !== "many" && selected.length > 1) {
+      throw new MutationError(
+        E.INVALID_PAYLOAD,
+        `${questionId} takes one answer, and ${selected.length} were chosen. Pick one, or type an answer that says what you mean.`,
+      );
+    }
+  }
+
+  if (status === "withdrawn") {
+    return mutate(root, async (db) => {
+      const project = await currentProject(db);
+      return setStatus(db, "question", questionId, "withdrawn", {
+        projectId: project.id,
+        actor,
+        note: typed ?? deferralReason,
+        activityType: "specification_changed",
+        activitySummary: `${questionId} withdrawn: ${(typed ?? deferralReason ?? "no reason given").slice(0, 160)}`,
+      });
     });
+  }
+
+  // The chosen options and the typed words become one sentence, in that order,
+  // because the options are the shared vocabulary and the typing qualifies them.
+  const answer = [selected.join("; "), typed].filter(Boolean).join(". ") || null;
+  const { answerQuestion: record } = await import("../init/questions.mjs");
+  const outcome = await record(root, questionId, {
+    answer: status === "deferred" ? null : answer,
+    // Kept apart from the composed answer so a question that writes through to a
+    // project field gets the sentence somebody wrote, not the option they picked.
+    inOwnWords: typed,
+    unknown: status === "deferred",
+    revisitTrigger: status === "deferred" ? deferralReason : null,
+    actor,
+    answeredBy: answeredBy ?? actor,
   });
+  return { id: questionId, status, answer, selected, outcome };
 }
 
 // ----------------------------------------------------------------- decisions

package/src/tasks/lifecycle.mjs

@@ -129,6 +129,13 @@ async function release(db, task, actor, note) {
     summary: note ?? `Assignment on ${task.id} released.`,
     metadata: { assignment: assignment.id },
   });
+  // Every path that ends a claim runs through here: releasing it, completing it,
+  // cancelling it. So this is the one place that has to stop pointing a session at
+  // a task it no longer holds, and only the session that held it is cleared.
+  await db.run(
+    "UPDATE work_sessions SET active_task_id = NULL WHERE project_id = ? AND active_task_id = ?",
+    task.project_id, task.id,
+  );
   return assignment;
 }
 
@@ -382,10 +389,48 @@ export async function claimTask(root, taskId, who = {}) {
       throw new TaskError(E.ALREADY_CLAIMED,
         `${taskId} was claimed by ${await holderOf(db, now)} a moment before this claim. Pick up another task.`);
     }
+    // The session is pointed at the task it just claimed.
+    //
+    // Claiming recorded an assignment and nothing else, so work_sessions.active_task_id
+    // stayed null on every session on every project. The session-start hook reads
+    // exactly that field to decide whether work is tracked, so it recorded an
+    // "untracked work" marker on every file edit, including edits made under a
+    // task that was claimed and in progress. The readiness report then raised its
+    // only high-severity warning, "changes were made while no task was claimed",
+    // against work that was properly tracked. A warning that fires when the rule
+    // was followed teaches the reader to stop reading warnings, and this is the
+    // one that means the record has fallen behind.
+    //
+    // Written here rather than in each caller, because the control centre claims
+    // tasks too and the field has to mean the same thing whichever surface moved it.
+    await pointSessionAt(db, task.project_id, sessionId, taskId);
+
     return db.get("SELECT * FROM tasks WHERE id = ?", taskId);
   });
 }
 
+/**
+ * Point a session at the task it is working on, or at nothing.
+ *
+ * The session is the one named, or the most recently active one on this machine,
+ * because a claim from the command line does not carry a session identifier and
+ * the hook that reads this field cannot ask.
+ */
+async function pointSessionAt(db, projectId, sessionId, taskId) {
+  const session = sessionId
+    ? await db.get("SELECT id FROM work_sessions WHERE id = ?", sessionId)
+    : await db.get(
+        `SELECT id FROM work_sessions
+          WHERE project_id = ? AND ended_at IS NULL
+          ORDER BY last_activity_at DESC, started_at DESC LIMIT 1`, projectId);
+  if (!session) return null;
+  await db.run(
+    "UPDATE work_sessions SET active_task_id = ?, last_activity_at = ? WHERE id = ?",
+    taskId, nowIso(), session.id,
+  );
+  return session.id;
+}
+
 /** Hand a task back. The task keeps its status; only the claim ends. */
 export async function releaseTask(root, taskId, { actor = "superdev", reason = null } = {}) {
   return mutate(root, async (db) => {