agmsg-cloud 0.1.0 → 0.1.2

package/dist/scripts/version-output.js

@@ -0,0 +1,65 @@
+// The `--version` contract, parsed as records rather than searched for.
+//
+// The command answers with TWO facts now (#341) — which build, and which copy
+// of it answered — and a check that takes the first line matching each shape
+// cannot tell one answer from two disagreeing ones. A binary printing two
+// identity lines is broken in a way that matters precisely when several
+// installs are in play, which is the situation the second line was added for;
+// `find` would report the first and call it a pass.
+//
+// So: exactly one of each, nothing else, and the version read from the identity
+// line alone. That last part is not tidiness. A directory carries
+// version-shaped fragments of its own — a node prefix, a store entry, an npx
+// cache path — and scanning the whole output for "every version here is the one
+// asked for" fails a CORRECT package the moment it is installed under such a
+// path. A verification that fails good releases is worse than none: the next
+// real failure gets waved through as another false alarm.
+export const IDENTITY_PREFIX = 'agmsg-cloud/';
+export const FROM_PREFIX = 'running from ';
+const VERSION_SHAPED = /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g;
+/** Distinct version-shaped tokens in one string, in order of first appearance. */
+export function versionsIn(text) {
+    return [...new Set(text.match(VERSION_SHAPED) ?? [])];
+}
+/**
+ * Read `--version` output as the pair of records it is.
+ *
+ * Every rejection names what was seen, because this runs against a published
+ * artifact where the next question is always "then what DID it print".
+ */
+export function parseVersionOutput(output) {
+    const lines = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+    const identity = lines.filter((line) => line.startsWith(IDENTITY_PREFIX));
+    const from = lines.filter((line) => line.startsWith(FROM_PREFIX));
+    const other = lines.filter((line) => !line.startsWith(IDENTITY_PREFIX) && !line.startsWith(FROM_PREFIX));
+    if (identity.length === 0)
+        return { ok: false, reason: `no \`${IDENTITY_PREFIX}<version>\` line` };
+    if (identity.length > 1) {
+        return { ok: false, reason: `${identity.length} identity lines: ${identity.join(' | ')}` };
+    }
+    if (from.length === 0)
+        return { ok: false, reason: `no \`${FROM_PREFIX}<directory>\` line` };
+    if (from.length > 1) {
+        return { ok: false, reason: `${from.length} \`${FROM_PREFIX.trim()}\` lines: ${from.join(' | ')}` };
+    }
+    // Anything else is unexplained output, and this command's whole purpose is to
+    // be readable when something else has already gone wrong.
+    if (other.length > 0)
+        return { ok: false, reason: `unexpected output: ${other.join(' | ')}` };
+    const version = identity[0].slice(IDENTITY_PREFIX.length).trim();
+    if (version === '')
+        return { ok: false, reason: `identity line names no version: ${identity[0]}` };
+    // The identity line must carry ONE version and it must be the one it names —
+    // `agmsg-cloud/1.2.3 (from 4.5.6)` is two claims wearing one line.
+    const onLine = versionsIn(identity[0]);
+    if (onLine.length !== 1 || onLine[0] !== version) {
+        return { ok: false, reason: `identity line is not a single version: ${identity[0]}` };
+    }
+    const directory = from[0].slice(FROM_PREFIX.length).trim();
+    if (directory === '')
+        return { ok: false, reason: `no directory named: ${from[0]}` };
+    return { ok: true, version, directory };
+}

package/dist/src/browser.js

@@ -90,6 +90,30 @@ export function verificationUrlIsSafe(url, endpoint) {
     // operator who named their own endpoint owns their own topology.
     return true;
 }
+/**
+ * The console to send someone to, or null when we do not know one.
+ *
+ * Null is the answer for a self-hosted endpoint, and it is the whole reason
+ * this is a function rather than a constant anyone can print. The pin above
+ * exists because the official console's origin is a name we ship; a
+ * self-hosted deployment's is "not ours to know", and guessing `app.<their
+ * domain>` sends an operator to a service that may not be theirs — or may be
+ * someone else's.
+ *
+ * So a caller that wants to end a message with "and manage it at …" has to
+ * handle the null. That is deliberate: a message with no URL is worse than one
+ * with a wrong URL only until the wrong URL is followed.
+ */
+export function officialConsoleFor(endpoint) {
+    try {
+        return new URL(endpoint).origin === new URL(DEFAULT_ENDPOINT).origin
+            ? OFFICIAL_CONSOLE_ORIGIN
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function openUrl(url) {
     const opener = openerFor(url);
     return new Promise((resolve) => {

package/dist/src/commands/login.js

@@ -3,6 +3,8 @@ import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../bro
 import { credentialsForOrigin, isOrgAddress, originOf, writeCredential } from '../credentials.js';
 import { settleMachineName, validateMachineName } from '../machine-name.js';
 import { resolveScriptsDir } from '../config.js';
+import { packageInstall } from '../version.js';
+import { pathLookupCommand } from '../preflight.js';
 import { teamsBoundTo } from '../oss.js';
 // `login` — the device-authorization flow, from this machine's side.
 //
@@ -360,7 +362,43 @@ async function pollUntilDecided(grant, ctx) {
             // will look up again. Checked here so nothing durable happens first, and
             // checked again in `keyFor` so a future caller cannot route around this.
             if (!isOrgAddress(issued.org)) {
-                throw new Error('the server answered with an org address this build does not recognise — nothing was stored');
+                // WHAT THIS SENTENCE HAS TO GET RIGHT: whose fault it is, and what to
+                // do next. The previous wording — "the server answered with an org
+                // address this build does not recognise" — put the server first, and
+                // the person who hit it concluded the service was broken and stopped
+                // (#476). It was not broken: their machine was running a build from
+                // before `isOrgAddress` learned the second form.
+                //
+                // `credentials.ts` predicts this window in as many words: the server
+                // cutover "does not land until `npm view agmsg-cloud version` resolves
+                // to a build whose `isOrgAddress` accepts the new form". The window was
+                // designed for. What was never written was the sentence someone reads
+                // from inside it.
+                //
+                // The version AND the directory, from `packageInstall()`, which walks
+                // once and returns both. That pairing is the point here rather than a
+                // detail: the machine that hit this had TWO `agmsg-cloud` on PATH, and
+                // the one that answered `-v` was not the one that ran. A version alone
+                // would have been the same ambiguity in a new place. Reading the
+                // directory back against the shell's own lookup is what settles it.
+                //
+                // The lookup command comes from `preflight.ts`, which already had to
+                // decide it: `where` on Windows, `which` elsewhere. Printing `which`
+                // unconditionally would hand a Windows reader a broken command at the
+                // exact moment they have hit the PATH confusion this sentence exists to
+                // resolve. Raised in review, and taken from the module that RUNS it so
+                // the printed advice and the executed lookup cannot drift apart.
+                //
+                // No version number is named as the one to upgrade TO. Naming it needs
+                // a claim about which release first accepted this form, that claim
+                // decays every release, and a reader on that exact version is told to
+                // install what they already have. "Update, then run this again" is
+                // true whatever the answer is.
+                const { version, directory } = packageInstall();
+                throw new Error(`this build (${version}, from ${directory}) does not recognise the org address ` +
+                    'the server sent — nothing was stored. Update with `npm i -g agmsg-cloud` and run ' +
+                    'this command again. If the version above is not the one you expected, another ' +
+                    `\`agmsg-cloud\` is ahead of it on PATH — compare it with \`${pathLookupCommand()} agmsg-cloud\`.`);
             }
             return finish(issued, endpoint, post, out);
         }

package/dist/src/commands/sync.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { CourierClient } from '../api.js';
 import { originOf, readCredential } from '../credentials.js';
+import { officialConsoleFor } from '../browser.js';
 import { publicKeyOf } from '../oss.js';
 import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
@@ -217,8 +218,22 @@ export async function cmdSync(config, opts) {
     // authenticated, by machine.
     await fetch(config, { team: opts.team });
     // The last thing said, because "what now" is the question the screen leaves
-    // otherwise — and here the answer is that there is no next command. Saying
-    // so is the point: someone who has just run five steps and watched a code
+    // otherwise: someone who has just run five steps and watched a code
     // comparison has every reason to expect a sixth.
-    out(`\n"${opts.team}" is on this machine, unlocked and syncing. Nothing further to run.\n`);
+    //
+    // "Nothing further to run" was true and was read as "nothing further to do",
+    // and the walk stopped there (#479). The two are different sentences. There
+    // is no sixth COMMAND, and there is somewhere to go — the console is where a
+    // team is managed once it syncs, and the CLI was the only thing that knew
+    // that and did not say it.
+    //
+    // The console is named only for the official endpoint. `browser.ts` pins that
+    // origin because it is a name we ship, and refuses to guess a self-hosted
+    // one — "its layout is not ours to know". Printing `app.<their domain>` would
+    // send an operator to a service that need not be theirs, so a self-hosted
+    // deployment gets the true half of the sentence and no invented URL.
+    const console_ = officialConsoleFor(config.baseUrl);
+    out(`\n"${opts.team}" is on this machine, unlocked and syncing. No further command to run` +
+        (console_ ? ` — manage it at ${console_}` : '') +
+        '.\n');
 }

package/dist/src/preflight.js

@@ -97,11 +97,29 @@ function remoteSupportsConnect(scriptsDir) {
         return /\bconnect\b/.test(text);
     }
 }
+/**
+ * What a person types to ask their shell which executable would run.
+ *
+ * `where` on Windows, `which` everywhere else. Exported and taking its platform
+ * as an argument because this answer is now needed in two places and both of
+ * them are wrong if they disagree: this module RUNS it, and `login` PRINTS it
+ * for an operator to run themselves (#476). Telling a Windows reader to run
+ * `which` hands them a broken command at the exact moment they have hit the
+ * PATH confusion the message exists to resolve — raised in review.
+ *
+ * A parameter rather than a module-level constant so both branches are
+ * reachable from a test on one machine. A constant bound at import time can
+ * only ever be checked on the platform the suite happens to run on, which is
+ * the branch nobody needed to check.
+ */
+export function pathLookupCommand(on = platform) {
+    return on === 'win32' ? 'where' : 'which';
+}
 function onPath(command) {
     try {
         // `command -v` through the shell would re-interpret the name; execFile with
         // a fixed argv does not.
-        execFileSync(platform === 'win32' ? 'where' : 'which', [command], { stdio: 'ignore' });
+        execFileSync(pathLookupCommand(), [command], { stdio: 'ignore' });
         return true;
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -12,7 +12,8 @@
   },
   "files": [
     "dist/src",
-    "!dist/src/**/*.map"
+    "dist/scripts",
+    "!dist/**/*.map"
   ],
   "repository": {
     "type": "git",