agmsg-cloud 0.1.0-rc.7 → 0.1.0

package/dist/src/vault-inventory.js

@@ -0,0 +1,118 @@
+/**
+ * Join the container against what the server calls each team.
+ *
+ * BOTH SETS COME OUT OF ONE RESPONSE. `listTeams` answers with the ids it
+ * returned and which of those carry a null name, so "in this org without a
+ * name" and "not in this org" are derived from the same read rather than from
+ * two lookups that could disagree. Deriving them separately is how two
+ * existence checks get mistaken for a relation.
+ */
+export function inventoryOf(container, names) {
+    const total = container.teams.length;
+    if (!names.asked)
+        return { namesKnown: false, total, entries: [...container.teams] };
+    const named = [];
+    const unnamed = [];
+    const unknown = [];
+    const ambiguous = [];
+    // The ids the org answered with — the set membership test for `unknown`.
+    const returned = new Set(names.teams.map((t) => t.teamId));
+    const byId = new Map(names.teams.map((t) => [t.teamId, t.teamName]));
+    // How many entries each id accounts for. Counted over the CONTAINER, not the
+    // response: the response cannot hold the same id twice, which is the whole
+    // reason a name from it cannot resolve a repeat here.
+    const perId = new Map();
+    for (const entry of container.teams) {
+        perId.set(entry.team_id, (perId.get(entry.team_id) ?? 0) + 1);
+    }
+    for (const entry of container.teams) {
+        // Before the name is consulted at all. An id the vault holds twice has no
+        // name that means one thing, so asking for one and then discarding it would
+        // be the same mistake with an extra step.
+        if ((perId.get(entry.team_id) ?? 0) > 1) {
+            ambiguous.push(entry);
+            continue;
+        }
+        if (!returned.has(entry.team_id)) {
+            unknown.push(entry);
+            continue;
+        }
+        const team = byId.get(entry.team_id);
+        // An empty string is not a name: it fails `agmsg_validate_team_name` ("must
+        // not be empty") and would reach the OSS side as a missing argument. It is
+        // the null case wearing a different type, so it lands in the same bucket.
+        if (team !== null && team !== undefined && team !== '')
+            named.push({ entry, team });
+        else
+            unnamed.push(entry);
+    }
+    // A NAME can repeat too, and a repeat is just as unplaceable. Team names are
+    // not unique on the server — `resolveTeamByName` refuses a name that matches
+    // more than one team for exactly this reason — so two entries with different
+    // ids can both come back called `alpha`. Only one local team can carry that
+    // name, and nothing in the response chooses between them: placing the first
+    // and letting the second collide is not a resolution, it is a race decided by
+    // the order the vault happens to store them in.
+    const perName = new Map();
+    for (const n of named)
+        perName.set(n.team, (perName.get(n.team) ?? 0) + 1);
+    const uniquelyNamed = [];
+    for (const n of named) {
+        if ((perName.get(n.team) ?? 0) > 1)
+            ambiguous.push(n.entry);
+        else
+            uniquelyNamed.push(n);
+    }
+    return { namesKnown: true, total, named: uniquelyNamed, unnamed, unknown, ambiguous };
+}
+/**
+ * The report, as lines.
+ *
+ * Built as data rather than written to stdout so a test can read it without a
+ * process, and so the one rule that matters is checkable: **the count of what
+ * could not be done is always printed when it is not zero**, with the ids.
+ */
+export function inventoryLines(inv, revision) {
+    const lines = [`opened the account vault, revision ${revision}`];
+    if (inv.total === 0) {
+        lines.push('it holds no team backups yet — `agmsg-cloud recovery setup` creates them');
+        return lines;
+    }
+    lines.push(`${inv.total} team backup(s) in it`);
+    if (!inv.namesKnown) {
+        // Every id, and no verdict about any of them. The entries are here; what
+        // failed is the question that would say which are placeable, and answering
+        // it anyway is how a network error becomes "your backups are unreachable".
+        lines.push('the server could not be asked for names, so none of these can be sorted yet:');
+        for (const entry of inv.entries)
+            lines.push(`  ${entry.team_id}`);
+        return lines;
+    }
+    for (const { team, entry } of inv.named) {
+        lines.push(`  ${team}  (${entry.team_id})`);
+    }
+    // Never folded together, and never folded into the count above. "4 of 6" that
+    // does not name the other two is the shape of a partial success printed as a
+    // success — and these two lists have different ways out, so a reader who is
+    // shown one line takes the worse of the two readings for all of them.
+    if (inv.unnamed.length > 0) {
+        lines.push(`${inv.unnamed.length} of ${inv.total} are in this org but the server has no name recorded` +
+            ` for them. If you know the name, it can be placed:`);
+        for (const entry of inv.unnamed)
+            lines.push(`  ${entry.team_id}`);
+    }
+    if (inv.ambiguous.length > 0) {
+        lines.push(`${inv.ambiguous.length} of ${inv.total} share a team id with another backup on a` +
+            ` different server, and the server's team list cannot say which name belongs to which:`);
+        for (const entry of inv.ambiguous) {
+            lines.push(`  ${entry.team_id}  on ${entry.server_instance_id}`);
+        }
+    }
+    if (inv.unknown.length > 0) {
+        lines.push(`${inv.unknown.length} of ${inv.total} did not appear in this org's teams at all —` +
+            ` this machine's credential cannot reach them:`);
+        for (const entry of inv.unknown)
+            lines.push(`  ${entry.team_id}`);
+    }
+    return lines;
+}

package/dist/src/vault-placement.js

@@ -0,0 +1,94 @@
+/**
+ * What happened to each entry the placement loop tried to place, and how that
+ * is reported.
+ *
+ * Kept as data and rendered separately for the same reason `vault-inventory.ts`
+ * is: the rule worth checking is about the REPORT, not about the spawning, and
+ * a test should be able to read the report without a process.
+ *
+ * The rule, from #342a and unchanged: **a partial result is never printed as a
+ * success.** Anything not placed is listed, with its id.
+ */
+/**
+ * @param inVault every entry the vault holds, NOT just the ones that were
+ * attempted. `placed 1 of 1` printed under `2 team backup(s) in it` is a
+ * partial result reading as a complete one — the denominator has to be the
+ * thing the person came here to get back.
+ */
+export function placementLines(results, inVault) {
+    if (results.length === 0)
+        return [];
+    const lines = [];
+    const placed = results.filter((r) => r.kind === 'placed');
+    const already = results.filter((r) => r.kind === 'already');
+    const done = placed.length + already.length;
+    lines.push(`placed ${done} of ${inVault} team backup(s) in the vault`);
+    if (results.length < inVault) {
+        // Said here as well as in the inventory above, because this line is the one
+        // a person reads as the outcome, and a denominator it cannot account for
+        // invites the reading that the rest simply worked.
+        lines.push(`  (${inVault - results.length} of those could not be attempted — see the list above)`);
+    }
+    for (const r of placed)
+        lines.push(`  ${r.team}  (${r.teamId})`);
+    for (const r of already) {
+        lines.push(`  ${r.team}  (${r.teamId})  — was already here, its key was re-imported`);
+    }
+    const stuck = results.filter((r) => r.kind === 'name-held' ||
+        r.kind === 'refused' ||
+        r.kind === 'locked' ||
+        r.kind === 'disconnected' ||
+        r.kind === 'wrong-instance' ||
+        r.kind === 'server-unknown');
+    if (stuck.length === 0)
+        return lines;
+    lines.push(`${stuck.length} could not be placed:`);
+    for (const r of stuck) {
+        if (r.kind === 'disconnected') {
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            lines.push('    already on this machine, but its connection to the server was ended,');
+            lines.push('    so its key cannot be imported. Reconnect it, then run this again.');
+        }
+        else if (r.kind === 'server-unknown') {
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            lines.push('    which server this machine reaches could not be established, so nothing');
+            lines.push('    was pulled — placing it without knowing would risk taking the wrong one:');
+            lines.push(`    ${r.why}`);
+        }
+        else if (r.kind === 'wrong-instance') {
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            lines.push('    this backup is from a different server than the one this machine');
+            lines.push('    reaches, so nothing was pulled and nothing was written:');
+            lines.push(`      the backup's server:  ${r.wanted}`);
+            lines.push(`      the server reached:   ${r.got}`);
+            lines.push('    no local team was created, so the name is still free for the right one.');
+        }
+        else if (r.kind === 'name-held') {
+            // The facts, and no route. Both ids so the two teams can be told apart,
+            // and "nothing was changed" said outright: the worst reading of a bare
+            // refusal is that something was half-done.
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            lines.push(`    a different team on this machine already holds the name '${r.team}'`);
+            // BOTH halves of both identities. The two can share a team id and differ
+            // only by server, and a report printing one uuid twice says "different
+            // team" while showing nothing that differs.
+            lines.push(`      the local one:  ${r.localTeamId}  on ${r.localInstance}`);
+            lines.push(`      the backup:     ${r.teamId}  on ${r.instance}`);
+            lines.push('    nothing local was changed. Placing it needs that name to be free.');
+        }
+        else if (r.kind === 'locked') {
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            lines.push('    it is on this machine but still locked — its key did not import:');
+            for (const said of r.said.split('\n'))
+                if (said.trim() !== '')
+                    lines.push(`    ${said}`);
+        }
+        else {
+            lines.push(`  ${r.team}  (${r.teamId})`);
+            for (const said of r.said.split('\n'))
+                if (said.trim() !== '')
+                    lines.push(`    ${said}`);
+        }
+    }
+    return lines;
+}

package/dist/src/version.js

@@ -5,27 +5,23 @@ import { fileURLToPath } from 'node:url';
 // version — an identity, and the only thing that tells one package.json from
 // another while walking up a tree that may contain several.
 const PACKAGE_NAME = 'agmsg-cloud';
-// The version this build was published as.
-//
-// Read from the package's own `package.json` at runtime rather than baked into
-// a constant, because a constant is a second place to update and the one that
-// gets forgotten: a build that says the wrong version is worse than one that
-// says none, since the answer looks authoritative either way. npm always
-// includes package.json in a tarball, so it is there for a published install.
-//
-// Found by walking UP from this module rather than by a fixed relative path,
-// because the depth differs between the two places this file runs from:
-// `src/version.ts` sits one level under the package root, `dist/src/version.js`
-// sits two. A path correct in one is wrong in the other, and the one that would
-// be wrong is the published one.
-//
-// The walk answers only from a manifest that NAMES this package. Without that
-// check the first non-empty version above the module wins, and the installs
-// most likely to hit it are the broken ones — a package.json missing or
-// stripped of its version is exactly when a monorepo root, an npx cache entry,
-// or a parent workspace supplies its own. Reporting a stranger's version is the
-// failure this command exists to prevent, wearing the shape of a success.
-export function packageVersion(moduleUrl = import.meta.url) {
+/**
+ * The install this process is running out of: its version AND where it is.
+ *
+ * Both come from ONE walk, and that is the point rather than a convenience.
+ * `which agmsg-cloud` answers from PATH and a manifest answers from the module
+ * graph; when two package managers have both installed this tool, those are two
+ * different questions with two different answers, and pairing them would report
+ * a directory that need not be where the version came from. The directory
+ * returned here is the one whose `package.json` supplied the version, so the
+ * two cannot disagree.
+ *
+ * Node resolves a module's realpath before loading it, so a bin symlink — the
+ * usual shape of a global install — has already been followed by the time
+ * `import.meta.url` exists. What comes back is the store directory, which is
+ * the part that tells a pnpm global install from an npm one.
+ */
+export function packageInstall(moduleUrl = import.meta.url) {
     let dir = dirname(fileURLToPath(moduleUrl));
     const { root } = parse(dir);
     for (;;) {
@@ -41,7 +37,7 @@ export function packageVersion(moduleUrl = import.meta.url) {
         if (manifest?.name === PACKAGE_NAME) {
             const version = manifest.version;
             if (typeof version === 'string' && version !== '')
-                return version;
+                return { version, directory: dir };
             // Fail closed. This IS the package and it cannot say what it is; climbing
             // past would hand the question to whatever sits above, which is how a
             // broken install comes to announce a stranger's version.
@@ -55,3 +51,6 @@ export function packageVersion(moduleUrl = import.meta.url) {
     // guessed — see the note above.
     throw new Error(`cannot determine the installed version: no ${PACKAGE_NAME} package.json above this module`);
 }
+export function packageVersion(moduleUrl = import.meta.url) {
+    return packageInstall(moduleUrl).version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -34,7 +34,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsx scripts/check-printed-commands.ts && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
     "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
-    "verify:published": "tsx scripts/verify-published.ts"
+    "verify:published": "tsx scripts/verify-published.ts",
+    "verify:shown-install": "tsx scripts/verify-shown-install.ts"
   },
   "dependencies": {
     "@agmsg-cloud/sas-core": "workspace:*",