dazzer-connect 0.3.0 → 0.4.1

package/README.md

@@ -69,12 +69,16 @@ Merge either one with any `mcpServers` entries you already have, save, and resta
 
 ## Put files into Dazzer
 
+Dazzer takes a new file only with a description of it. A single new file needs an entry under its own name in a descriptions file, passed with `--described-in`, just as a folder does. The descriptions file is shown below.
+
 ```bash
 dazzer add report.pdf
 dazzer add ./backlog
 ```
 
-A folder is walked with its subfolders. Hidden files are left alone, and nothing outside the folder is ever sent. The first time, you are asked which space things go in: run the same command again with `--space "<name>"`, or with `--keep-to-myself`. A folder run ends with a count of what went in and what was skipped. Add `--why` to see each file that was skipped, and why.
+A folder is walked with its subfolders. Hidden files are left alone, and nothing outside the folder is ever sent. The first time, you are asked which space things go in: run the same command again with `--space "<name>"`, or with `--keep-to-myself`. A folder run ends with a count of what went in and what was skipped. Add `--why` to see each file that was skipped, and why. A run that left a file out exits with a failure code. A file already in Dazzer was not left out. In a folder run, neither was a file held while you are asked whether it is a newer version of one already there.
+
+A folder run without a descriptions file sends nothing and says so.
 
 ### With what your assistant wrote about each file
 
@@ -104,7 +108,7 @@ Your own AI assistant can read the files and say what each one is. It writes tha
 }
 ```
 
-Save it beside the folder, never inside it — for example as `backlog-descriptions.json` next to `backlog`. Inside the folder, a later `dazzer add ./backlog` without `--described-in` would send it like any other file. Then:
+Save it beside the folder, never inside it — for example as `backlog-descriptions.json` next to `backlog`. Inside the folder, it is one more file a run has to tell apart from the documents. Then:
 
 ```bash
 dazzer add ./backlog --described-in ./backlog-descriptions.json
@@ -113,14 +117,24 @@ dazzer add ./backlog --described-in ./backlog-descriptions.json
 Each file goes with its own entry. The descriptions file named by `--described-in` is not sent with them, even when it sits inside the folder, and the run says to move it.
 
 - Each entry's form is checked before its file is sent. An entry in a form Dazzer refuses, such as a date written as "March 2026", holds its file back, and a line names the field and the form it takes. What the entry says is judged by Dazzer once the file has arrived.
-- A file with no entry goes in as usual, and the count names it.
-- An entry that names no file being added is reported, and nothing is sent for it. If no entry names a file being added, nothing is sent at all.
-- A file Dazzer refuses although it had an entry is named, in Dazzer's own words.
-- Whatever Dazzer did not keep of an entry is printed file by file, with what to change.
+- A file with no entry, or whose entry has no description, is not sent. The count says how many, and names them while there are few.
+- An entry that names no file being added is reported, and nothing is sent for it. If no entry names a file being added, or none has a description, nothing is sent at all.
+- A file Dazzer refuses is named, with why it was not added. A file refused for its kind or its size is only counted, and `--why` names it.
+- Whatever Dazzer did not keep of an entry is printed file by file, in plain words.
 - Sent again, a folder already in Dazzer says how many files took the description sent now, how many already had one, and how many did not take the one sent.
 
 An assistant that can run commands runs this one itself. One that cannot gives you the descriptions file to save beside the folder, and the line to run.
 
+## Keep it up to date
+
+Dazzer takes files only from a recent enough copy of this tool. An older copy is told so on its first call, before it sends anything, with the one command that updates it:
+
+```bash
+npm install -g dazzer-connect@latest
+```
+
+Once a day, the tool also tells you when a newer version is out. It looks at most once a day, never makes a command wait for the answer, and stays quiet if it cannot find out. What it remembers sits in the same settings folder as the rest of its state, below.
+
 ## Other commands
 
 ```bash

package/dist/index.js

@@ -8,6 +8,10 @@ import { Command } from "commander";
 import { open, stat as statPath } from "node:fs/promises";
 import { basename, extname } from "node:path";
 
+// src/lib/api-client.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
 // src/lib/output.ts
 function writeOut(message) {
   process.stdout.write(`${message}
@@ -19,6 +23,9 @@ function writeErr(message) {
 }
 var CANNOT_REACH_DAZZER = "I can't reach Dazzer right now \u2014 nothing was sent. Try again shortly.";
 var SIGN_IN_NO_LONGER_VALID = "Your Dazzer sign-in is no longer valid. Reconnect your client (or run `dazzer auth login`).";
+var RENEWED_SIGN_IN_NOT_SAVED = "Your sign-in was renewed, but this machine's credential store would not save it. Run: dazzer auth login";
+var UPDATE_THE_TOOL = "npm install -g dazzer-connect@latest";
+var newerToolIsOut = (version2) => `Version ${version2} of dazzer is out. Update it with: ${UPDATE_THE_TOOL}`;
 function printDeviceInstructions(deviceAuth) {
   writeOut("");
   if (deviceAuth.verification_uri_complete) {
@@ -89,6 +96,9 @@ function printAuthStatus(params) {
       writeOut("  Common on servers and containers, which often have none.");
       writeOut("  Run: dazzer auth login \u2014 it prints a pass you can paste in.");
       return;
+    case "save-refused":
+      writeOut(RENEWED_SIGN_IN_NOT_SAVED);
+      return;
     case "expired":
       writeOut("Your sign-in has expired or been revoked. Run: dazzer auth login");
       return;
@@ -193,6 +203,12 @@ var RefreshRejectedError = class extends Error {
   }
   oauthError;
 };
+var RenewedSignInNotSavedError = class extends Error {
+  constructor() {
+    super("The credential store would not save the renewed sign-in.");
+    this.name = "RenewedSignInNotSavedError";
+  }
+};
 async function refreshAccessToken(options) {
   const fetchFn = options.fetchFn ?? fetch;
   const params = new URLSearchParams({
@@ -220,7 +236,11 @@ async function refreshAccessToken(options) {
   }
   const newRefresh = typeof refreshToken === "string" ? refreshToken : options.refreshToken;
   const expiresIn = typeof body.expires_in === "number" ? body.expires_in : null;
-  await options.tokenStore.save({ accessToken, refreshToken: newRefresh });
+  try {
+    await options.tokenStore.save({ accessToken, refreshToken: newRefresh });
+  } catch {
+    throw new RenewedSignInNotSavedError();
+  }
   return { accessToken, refreshToken: newRefresh, expiresIn };
 }
 async function getValidAccessToken(options) {
@@ -235,6 +255,9 @@ async function getValidAccessToken(options) {
     if (err instanceof RefreshRejectedError) {
       return { status: "rejected" };
     }
+    if (err instanceof RenewedSignInNotSavedError) {
+      return { status: "save-refused" };
+    }
     return { status: "unreachable" };
   }
 }
@@ -315,6 +338,31 @@ function refusalPlaces(body) {
     ...typeof keep === "boolean" ? { keepToYourself: keep } : {}
   };
 }
+var wordsIn = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
+function refusalAbout(body) {
+  if (typeof body !== "object" || body === null) return {};
+  const flat = body;
+  const enveloped = typeof flat.error === "object" && flat.error !== null ? flat.error.details : void 0;
+  const fields = [
+    ...wordsIn(flat.field) === void 0 ? [] : [flat.field],
+    ...Array.isArray(enveloped) ? enveloped.flatMap((detail) => {
+      const named2 = typeof detail === "object" && detail !== null ? wordsIn(detail.field) : void 0;
+      return named2 === void 0 ? [] : [named2];
+    }) : []
+  ];
+  const dropped = Array.isArray(flat.dropped) ? flat.dropped.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null) return [];
+    const line = wordsIn(entry.line);
+    const reason = wordsIn(entry.reason);
+    return line === void 0 || reason === void 0 ? [] : [{ line, reason }];
+  }) : [];
+  const howMuch = typeof flat.how_much_was_read === "object" && flat.how_much_was_read !== null ? wordsIn(flat.how_much_was_read.reason) : void 0;
+  return {
+    ...fields.length > 0 ? { fields } : {},
+    ...dropped.length > 0 ? { dropped } : {},
+    ...howMuch === void 0 ? {} : { howMuchWasRead: howMuch }
+  };
+}
 async function resolveCredential(auth2) {
   let held;
   try {
@@ -334,6 +382,8 @@ async function resolveCredential(auth2) {
       return { status: "signed-out" };
     case "rejected":
       return { status: "sign-in-invalid" };
+    case "save-refused":
+      return { status: "save-refused" };
     case "unreachable":
       return { held: held.accessToken };
     case "refreshed": {
@@ -353,6 +403,9 @@ async function callDazzer(request) {
     if (credential.status === "sign-in-invalid") {
       return { status: "sign-in-invalid", message: SIGN_IN_NO_LONGER_VALID };
     }
+    if (credential.status === "save-refused") {
+      return { status: "sign-in-invalid", message: RENEWED_SIGN_IN_NOT_SAVED };
+    }
     return { status: credential.status };
   }
   const fetchFn = request.fetchFn ?? fetch;
@@ -384,15 +437,99 @@ async function callDazzer(request) {
       httpStatus: res.status,
       ...detail === void 0 ? {} : { detail },
       ...code === void 0 ? {} : { code },
-      ...refusalPlaces(body)
+      ...refusalPlaces(body),
+      ...refusalAbout(body)
     };
   }
   return { status: "ok", httpStatus: res.status, body };
 }
+var REGISTRY = "https://registry.npmjs.org";
+var LOOK_AT_MOST_MS = 3e3;
+var A_DAY_MS = 24 * 60 * 60 * 1e3;
+var NEWER_TOOL_FILE = "newer-version.json";
+function releaseOf(version2) {
+  if (typeof version2 !== "string") return null;
+  const said = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/.exec(version2);
+  return said === null ? null : [Number(said[1]), Number(said[2]), Number(said[3])];
+}
+function isLater(published, mine) {
+  const theirs = releaseOf(published);
+  const own = /^(\d{1,6}\.\d{1,6}\.\d{1,6})(-[^+]+)?(\+.+)?$/.exec(mine);
+  const ours = own === null ? null : releaseOf(own[1]);
+  if (theirs === null || own === null || ours === null) return false;
+  for (let at = 0; at < 3; at += 1) {
+    if (theirs[at] !== ours[at]) return (theirs[at] ?? 0) > (ours[at] ?? 0);
+  }
+  return own[2] !== void 0;
+}
+async function recall(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function remember(folder, file, what) {
+  try {
+    await mkdir(folder, { recursive: true });
+    await writeFile(file, `${JSON.stringify(what)}
+`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+var withinADay = (then, now) => typeof then === "number" && Number.isFinite(then) && then <= now && now - then < A_DAY_MS;
+function lookForNewerTool(check) {
+  const now = check.now ?? Date.now;
+  const file = join(check.folder, NEWER_TOOL_FILE);
+  const stop = new AbortController();
+  const looked = (async () => {
+    try {
+      const before = await recall(file);
+      if (withinADay(before.looked_at, now()) || stop.signal.aborted) return;
+      const signal = AbortSignal.any([
+        stop.signal,
+        AbortSignal.timeout(check.lookAtMostMs ?? LOOK_AT_MOST_MS)
+      ]);
+      const res = await (check.fetchFn ?? fetch)(
+        `${REGISTRY}/${encodeURIComponent(check.name)}/latest`,
+        { headers: { accept: "application/json" }, signal }
+      );
+      const published = res.ok ? (await res.json()).version : void 0;
+      if (stop.signal.aborted) return;
+      const latest = releaseOf(published) === null ? void 0 : published;
+      await remember(check.folder, file, {
+        ...await recall(file),
+        looked_at: now(),
+        ...latest === void 0 ? {} : { latest }
+      });
+    } catch {
+    }
+  })();
+  return {
+    looked,
+    finish: async () => {
+      stop.abort();
+      try {
+        await looked;
+        const known = await recall(file);
+        const latest = known.latest;
+        if (typeof latest !== "string" || !isLater(latest, check.version)) return null;
+        if (withinADay(known.told_at, now())) return null;
+        const kept = await remember(check.folder, file, { ...known, told_at: now() });
+        return kept ? newerToolIsOut(latest) : null;
+      } catch {
+        return null;
+      }
+    }
+  };
+}
 
 // src/lib/config-store.ts
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir as mkdir2, readFile as readFile2, unlink, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
 import envPaths from "env-paths";
 
 // src/lib/discovery.ts
@@ -456,9 +593,9 @@ async function discoverEndpoints(issuer, fetchFn = fetch) {
 
 // src/lib/config-store.ts
 var paths = envPaths("dazzer", { suffix: "" });
-var CONFIG_FILE = join(paths.config, "auth.json");
+var CONFIG_FILE = join2(paths.config, "auth.json");
 async function ensureConfigDir() {
-  await mkdir(paths.config, { recursive: true });
+  await mkdir2(paths.config, { recursive: true });
 }
 var MAX_CLIENT_ID_LENGTH = 512;
 async function saveAuthMetadata(meta) {
@@ -471,12 +608,12 @@ async function saveAuthMetadata(meta) {
   const savedToStore = typeof meta.savedToStore === "boolean" ? meta.savedToStore : void 0;
   await ensureConfigDir();
   const checked = { issuer, clientId, expiresAt, savedToStore };
-  await writeFile(CONFIG_FILE, `${JSON.stringify(checked, null, 2)}
+  await writeFile2(CONFIG_FILE, `${JSON.stringify(checked, null, 2)}
 `, "utf8");
 }
 async function loadAuthMetadata() {
   try {
-    const raw = await readFile(CONFIG_FILE, "utf8");
+    const raw = await readFile2(CONFIG_FILE, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.issuer !== "string" || typeof parsed.clientId !== "string") {
       return null;
@@ -605,9 +742,17 @@ var KeychainTokenStore = class {
     this.openEntry = openEntry;
   }
   openEntry;
+  /**
+   * THE REFRESH TOKEN IS WRITTEN FIRST, AND IF IT WILL NOT BE, NOTHING ELSE IS TOUCHED. After a renewal
+   * the saved refresh token is already spent at the sign-in server. Writing the access token first and
+   * then failing on the refresh token left a new access token beside that spent one, which read as a
+   * fresh sign-in until it failed to renew. In this order a refused first write changes nothing, and
+   * a refused second write leaves the new refresh token, which can still renew. Either way the
+   * refusal reaches the caller, which says so rather than calling it anything else.
+   */
   async save(tokens) {
-    this.openEntry(ACCESS_ACCOUNT).setPassword(tokens.accessToken);
     this.openEntry(REFRESH_ACCOUNT).setPassword(tokens.refreshToken);
+    this.openEntry(ACCESS_ACCOUNT).setPassword(tokens.accessToken);
   }
   async load() {
     const accessToken = this.openEntry(ACCESS_ACCOUNT).getPassword();
@@ -642,7 +787,7 @@ function createTokenStore() {
 
 // src/lib/walk.ts
 import { readdir, realpath, stat } from "node:fs/promises";
-import { join as join2, sep } from "node:path";
+import { join as join3, sep } from "node:path";
 function inside(base, candidate) {
   return candidate === base || candidate.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
 }
@@ -667,7 +812,7 @@ async function walkFolder(root) {
     entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
-      const full = join2(dir, entry.name);
+      const full = join3(dir, entry.name);
       const relative = `${prefix}${entry.name}`;
       if (entry.isSymbolicLink()) {
         await followShortcut(full, relative);
@@ -774,6 +919,10 @@ function namingNoFile(keys) {
 var noEntryMatches = (name2, example) => `No entry in ${name2} names a file being added \u2014 nothing was sent.` + (example === void 0 ? "" : ` A key looks like ${JSON.stringify(asPrinted(example))}.`);
 var keepItBeside = "The descriptions file is inside the folder. Keep it beside the folder instead, so no later run sends it as a document.";
 var itHadNoDescription = "It had no description.";
+var NOTHING_DESCRIBED = "Nothing was sent. No file here has a description.";
+var DESCRIBE_THEM = "Write what each file is in a descriptions file. Then run this again with --described-in.";
+var notSentNoDescription = (name2) => `${name2} was not sent. It has no description.`;
+var notAdded = (name2, because2) => [`${name2} was not added.`, ...because2].join(" ");
 function alreadyThereDescriptions(counted) {
   const parts = [
     ...counted.filed > 0 ? [`${counted.filed} took the description sent now`] : [],
@@ -933,6 +1082,7 @@ async function settleSpace(options, auth2, deps, voice, name2) {
 var HELD_FOR_AN_ANSWER = "same_name_different_contents";
 function fromAnswer(answer) {
   if (answer.status === "refused") {
+    if (aboutThisTool(answer)) return { kind: "stop", answer };
     if (answer.code === HELD_FOR_AN_ANSWER && answer.detail !== void 0) {
       return { kind: "held", question: answer.detail };
     }
@@ -943,11 +1093,17 @@ function fromAnswer(answer) {
       // Carried, not filled in: absent stays absent, so nothing downstream can print an offer the
       // service did not make.
       ...answer.choices === void 0 ? {} : { choices: answer.choices },
-      ...answer.keepToYourself === void 0 ? {} : { keepToYourself: answer.keepToYourself }
+      ...answer.keepToYourself === void 0 ? {} : { keepToYourself: answer.keepToYourself },
+      ...answer.fields === void 0 ? {} : { fields: answer.fields },
+      ...answer.dropped === void 0 ? {} : { dropped: answer.dropped },
+      ...answer.howMuchWasRead === void 0 ? {} : { howMuchWasRead: answer.howMuchWasRead }
     };
   }
   return { kind: "stop", answer };
 }
+function aboutThisTool(answer) {
+  return answer.status === "refused" && answer.fields?.includes(CLIENT_HEADER) === true;
+}
 async function sendOne(input) {
   const { deps, handle, options, voice } = input;
   const described = await callPaced(
@@ -1208,8 +1364,22 @@ var LINE_DROPPED = {
   "line-verbatim-from-document": "its words are copied out of the document",
   "quote-empty": "it quotes nothing",
   "quote-too-long": "its quote is too long",
+  "unstorable-characters": "it holds a character that cannot be stored",
   "quote-not-in-document": "the words it quotes are not in the document"
 };
+var A_LINE = {
+  what_it_is: "The line saying what it is",
+  what_it_covers: "The line saying what it covers",
+  what_it_decides: "The line saying what it decides"
+};
+var HOW_MUCH_NOT_KEPT = {
+  "not-said": "Its description does not say how much of the file was read.",
+  "which-part-empty": "Its description says only part of the file was read, and not which part.",
+  "which-part-unstorable-characters": "The part it says was read holds a character that cannot be stored.",
+  "which-part-too-long": "The part it says was read is too long. Say it in one short sentence.",
+  "which-part-line-break-or-marker": "The part it says was read is not one plain line."
+};
+var HOW_MUCH_NOT_KEPT_OTHERWISE = "Its description does not say how much of the file was read in a form Dazzer keeps.";
 var FACT_DROPPED = {
   "fact-empty": "it has no words",
   "fact-too-long": "it is too long",
@@ -1231,8 +1401,44 @@ var TYPING_NOT_USED = {
   not_used_file_has_its_own_text: "the file has words of its own",
   not_used_document_already_held: "the document was already here"
 };
-var inPlainWords = (words, name2) => words[name2] ?? name2;
-var SHORT_EXAMPLE = 120;
+var because = (words, name2) => {
+  const said = words[name2];
+  return said === void 0 ? ` (${name2}).` : `, because ${said}.`;
+};
+var lineNotKept = (dropped) => `${A_LINE[dropped.line] ?? "A line of its description"} was not kept${because(LINE_DROPPED, dropped.reason)}`;
+var howMuchNotKept = (reason) => HOW_MUCH_NOT_KEPT[reason] ?? HOW_MUCH_NOT_KEPT_OTHERWISE;
+function whatToDoAbout(refused) {
+  return refused.code === "description_missing" ? DESCRIBE_THEM : void 0;
+}
+var ADD_THE_TEXT = "Add the text you read in it to its entry.";
+function notAddedBecause(refused) {
+  const dropped = (refused.dropped ?? []).map(lineNotKept);
+  const howMuch = refused.howMuchWasRead === void 0 ? [] : [howMuchNotKept(refused.howMuchWasRead)];
+  switch (refused.code) {
+    case "description_missing":
+      return ["It has no description."];
+    case "description_not_kept": {
+      const noLineKept = refused.fields?.includes("description") === true;
+      const said = [...noLineKept ? ["No line of its description was kept."] : [], ...dropped];
+      const all = [...said, ...howMuch];
+      return all.length > 0 ? all : ["Its description was not kept."];
+    }
+    case "nothing_to_check_it_against":
+      return [
+        "Dazzer holds no words of it to check its description against.",
+        ADD_THE_TEXT,
+        ...howMuch
+      ];
+    case "transcription_too_long":
+      return ["The text typed out of it is longer than Dazzer keeps for one file."];
+    case "try_again_shortly":
+      return ["It could not be read just now. Try again shortly."];
+    case "could_not_read_it":
+      return ["Dazzer could not read its words.", ADD_THE_TEXT];
+    default:
+      return void 0;
+  }
+}
 function whatBecameOfIt(stored, alreadyHere, descriptionSent) {
   const lines = [];
   let filing;
@@ -1240,34 +1446,25 @@ function whatBecameOfIt(stored, alreadyHere, descriptionSent) {
   if (description !== null) {
     const state = wordsOf(description.state);
     const what = wordsOf(description.what);
-    const how = wordsOf(description.how);
     if (descriptionSent && state !== void 0) {
       filing = state === "filed" ? "filed" : alreadyHere && state === "not_filed" && what === void 0 ? "already-described" : "not-kept";
     }
     if (state === "not_filed" && what !== void 0) {
-      lines.push(how === void 0 ? what : `${what} ${how}`);
+      lines.push("Its description was not kept.");
     } else if (state !== void 0 && state !== "filed" && state !== "none_supplied" && !(alreadyHere && state === "not_filed")) {
       lines.push(
-        state === "not_filed" ? "description not filed." : `description not filed: ${inPlainWords(DESCRIPTION_NOT_FILED, state)}`
+        state === "not_filed" ? "Its description was not filed." : `Its description was not filed${because(DESCRIPTION_NOT_FILED, state)}`
       );
     }
     for (const dropped of listOf(description.dropped)) {
       if (!isPlainObject(dropped)) continue;
       const line = wordsOf(dropped.line);
       const reason = wordsOf(dropped.reason);
-      const what2 = wordsOf(dropped.what);
-      const how2 = wordsOf(dropped.how);
-      const why = what2 === void 0 ? reason === void 0 ? void 0 : inPlainWords(LINE_DROPPED, reason) : how2 === void 0 ? what2 : `${what2} ${how2}`;
-      if (line !== void 0 && why !== void 0) lines.push(`${line} dropped: ${why}`);
+      if (line !== void 0 && reason !== void 0) lines.push(lineNotKept({ line, reason }));
     }
     const howMuch = isPlainObject(description.how_much_was_read) ? description.how_much_was_read : null;
-    const howMuchWhat = howMuch === null ? void 0 : wordsOf(howMuch.what);
-    if (howMuch !== null && howMuchWhat !== void 0) {
-      const howMuchHow = wordsOf(howMuch.how);
-      const example = howMuch.example === void 0 ? "" : JSON.stringify(howMuch.example);
-      lines.push(
-        `how_much_was_read not kept: ${howMuchWhat}` + (howMuchHow === void 0 ? "" : ` ${howMuchHow}`) + (example !== "" && example.length <= SHORT_EXAMPLE ? ` Example: ${example}` : "")
-      );
+    if (howMuch !== null && wordsOf(howMuch.what) !== void 0) {
+      lines.push(howMuchNotKept(wordsOf(howMuch.reason) ?? ""));
     }
   }
   const facts = isPlainObject(stored.facts) ? stored.facts : null;
@@ -1275,16 +1472,16 @@ function whatBecameOfIt(stored, alreadyHere, descriptionSent) {
     if (!isPlainObject(dropped)) continue;
     const reason = wordsOf(dropped.reason);
     if (typeof dropped.fact === "number" && reason !== void 0) {
-      lines.push(`fact ${dropped.fact} dropped: ${inPlainWords(FACT_DROPPED, reason)}`);
+      lines.push(`Fact ${dropped.fact} was not kept${because(FACT_DROPPED, reason)}`);
     }
   }
   const date = isPlainObject(stored.date_not_kept) ? wordsOf(stored.date_not_kept.reason) : void 0;
   if (date !== void 0 && !(alreadyHere && date === "document-already-held")) {
-    lines.push(`document_date not kept: ${inPlainWords(DATE_NOT_KEPT, date)}`);
+    lines.push(`Its date was not kept${because(DATE_NOT_KEPT, date)}`);
   }
   const typed = wordsOf(stored.transcription);
   if (typed !== void 0 && typed !== "used" && !(alreadyHere && typed === "not_used_document_already_held")) {
-    lines.push(`transcription not used: ${inPlainWords(TYPING_NOT_USED, typed)}`);
+    lines.push(`The text typed out of it was not used${because(TYPING_NOT_USED, typed)}`);
   }
   return {
     notKept: lines.map(asPrinted),
@@ -1305,6 +1502,7 @@ async function openOne(path) {
     return err?.code === "ENOENT" ? "missing" : "cannot-open";
   }
 }
+var LEAVES_A_FILE_OUT = (skip) => skip.reason !== "already-here" && skip.reason !== "the-descriptions-file";
 var REASON_ORDER = [
   "type-not-readable",
   "too-large",
@@ -1314,6 +1512,7 @@ var REASON_ORDER = [
   "did-not-finish",
   "leads-out",
   "entry-wrong-shape",
+  "no-description",
   "the-descriptions-file"
 ];
 var NAMED_ALWAYS = /* @__PURE__ */ new Set(["entry-wrong-shape"]);
@@ -1331,6 +1530,7 @@ var COUNTED = {
   "did-not-finish": (many) => `${many} that didn't finish`,
   "leads-out": (many) => `${many} shortcut${many === 1 ? "" : "s"} out of the folder`,
   "entry-wrong-shape": (many) => `${many} with an entry in the wrong shape`,
+  "no-description": (many) => `${many} with no description`,
   "the-descriptions-file": (many) => `${many} that ${many === 1 ? "is" : "are"} the descriptions file`
 };
 var IN_DETAIL = {
@@ -1342,10 +1542,11 @@ var IN_DETAIL = {
   "did-not-finish": "the send didn't finish",
   "leads-out": "a shortcut out of the folder",
   "entry-wrong-shape": "not sent: its entry is in the wrong shape.",
+  "no-description": "not sent: it has no description.",
   "the-descriptions-file": "the descriptions file itself, never sent"
 };
-function countLine(added, space, skipped, why, undescribed = []) {
-  const documents = `${added} document${added === 1 ? "" : "s"} in ${named(space)}.` + (undescribed.length === 0 ? "" : ` ${undescribed.length} had no description${undescribed.length <= NAMED_WHEN_AT_MOST ? ` \u2014 ${listed(undescribed.map(asPrinted))}` : ""}.`);
+function countLine(added, space, skipped, why) {
+  const documents = `${added} document${added === 1 ? "" : "s"} in ${named(space)}.`;
   if (skipped.length === 0) return documents;
   const reasons = REASON_ORDER.flatMap((reason) => {
     const many = skipped.filter((skip) => skip.reason === reason).length;
@@ -1355,8 +1556,9 @@ function countLine(added, space, skipped, why, undescribed = []) {
   return `${documents} ${skipped.length} skipped \u2014 ${reasons}.${pointAtWhy ? " Run with --why to see each." : ""}`;
 }
 function whyLine(skip) {
-  const because = skip.said === void 0 ? IN_DETAIL[skip.reason] : skip.reason === "refused" ? `refused: ${skip.said}` : skip.said;
-  return `${asPrinted(skip.relative)} \u2014 ${because}`;
+  if (skip.line !== void 0) return skip.line;
+  const because2 = skip.said === void 0 ? IN_DETAIL[skip.reason] : skip.reason === "refused" ? `refused: ${skip.said}` : skip.said;
+  return `${asPrinted(skip.relative)} \u2014 ${because2}`;
 }
 var FROM_THE_WALK = {
   "leads-out": "leads-out",
@@ -1447,7 +1649,7 @@ async function addOneFile(options, deps, voice, descriptions) {
       );
     }
     if (outcome.kind === "added" || outcome.kind === "already-here") {
-      for (const line of outcome.notKept) voice.write(`${name2} \u2014 ${line}`);
+      for (const line of outcome.notKept) voice.write(`${name2}: ${line}`);
     }
     return result;
   } finally {
@@ -1472,11 +1674,18 @@ function answerForOneFile(outcome, name2, voice) {
       return { ok: false };
     // ONE FILE, ONE REFUSAL, AND THE PLACES IT OFFERED. The sentence is the service's and is
     // printed as sent; the places under it are the service's too, and without them a refusal
-    // that says to name one of them is a dead end for the person holding this one file.
-    case "refused":
-      voice.write(outcome.said ?? wentWrong(name2));
+    // that says to name one of them is a dead end for the person holding this one file. A refusal
+    // whose sentence is written for whoever makes the call is said in this command's own words.
+    case "refused": {
+      const because2 = notAddedBecause(outcome);
+      voice.write(
+        because2 === void 0 ? outcome.said ?? wentWrong(name2) : notAdded(name2, because2)
+      );
+      const next = whatToDoAbout(outcome);
+      if (next !== void 0) voice.write(next);
       offerThePlaces(voice.write, outcome);
       return { ok: false };
+    }
     case "did-not-finish":
       voice.write(didNotFinish(name2));
       return { ok: false };
@@ -1521,6 +1730,17 @@ async function addFolder(options, deps, voice, descriptions) {
     );
     return { ok: false };
   }
+  const worthAsking = walked.files.some((file) => {
+    const entry = descriptions?.entries.get(asKey(file.relative));
+    if (entry === void 0) return false;
+    const checked = checkEntry(entry);
+    return "wrong" in checked || "description" in checked.described;
+  });
+  if (walked.files.length > 0 && !worthAsking) {
+    voice.write(NOTHING_DESCRIBED);
+    voice.write(DESCRIBE_THEM);
+    return { ok: false };
+  }
   const auth2 = deps.auth ?? await resolveAuth(options);
   if (auth2 === null) {
     voice.write(CANNOT_REACH_DAZZER);
@@ -1535,7 +1755,6 @@ async function addFolder(options, deps, voice, descriptions) {
   const held = [];
   let added = 0;
   let ran = true;
-  const undescribed = [];
   const notKept = [];
   const alreadyThere = { filed: 0, alreadyDescribed: 0, notKept: 0 };
   for (const file of walked.files) {
@@ -1553,6 +1772,16 @@ async function addFolder(options, deps, voice, descriptions) {
       }
       described = checked.described;
     }
+    if (described === void 0 || !("description" in described)) {
+      skipped.push(
+        descriptions !== void 0 && await isFile(file.path, descriptions.identity) ? { relative: file.relative, reason: "the-descriptions-file" } : {
+          relative: file.relative,
+          reason: "no-description",
+          line: notSentNoDescription(asPrinted(file.relative))
+        }
+      );
+      continue;
+    }
     const handle = await openOne(file.path);
     if (typeof handle === "string") {
       skipped.push({ relative: file.relative, reason: "cannot-open" });
@@ -1589,9 +1818,6 @@ async function addFolder(options, deps, voice, descriptions) {
     }
     if (outcome.kind === "added") {
       added += 1;
-      if (descriptions !== void 0 && !("description" in (described ?? {}))) {
-        undescribed.push(file.relative);
-      }
       continue;
     }
     if (outcome.kind === "already-here") {
@@ -1607,16 +1833,19 @@ async function addFolder(options, deps, voice, descriptions) {
       continue;
     }
     if (outcome.kind === "refused") {
+      const because2 = notAddedBecause(outcome);
+      const reason = (outcome.code === void 0 ? void 0 : FROM_THE_SERVICE[outcome.code]) ?? "refused";
       skipped.push({
         relative: file.relative,
-        // KEYED ON THE SERVICE'S CODE, never on the words it sent: the words are the person's and
-        // may be reworded, the code is the label the service publishes.
-        reason: (outcome.code === void 0 ? void 0 : FROM_THE_SERVICE[outcome.code]) ?? "refused",
+        reason,
         ...outcome.said === void 0 ? {} : { said: outcome.said },
-        // REFUSED ALTHOUGH IT CARRIED AN ENTRY: most likely about what the entry says, which only
-        // the person's assistant can put right — so it is named, in the service's own sentence,
-        // without anybody having to run the whole folder again with `--why` to find out.
-        ...described === void 0 ? {} : { named: true }
+        ...because2 === void 0 ? {} : { line: notAdded(asPrinted(file.relative), because2) },
+        // REFUSED ALTHOUGH IT CARRIED AN ENTRY, which every file sent now does: most likely about
+        // what the entry says, which only the person's assistant can put right, so it is named
+        // without anybody having to run the whole folder again with `--why`. A refusal about the
+        // file's kind or size is about the file, not its entry, so it stays a count that `--why`
+        // names: a folder with thirty spreadsheets in it is one line, not thirty.
+        ...reason === "refused" ? { named: true } : {}
       });
       continue;
     }
@@ -1636,7 +1865,11 @@ async function addFolder(options, deps, voice, descriptions) {
   skipped.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
   held.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
   notKept.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
-  voice.write(countLine(added, settled.space, skipped, options.why === true, undescribed));
+  const undescribed = skipped.filter((skip) => skip.reason === "no-description");
+  if (undescribed.length <= NAMED_WHEN_AT_MOST) {
+    for (const skip of undescribed) skip.named = true;
+  }
+  voice.write(countLine(added, settled.space, skipped, options.why === true));
   if (skipped.some((skip) => skip.reason === "the-descriptions-file")) voice.write(keepItBeside);
   if (alreadyThere.filed + alreadyThere.alreadyDescribed + alreadyThere.notKept > 0) {
     voice.write(alreadyThereDescriptions(alreadyThere));
@@ -1647,7 +1880,7 @@ async function addFolder(options, deps, voice, descriptions) {
     if (options.why === true || namedWithoutWhy(skip)) voice.write(whyLine(skip));
   }
   for (const one of notKept) {
-    for (const line of one.lines) voice.write(`${asPrinted(one.relative)} \u2014 ${line}`);
+    for (const line of one.lines) voice.write(`${asPrinted(one.relative)}: ${line}`);
   }
   const onlyOne = held.length === 1 ? held[0] : void 0;
   if (onlyOne !== void 0) {
@@ -1660,7 +1893,15 @@ async function addFolder(options, deps, voice, descriptions) {
       )
     );
   }
-  return { ok: ran };
+  return { ok: ran && !skipped.some(LEAVES_A_FILE_OUT) };
+}
+async function isFile(path, identity) {
+  try {
+    const info = await statPath(path, { bigint: true });
+    return sameFile({ dev: info.dev, ino: info.ino }, identity);
+  } catch {
+    return false;
+  }
 }
 async function aKeyItWouldMatch(files, descriptionsFile) {
   for (const file of files) {
@@ -2348,6 +2589,9 @@ async function runStatus(options) {
     case "rejected":
       printAuthStatus({ state: "expired" });
       return;
+    case "save-refused":
+      printAuthStatus({ state: "save-refused" });
+      return;
     case "unreachable":
       printAuthStatus({
         state: "unverified",
@@ -2399,6 +2643,15 @@ var { name, version } = require2("../package.json");
 var client = `${name}/${version}`;
 var program = new Command();
 program.name("dazzer").description("Sign in to Dazzer from your terminal").version(version);
+var newerTool;
+program.hook("preAction", () => {
+  newerTool = lookForNewerTool({ name, version, folder: getConfigDir() });
+});
+program.hook("postAction", async () => {
+  const said = await newerTool?.finish();
+  if (said) process.stderr.write(`${said}
+`);
+});
 program.command("add").description("Put a file, or a whole folder, into Dazzer").argument("<path>", "The file or folder to add").option("--space <name>", "The space to put it in \u2014 the name you were shown, or its number").option("--keep-to-myself", "Keep it to yourself, rather than putting it in a shared space").option("--why", "Show each document that was skipped, and why").option(
   "--described-in <file>",
   "A JSON file saying what each file is, keyed by its path inside the folder"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dazzer-connect",
   "private": false,
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Sign in to Dazzer \u2014 the memory your AI tools share \u2014 from a terminal, for clients that cannot sign in themselves",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@dazzer/auth-ui": "workspace:*",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.3",
     "esbuild": "^0.28.2",
     "tsx": "^4.23.15",
     "typescript": "^5.7.2",