agmsg-cloud 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/src/commands/approve.js

@@ -360,7 +360,21 @@ args, deps = {}) {
             done();
             // Closed, not refunded: §4.1 keeps a success counted in the window.
             closeAttempt(scope, requestId, 'succeeded', undefined, env);
-            out(`approved; registered device ${device_id}\n`);
+            // The LABEL, not the id.
+            //
+            // `device_id` is a UUID the approver cannot use: no subcommand of this
+            // CLI accepts one (derived from index.ts — approve, connect, fetch,
+            // login, logout, pull, recovery, request, sync, watch, whoami, and none
+            // take a device). So it fails all three tests for reaching a person: it
+            // decides nothing for them, it cannot help them repair anything, and the
+            // label they just compared eight digits against is what actually names
+            // the machine they approved (#275 — the operator gets the minimum, the
+            // rest belongs in a log).
+            //
+            // Not routed to a log instead, because this CLI has no log to route it
+            // to. Building one for a single value would be the wrong size; when a
+            // second diagnostic needs a home, that is the moment to give it one.
+            out(`approved; "${start.label}" can now read this team\n`);
         }
         finally {
             rmSync(scratch, { recursive: true, force: true });

package/dist/src/commands/login.js

@@ -63,6 +63,7 @@ export async function cmdLogin(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const now = opts.now ?? (() => Date.now());
+    const out = opts.out ?? ((text) => void process.stdout.write(text));
     const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
     // The flag, validated, before anything is asked. `settleMachineName` returns
     // it verbatim when it is given, so nothing below needs the prompt to know
@@ -73,7 +74,7 @@ export async function cmdLogin(opts) {
     // the thing it takes away is the moment the operator typed the destination —
     // so the destination is printed instead. Nobody should have to guess which
     // server their machine is about to be registered with.
-    process.stdout.write(`Connecting to ${new URL(endpoint).host}\n`);
+    out(`Connecting to ${new URL(endpoint).host}\n`);
     const post = async (path, body, bearer) => {
         try {
             return await fetchImpl(`${endpoint}${path}`, {
@@ -115,7 +116,7 @@ export async function cmdLogin(opts) {
     if (stored && (asked === undefined || stored.machineName === asked)) {
         const res = await post('/v1/device/activate', {}, stored.secret);
         if (res.ok) {
-            process.stdout.write(`Already signed in as machine "${stored.machineName}".\n`);
+            out(`Already signed in as machine "${stored.machineName}".\n`);
             return;
         }
         const code = await errorCode(res);
@@ -148,16 +149,32 @@ export async function cmdLogin(opts) {
         throw new Error(`could not start login: ${codeRes.status} ${code}`);
     }
     const grant = (await codeRes.json());
-    process.stdout.write(`\nOpen this page and check the code matches:\n\n`);
-    process.stdout.write(`  ${grant.verification_uri_complete}\n\n`);
-    process.stdout.write(`  code:    ${grant.user_code}\n`);
-    process.stdout.write(`  machine: ${machineName}\n\n`);
+    out(`\nOpen this page and check the code matches:\n\n`);
+    out(`  ${grant.verification_uri_complete}\n\n`);
+    out(`  code:    ${grant.user_code}\n`);
+    out(`  machine: ${machineName}\n\n`);
     // Armed, never awaited: an approval done from a phone, or from a URL typed by
     // hand, must still be noticed — so the poll below runs whether or not any key
     // is ever pressed. `disarm` is bound to every exit path, because a live stdin
     // listener would hold the process open after login has already finished.
     const opener = (opts.armOpener ?? armEnterToOpen)(grant.verification_uri_complete, endpoint);
-    process.stdout.write(`Waiting for approval — nothing is granted until you approve it.\n`);
+    // SAYS THAT THE BLOCKING IS THE DESIGN, and that the two lines above are
+    // already usable.
+    //
+    // An agent held the URL and the code for 42 seconds waiting for this command
+    // to return before relaying them — and it cannot return until someone
+    // approves, which nobody can do without seeing what it has already printed.
+    // The one step that needs a person was the step the person was locked out of
+    // (issue 279).
+    //
+    // The prompt handed to an agent carries four sentences about this. They are a
+    // description of behaviour this output can state itself, and prose in a
+    // prompt does not reach anyone who did not read that prompt — someone running
+    // the command by hand gets nothing.
+    out(`Waiting for approval — nothing is granted until you approve it.\n`);
+    out(`This command will not return until then. That is expected, not a failure:\n` +
+        `the page and the code above are ready to use now — open them, do not wait\n` +
+        `for this to finish.\n`);
     try {
         return await pollUntilDecided(grant, {
             post,
@@ -165,6 +182,7 @@ export async function cmdLogin(opts) {
             now,
             endpoint,
             armOpener: opts.armOpener ?? armEnterToOpen,
+            out,
         });
     }
     finally {
@@ -172,7 +190,7 @@ export async function cmdLogin(opts) {
     }
 }
 async function pollUntilDecided(grant, ctx) {
-    const { post, sleep, now, endpoint, armOpener } = ctx;
+    const { post, sleep, now, endpoint, armOpener, out } = ctx;
     // The poll is single-flight by construction: one loop, one request in flight.
     // A concurrent second poll on the same grant would revoke the credential the
     // first poll received.
@@ -198,7 +216,7 @@ async function pollUntilDecided(grant, ctx) {
             if (err instanceof Unreachable) {
                 // Said out loud rather than swallowed: an operator watching a long wait
                 // should see that contact was lost and regained, not silence.
-                process.stdout.write(`  (lost contact with the server, still waiting)\n`);
+                out(`  (lost contact with the server, still waiting)\n`);
                 continue;
             }
             throw err;
@@ -227,7 +245,7 @@ async function pollUntilDecided(grant, ctx) {
             if (!isOrgAddress(issued.org)) {
                 throw new Error('the server answered with an org address this build does not recognise — nothing was stored');
             }
-            return finish(issued, endpoint, post);
+            return finish(issued, endpoint, post, out);
         }
         const body = await errorBody(res);
         const code = body.code;
@@ -248,7 +266,9 @@ async function pollUntilDecided(grant, ctx) {
         throw new Error(explained ? `login stopped: ${explained}` : `login failed: ${res.status} ${code}`);
     }
 }
-async function finish(issued, endpoint, post) {
+async function finish(issued, endpoint, post, 
+/** The caller's sink, so every line this command prints goes one place. */
+out) {
     const secret = secretFromCapabilityUrl(issued.capability_url);
     // Durable write FIRST. If the process dies between here and activate, the
     // credential is on disk and the machine can be activated by running login
@@ -270,8 +290,8 @@ async function finish(issued, endpoint, post) {
         const code = await errorCode(res);
         throw new Error(`the credential was saved but could not be activated (${res.status} ${code}) — run login again`);
     }
-    process.stdout.write(`\nSigned in as machine "${issued.machine_name}".\n`);
-    process.stdout.write(`Its sync address is saved on this machine; no token to copy.\n`);
+    out(`\nSigned in as machine "${issued.machine_name}".\n`);
+    out(`Its sync address is saved on this machine; no token to copy.\n`);
 }
 async function errorCode(res) {
     return (await errorBody(res)).code;

package/dist/src/commands/sync.js

@@ -87,13 +87,33 @@ export async function cmdSync(config, opts) {
         // this machine may join, and a scary line about an unrelated call would
         // compete with the instructions below.
     }
-    out('  On a machine that already has the team, run:\n\n');
-    // The real command, with the team quoted for a shell. A placeholder makes
-    // the reader do the substitution, and the whole point of this arc is to stop
-    // carrying values by hand between machines — an instruction that ends in
-    // `<team>` hands the work straight back (raised in review).
-    out(`      agmsg-cloud approve ${shellArg(opts.team)}\n\n`);
-    out('  Compare the eight digits on both screens before answering there.\n\n');
+    // PROSE, NOT A BLOCK TO COPY — and what changes is what this command claims
+    // at this moment, not what it knows (#307).
+    //
+    // Nothing here has established that the team exists, and nothing can. The
+    // local store is what `connect` and `fetch` fail closed on, and a second
+    // machine does not have one — that absence is the premise of `sync`. The name
+    // does not decide it either: `agmsg_validate_team_name` bars `.` `..`, `/`,
+    // `\`, a leading `-` and control characters, so `<team>` is a VALID team name.
+    // The ceremony below is scoped to the org rather than the team (#148). The one
+    // remaining source, asking the service by name, answers nothing for every team
+    // today (#250).
+    //
+    // So this is not a fix, and the issue stays open. What it removes is a
+    // misreading: an indented, copyable command reads as "this is the step", and
+    // when the person had not filled the placeholder it put a literal `'<team>'`
+    // on the other machine, quoted and ready to paste. As a sentence it reads as
+    // what it is — something to ask for, on a machine that has the team, which is
+    // a condition the reader can check and this process cannot.
+    //
+    // The command still goes through `shellArg`: the name reaching it is arbitrary
+    // text either way.
+    out(`  Ask a machine that already has "${opts.team}" to run ` +
+        `\`agmsg-cloud approve ${shellArg(opts.team)}\`, and compare the eight digits on ` +
+        'both screens before answering there.\n\n');
+    out(`  This machine has not confirmed that "${opts.team}" is on the service — it has no\n` +
+        '  way to, before the steps below. If that machine has no such team, stop here and\n' +
+        '  connect it there first.\n\n');
     // Everything the ceremony guarantees happens inside here: the commitment is
     // pinned before anything opens, nothing is sealed or uploaded until the
     // digits match, and this side refuses a transcript it cannot verify.

package/dist/src/config.js

@@ -23,7 +23,48 @@ function fromEnv(env) {
 // `connect --preflight` is a dry run whose whole purpose is to be usable before
 // anything is set up, so it must not be refused for not being signed in.
 export function resolveScriptsDir(env = process.env) {
-    return env.AGMSG_SCRIPTS_DIR ?? join(homedir(), '.agents', 'skills', 'agmsg', 'scripts');
+    return scriptsDirChoice(env).dir;
+}
+/**
+ * The resolution, with its PROVENANCE — because the path alone does not answer
+ * the question an operator is actually asking (issue 282).
+ *
+ * An empty value is treated as unset. `??` passes the empty string through, so
+ * `export AGMSG_SCRIPTS_DIR=` resolved to `""` and every script path became a
+ * bare filename — measured, not supposed:
+ *
+ *     resolveScriptsDir({ AGMSG_SCRIPTS_DIR: '' })   ->  ""
+ *
+ * That is the shape someone reaches for when they are trying to undo the
+ * override, and it left them further from the default rather than back at it.
+ */
+export function scriptsDirChoice(env = process.env) {
+    const given = env.AGMSG_SCRIPTS_DIR;
+    if (given !== undefined && given !== '')
+        return { dir: given, from: 'env' };
+    return { dir: defaultScriptsDir(), from: 'default' };
+}
+/**
+ * The install used when `AGMSG_SCRIPTS_DIR` says nothing.
+ *
+ * Split out because it is also the answer to "what is the OTHER install"
+ * (issue 279), and a second copy of the path would be free to drift from the
+ * one the resolver uses — which is exactly the disagreement being reported.
+ *
+ * `home` is a PARAMETER, not `env.HOME`. The first version read
+ * `env.HOME ?? homedir()` and called it injectable-but-equivalent, on the
+ * grounds that `homedir()` reads `$HOME` on POSIX. That does not close: this
+ * CLI targets Windows, where a POSIX-compatible shell sets `HOME` to something
+ * like `/c/Users/x` while `homedir()` returns the native path — so the
+ * "equivalent" version would have moved the default install location for every
+ * Git Bash user (raised in review).
+ *
+ * Production never passes it. A seam a caller must opt into cannot change what
+ * anyone runs; an environment variable that production already has is not a
+ * seam at all.
+ */
+export function defaultScriptsDir(home = homedir()) {
+    return join(home, '.agents', 'skills', 'agmsg', 'scripts');
 }
 /**
  * THE credential decision. Every caller that needs to know whether this machine

package/dist/src/preflight.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { hasCredential } from './config.js';
+import { defaultScriptsDir, hasCredential, scriptsDirChoice } from './config.js';
 import { join } from 'node:path';
 import { platform } from 'node:process';
 // What `connect` needs before it starts, checked all at once.
@@ -151,7 +151,17 @@ function toolsFor(scripts) {
         python3: scripts.includes('remote.sh'),
     };
 }
-export function preflight(scriptsDir, needs, env = process.env) {
+export function preflight(scriptsDir, needs, env = process.env, 
+/**
+ * The home directory the default install would be under.
+ *
+ * Only ever passed by a check that needs to put a second install somewhere it
+ * owns. It is a parameter rather than `env.HOME` because this CLI runs on
+ * Windows too, where a POSIX-compatible shell sets `HOME` to a path
+ * `homedir()` does not return — reading it would have moved the default
+ * install for every Git Bash user in exchange for a testable line.
+ */
+home) {
     const { command, scripts } = needs;
     const requireConnect = needs.requireConnect ?? false;
     const requirements = [];
@@ -229,8 +239,43 @@ export function preflight(scriptsDir, needs, env = process.env) {
         command,
         scriptsDir,
         agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
+        scriptsDirFrom: provenance(env, home),
+        otherInstalls: otherInstalls(scriptsDir, env, home),
     };
 }
+/**
+ * The install that exists at the location this command is NOT using.
+ *
+ * Only ever one, and only when `AGMSG_SCRIPTS_DIR` points somewhere other than
+ * the default: those are the two places `resolveScriptsDir` can name, so they
+ * are the two places worth reporting. `version.sh` is the marker rather than
+ * the directory itself — an empty `~/.agents/skills/agmsg/scripts` is not a
+ * second install, and calling it one would send someone to look at nothing.
+ */
+/**
+ * Which of the three states the resolution is in.
+ *
+ * Three, not two: the variable can be set AND point at the default, which is
+ * what someone has on the way to undoing an override. Collapsing it into "env"
+ * makes the output say "not the default location" about the default location.
+ */
+function provenance(env, home) {
+    const choice = scriptsDirChoice(env);
+    if (choice.from === 'default')
+        return 'default';
+    return choice.dir === defaultScriptsDir(home) ? 'env-at-default' : 'env';
+}
+function otherInstalls(scriptsDir, env, home) {
+    // Through the resolver's own accessor, so the two can never disagree about
+    // where "the default" is — a disagreement here would report the wrong
+    // directory as the one not in use.
+    const fallback = defaultScriptsDir(home);
+    if (scriptsDir === fallback)
+        return [];
+    if (!env.AGMSG_SCRIPTS_DIR)
+        return [];
+    return existsSync(join(fallback, 'version.sh')) ? [fallback] : [];
+}
 // The refusal in front of every command that shells out: one place decides how
 // a missing prerequisite reads, so it reads the same whichever command found
 // it.
@@ -262,7 +307,39 @@ export function formatPreflight(result) {
     // decoration on a label; it is the answer to "which one did you look at".
     lines.push('');
     lines.push(`  scripts directory:       ${result.scriptsDir}`);
-    lines.push(`  set AGMSG_SCRIPTS_DIR to check a different install.`);
+    // WHAT PUT IT THERE, when something did.
+    //
+    // The hint below is advice to redirect the install. Printed while
+    // AGMSG_SCRIPTS_DIR is already set, it invites the reader to do the thing
+    // that is currently confusing them — "you could redirect this" when the truth
+    // is "this is redirected". So the two are alternatives, not a pair.
+    //
+    // Nothing extra when the default is in force: "this is the default" on every
+    // ordinary run is noise, and the sentence is only missing when something
+    // non-default is deciding.
+    if (result.scriptsDirFrom === 'env') {
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, not the default location.`);
+    }
+    else if (result.scriptsDirFrom === 'env-at-default') {
+        // The variable is set AND points at the default. Saying "not the default
+        // location" here would be false, and it is the state someone reaches while
+        // trying to undo an override — the one moment the sentence has to be exact.
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, which points at the default location.`);
+    }
+    else {
+        lines.push(`  set AGMSG_SCRIPTS_DIR to check a different install.`);
+    }
+    // NAMES THE OTHER ONE, and says which of the two is in force.
+    //
+    // Without this the reader has to decide, and an agent that finds two installs
+    // stops and asks — the incident four lines of the handed-over prompt exist to
+    // prevent (issue 279). The answer is not a preference to be settled; it is
+    // already settled by the resolver, and this is it being said out loud.
+    for (const other of result.otherInstalls) {
+        lines.push('');
+        lines.push(`  another install is here:  ${other}`);
+        lines.push(`  it is NOT the one in use — AGMSG_SCRIPTS_DIR decides, and it points above.`);
+    }
     if (result.agmsgVersion !== null) {
         // Named as what it is. Calling it "agmsg 1.1.11" would invite the reader to
         // compare it with a release number, which is the thing it cannot be
@@ -274,6 +351,15 @@ export function formatPreflight(result) {
     if (missing.length === 0) {
         lines.push('');
         lines.push(`Everything ${result.command} needs is here.`);
+        // SAYS THAT THIS IS THE CHECK.
+        //
+        // An agent told "make sure the prerequisites are met" checks them again
+        // unless something says not to — it has no way to know this output was the
+        // check rather than a summary of one. The prompt carries a sentence for
+        // exactly that ("do not check for tools yourself"), which is a property
+        // this output should have rather than a warning the reader must be given
+        // separately (issue 279).
+        lines.push(`This was the check. Nothing else needs testing before you run it.`);
         return `${lines.join('\n')}\n`;
     }
     for (const r of missing) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.7",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,7 +33,8 @@
     "pretypecheck": "pnpm run build:deps",
     "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"
+    "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"
   },
   "dependencies": {
     "@agmsg-cloud/sas-core": "workspace:*",