agent-dag 3.22.0 → 3.22.3

package/src/server/invoked-as.mjs

@@ -1,144 +0,0 @@
-// Which of the three published commands the user typed — and nothing else.
-//
-// The deck is on npm three times over — `ccdeck`, `agents-deck` and `agent-dag`
-// — and since #340 all three are literally the same tarball, published with
-// `name` set to each in turn. Every surface a human reads says ccdeck now, and
-// most of the downloads are still on the other two, so nothing closes that split
-// on its own. This file is the evidence behind saying so — once in the terminal,
-// once in the browser.
-//
-// Two rules make that safe, and they are the whole of the file.
-//
-// It is never a refusal. A build that declined to boot under an old name would
-// take the self-update path down with it: a user on `agents-deck` clicks
-// "Update & restart", the copy that arrives refuses to run, and the deck is
-// dead on the one machine where the deck was the thing that would have
-// explained why.
-//
-// And it is never asked of the PACKAGE. That was unarguable while ccdeck was a
-// stub — it depended on `agents-deck` and spawned its bin, so "is this build
-// agents-deck?" was true inside every ccdeck run, and a notice keyed on it would
-// have scolded exactly the people who did what we asked. #340 removed the stub
-// and the rule outlived it, because the three names are now ONE tarball: asking
-// the package what it is gets you whichever name the publish step happened to
-// set last, which is not evidence about the user at all. The question is which
-// name the USER TYPED. That is a different question, with a different answer,
-// and on one platform with no answer at all:
-//
-//   npx, everywhere — npm writes the literal spec into
-//     `_npx/<hash>/package.json` as `_npx.packages`, which npxRestartSpec
-//     already reads to decide what a restart re-runs. Reused rather than
-//     re-derived; the only difference here is that this caller has no fallback
-//     to offer, since a guess is the one answer it must not give.
-//
-//   a global install on macOS or Linux — npm links <prefix>/bin/<name> at the
-//     package's bin/agent-dag.js, and node does not resolve that symlink for
-//     argv[1]. All three names reach one file and only argv[1] tells them
-//     apart, so its last segment is the command that was typed. Verified with
-//     npm's own layout: a symlink named `ccdeck` gives argv[1] `…/bin/ccdeck`.
-//
-//   a global install on Windows — nowhere. npm writes <name>.cmd, <name>.ps1
-//     and an extensionless sh shim, each of which runs
-//     `node "…\node_modules\<pkg>\bin\agent-dag.js" %*` (npm's cmd-shim).
-//     The typed name is the shim's FILENAME and never becomes an argument, and
-//     there is no other carrier — npm_config_user_agent and friends are not set
-//     for a direct bin invocation. So Windows answers null.
-//
-//   a git checkout — nothing was typed. `node bin/agent-dag.js` is not any of
-//     the three names.
-//
-// Which leaves the callers one rule: positive identification, or silence. A
-// notice shown to somebody who already types `ccdeck` is worse than a notice
-// missed, because it is the failure that teaches everyone to ignore the next
-// one.
-import { bareSpecName, isNpxInstall, npxRestartSpec } from "./self-update.mjs";
-
-/** The command every surface promotes. Deliberately not brand.mjs's PRODUCT:
- *  that is the name a human reads, this is an npm bin name the user types, and
- *  the two are the same string only because the rename made them so —
- *  invoked-as.test.ts pins them against each other rather than assuming it. */
-export const PREFERRED = "ccdeck";
-
-/** Every command an install of this package provides, which is every name that
- *  can be typed. package.json's `bin` block is the other half of this list. */
-export const COMMANDS = [PREFERRED, "agents-deck", "agent-dag"];
-
-/** `value` when it is one of those three, and null for everything else — a shim
- *  filename with an extension on it, a path, a spec that resolved to some other
- *  package, an environment variable somebody set by hand. None of those are
- *  evidence of anything, and this function is the only place that decides so. */
-export function knownCommand(value) {
-  return typeof value === "string" && COMMANDS.includes(value) ? value : null;
-}
-
-/** The last segment of a path, split on both separators rather than `path.sep`
- *  — the same reason isNpxInstall gives: a Windows path can reach a POSIX
- *  process through a test or a config file, and a separator-agnostic split is
- *  what keeps this one function on all three platforms. */
-function lastSegment(path) {
-  if (typeof path !== "string") return null;
-  const parts = path.split(/[\\/]/);
-  return parts[parts.length - 1];
-}
-
-/**
- * The name the user typed, when we can prove it. Null means unknown, and
- * unknown must never produce a notice.
- */
-export function invokedAs({ pkgRoot, argv1, platform = process.platform } = {}) {
-  // npx first, and alone: under npx argv[1] is a path inside the cache
-  // directory, so the metadata is not the better answer, it is the only one.
-  // The explicit null fallback is the point of the call — npxRestartSpec's
-  // default is the package name, which is right for "what do I re-run" and
-  // would be a guess wearing an answer's clothes here.
-  if (isNpxInstall(pkgRoot)) return knownCommand(bareSpecName(npxRestartSpec(pkgRoot, null)));
-  // See the header: on Windows the shim eats the name. Decided on the platform
-  // rather than left to the extension check below, so that a Windows path that
-  // somehow did end in a bare name still cannot become a guess.
-  if (platform === "win32") return null;
-  return knownCommand(lastSegment(argv1));
-}
-
-/**
- * The same question, answered for the process that is asking it.
- *
- * bin/deck.js — and the server running inside it — is spawned BY the
- * supervisor, so its own argv[1] is `…/bin/deck.js` every single time: the
- * typed name reached bin/agent-dag.js and stopped there. The supervisor answers
- * once and passes the answer down in AGENTS_DECK_INVOKED_AS, which is read back
- * through knownCommand rather than trusted, since an environment variable is
- * user input like any other. The fall-through still answers the npx half for a
- * worker started with no supervisor above it.
- */
-export function invokedName({
-  env = process.env, pkgRoot, argv1 = process.argv[1], platform = process.platform,
-} = {}) {
-  return knownCommand(env?.AGENTS_DECK_INVOKED_AS) ?? invokedAs({ pkgRoot, argv1, platform });
-}
-
-/**
- * What the terminal says about it, or null when there is nothing to say.
- *
- * Two lines, because the second one is where the value is. Someone who ran
- * `npm i -g agents-deck` has nothing to install and nothing to download — the
- * same install already put a `ccdeck` on their PATH, and all they have to do is
- * type it. Handing them an install command instead would be work we invented.
- * Under npx there is no such install, so the fix there is the command itself.
- *
- * `dash` comes from the caller's glyph tier: an em dash is as absent from a
- * legacy Windows console as a check mark is, and this file must not be the one
- * place that forgets it.
- */
-export function renameNotice({ invoked, pkgRoot, dash = "—", preferred = PREFERRED } = {}) {
-  const name = knownCommand(invoked);
-  if (!name || name === preferred) return null;
-  return {
-    // Leads with the reassurance on purpose. Nothing is breaking here, no
-    // command is being taken away, and a line that opened with the rename would
-    // read as one that was.
-    said: `${name} still works ${dash} the deck is called ${preferred} now`,
-    fix: isNpxInstall(pkgRoot)
-      ? `next time: npx ${preferred}`
-      : `${preferred} already works here ${dash} same install, no download`,
-  };
-}

package/src/server/lan-about.mjs

@@ -1,119 +0,0 @@
-// What a paired deck says about itself: the version it runs and the machine it
-// runs on.
-//
-// ONLY TO A DECK THAT IS PAIRED, AND SEALED. The beacon is shouted at the whole
-// network and the hello is sent before anybody has proved anything, so neither
-// carries this: which build of which operating system a machine runs is the
-// first thing somebody hunting for a known-broken version would want, and
-// nobody on the network is owed it. It rides the manifest exchange, which only
-// happens between two decks that have each accepted the other — and it is
-// sealed with that connection's key, because the frames around it are JSON in
-// the clear on the wire.
-//
-// BOTH WAYS. The deck that dials sends its own card with the question, and the
-// deck that answers sends its own with the answer. A deck that only calls in —
-// paired, with no address this one can reach — is never asked anything, so the
-// card it sends when it calls is the only way this deck ever learns what it is.
-//
-// OLDER DECKS SAY NOTHING, AND NOTHING BREAKS. The field is extra on a frame
-// both versions already send: a deck from before this reads the accounts and
-// never looks at the rest, and a card that is absent is drawn as absent.
-import { readFileSync } from "node:fs";
-import { release as osRelease } from "node:os";
-import { open, seal } from "./lan-sync.mjs";
-
-/**
- * The operating system, in the words its owner would use.
- *
- * Node reports the KERNEL — `darwin 25.5.0`, `win32 10.0.26100` — and nobody
- * calls their laptop Darwin 25. So the numbers are translated on the machine
- * they describe, where the translation is certain, rather than on the one
- * reading them. Every input is a parameter, so all three platforms are tested
- * on any one of them.
- */
-export function osLabel({ platform, release = "", prettyName = "" } = {}) {
-  const [major, minor, build] = String(release).split(".").map(n => Number.parseInt(n, 10));
-  const dot = Number.isInteger(minor) ? `.${minor}` : "";
-  if (platform === "darwin") {
-    if (!Number.isInteger(major)) return "macOS";
-    // Darwin 20 was macOS 11 and every major after it was one more — until 25,
-    // which Apple shipped as macOS 26 to match the year.
-    if (major >= 25) return `macOS ${major + 1}${dot}`;
-    if (major >= 20) return `macOS ${major - 9}${dot}`;
-    // The 10.x years, where the kernel's major minus four is the second number.
-    return major >= 5 ? `macOS 10.${major - 4}` : "macOS";
-  }
-  if (platform === "win32") {
-    // Windows 11 kept the version 10.0 and moved only the build, and 22000 is
-    // the first one. From here it is the only way to tell the two apart.
-    if (major === 10 && Number.isInteger(build)) return build >= 22_000 ? "Windows 11" : "Windows 10";
-    return "Windows";
-  }
-  if (platform === "linux") return prettyName || "Linux";
-  return typeof platform === "string" && platform ? platform : "unknown";
-}
-
-/** The distribution's own name for itself, from the file every systemd-era
- *  distribution ships, with the fallback path the same spec names. Only ever
- *  read on Linux: the paths are Linux's and mean nothing anywhere else. */
-export function linuxPrettyName(read = readFileSync) {
-  for (const file of ["/etc/os-release", "/usr/lib/os-release"]) {
-    try {
-      const line = /^PRETTY_NAME=(.*)$/m.exec(String(read(file, "utf8")))?.[1];
-      const name = line?.trim().replace(/^(["'])(.*)\1$/, "$2").trim();
-      if (name) return name;
-    } catch { /* not this one */ }
-  }
-  return "";
-}
-
-/** This deck's own card. Built once, at start: nothing in it changes while the
- *  process lives, and an upgrade is a restart. */
-export function aboutThisDeck({
-  version = null, platform = process.platform, release = osRelease(), arch = process.arch, read = readFileSync,
-} = {}) {
-  return readAbout({
-    version,
-    os: osLabel({ platform, release, prettyName: platform === "linux" ? linuxPrettyName(read) : "" }),
-    arch,
-  });
-}
-
-/** One field of a card, or null. It came off the network, so it is a string of
- *  bounded length with no control characters — the rule cleanName applies to a
- *  deck's name, for the same reason: it reaches a terminal as well as a page.
- *  `\p{Cc}` is the Unicode class for exactly those, C0 and C1 both. */
-function field(v, max, shape = null) {
-  if (typeof v !== "string") return null;
-  const flat = v.replace(/\p{Cc}/gu, " ").replace(/\s+/g, " ").trim();
-  const s = [...flat].slice(0, max).join("").trim();
-  return s && (!shape || shape.test(s)) ? s : null;
-}
-
-/** A card, or null when there is nothing in it worth drawing. */
-export function readAbout(raw) {
-  if (!raw || typeof raw !== "object") return null;
-  const version = field(raw.version, 32, /^[0-9A-Za-z][0-9A-Za-z.+-]*$/);
-  const os = field(raw.os, 48);
-  const arch = field(raw.arch, 16, /^[0-9A-Za-z_]+$/);
-  return version || os || arch ? { version, os, arch } : null;
-}
-
-/** Bound to one connection AND one direction, so a card cannot be replayed
- *  back at the deck that sent it as if it were the other deck's. */
-const aboutAad = (fromFp, toFp) => `${fromFp}->${toFp}|about`;
-
-/** This deck's card, sealed for the deck on the other end of `key`. */
-export function sealAbout(key, about, fromFp, toFp) {
-  if (!key || !about) return null;
-  return seal(key, JSON.stringify(about), aboutAad(fromFp, toFp));
-}
-
-/** The other deck's card, or null — for a deck that sent none, and for one
- *  whose seal does not open, which mean the same thing to the panel. */
-export function openAbout(key, sealed, fromFp, toFp) {
-  if (!key || !sealed || typeof sealed !== "object") return null;
-  const text = open(key, sealed, aboutAad(fromFp, toFp));
-  if (text == null) return null;
-  try { return readAbout(JSON.parse(text)); } catch { return null; }
-}