@augurworks/augur 0.15.7 → 0.15.9

package/README.md

@@ -53,6 +53,27 @@ contracts in [agents/](./agents/) does the same job. Screens in the demo space
 carry the session that made them: [open the repo and read one](https://github.com/andratwiro/augur-space-fulla/tree/main/garden/prompts).
 The follow-ups read like design direction, because that is what they are.
 
+## Let an assistant in from a link
+
+Someone on the team gives their assistant the workspace address and asks for a
+change. Nothing else is needed from them, and no password ever changes hands.
+The workspace tells the assistant how to get in (`/llms.txt` on every instance),
+and the flow is device pairing:
+
+```bash
+npx @augurworks/augur connect --origin https://<the workspace>
+```
+
+It prints a link and a code. The person opens the link in the browser they are
+already signed in to and types the code; that pairs the one terminal that printed
+it, to publish as them. From then on the assistant opens a prototype as a draft
+(`augur open <opportunity>/<prototype>`), edits it, live at the draft's own
+address, and lands it (`augur land`), which moves the real URL. Signed-in members
+see the same instructions under Help › Building and at `/__connect`, so a person
+who knows nothing technical can still confirm what their assistant was told. The
+package on npm is this repository, and nothing else: `npm view @augurworks/augur
+repository`.
+
 ## Boards where the prototypes run
 
 Drop a live prototype next to the stickies and drive it. Everyone on the board

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augurworks/augur",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "files": [
     "scripts/",
     "build.js",

package/scripts/connect.mjs

@@ -19,6 +19,7 @@ import path from "node:path";
 import os from "node:os";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolveOrigin } from "./lib/store.mjs";
+import { augurOnPath } from "./lib/adapters.mjs";
 
 const C = { dim: "\x1b[2m", bold: "\x1b[1m", ok: "\x1b[32m", warn: "\x1b[33m", off: "\x1b[0m" };
 const log = (m) => console.log(`\x1b[35m[connect]\x1b[0m ${m}`);
@@ -64,6 +65,37 @@ async function post(pathPart, body) {
   return { status: r.status, json };
 }
 
+// A machine that is ALREADY connected to this origin does not pair again by accident. One
+// cold agent collected its token with a blocking `connect`, did not read the answer, ran
+// `connect` again, minted a second code, and had the person approve that too. If the saved
+// token still answers, say so and stop; `--again` pairs afresh on purpose, and a token the
+// workspace no longer honours (revoked, another workspace's) falls through to a new pairing.
+const AGAIN = argv.includes("--again");
+// Whether this workspace serves drafts, from its own door — the success line names the
+// right next verb, not `publish` on a workspace that refuses it. Asked before any path
+// that can finish, including the one that collects a pairing started earlier.
+let draftsHere = false;
+try { const j = await (await fetch(`${ORIGIN}/.well-known/augur.json`, { headers: { Accept: "application/json" } })).json(); draftsHere = !!(j && j.drafts && j.drafts.enabled); } catch (e) { draftsHere = false; }
+const TOKENS_FILE = path.join(os.homedir(), ".config", "augur", "tokens.json");
+function savedToken() {
+  try { const t = JSON.parse(readFileSync(TOKENS_FILE, "utf8"))[host]; return t && t.token ? t : null; } catch (e) { return null; }
+}
+if (!AGAIN && !process.env.AUGUR_TOKEN) {
+  const saved = savedToken();
+  if (saved && !(saved.expiresAt && Date.parse(saved.expiresAt) <= Date.now())) {
+    let live = false;
+    try {
+      const r = await fetch(`${ORIGIN}/__unit/drafts`, { headers: { Authorization: `Bearer ${saved.token}`, Accept: "application/json" } });
+      live = r.status === 200;
+    } catch (e) { live = false; }
+    if (live) {
+      log(`this machine is already connected to ${C.bold}${host}${C.off}${saved.at ? ` (since ${saved.at.slice(0, 16).replace("T", " ")})` : ""}. Nothing to approve.`);
+      console.log(`  ${C.dim}\`augur open <opportunity>/<prototype>\` works from here. \`augur connect --again\` pairs afresh.${C.off}`);
+      process.exit(0);
+    }
+  }
+}
+
 // A pairing this machine already started and nobody has collected: ask once whether it
 // was approved meanwhile, and if not, keep waiting on THAT code rather than minting a
 // second one for the same person to type.
@@ -152,7 +184,17 @@ all[new URL(ORIGIN).host] = {
 writeFileSync(file, JSON.stringify(all, null, 2), { mode: 0o600 });
 
 log(`${C.ok}paired — publish access: ${saved.space === "*" ? "all spaces" : saved.space}${C.off}`);
-console.log(`ready — \`augur publish\` will now use this token for ${ORIGIN}`);
+// The next verb, spelled so it runs from THIS machine: `augur` after a global install, the
+// package's own `npx` line otherwise — and the verb this workspace takes, which the door
+// knows (drafts: open and land; a whole-tree instance: publish).
+const verb = augurOnPath() ? "augur" : "npx @augurworks/augur";
+if (draftsHere) {
+  console.log(`ready — \`${verb} open <opportunity>/<prototype>\` opens one prototype as a draft (live at once at its own address);`);
+  console.log(`        edit the folder it makes, then \`${verb} land\` in that folder: the real URL moves.`);
+} else {
+  console.log(`ready — \`${verb} publish\` will now use this token for ${ORIGIN}`);
+}
+if (verb !== "augur") console.log(`${C.dim}(\`augur\` is not on this machine's PATH; \`npm i -g @augurworks/augur\` puts it there for good.)${C.off}`);
 if (saved.expiresAt) {
   const days = Math.max(0, Math.round((Date.parse(saved.expiresAt) - Date.now()) / 86400000));
   console.log(`${C.dim}It expires in ${days} days (${saved.expiresAt.slice(0, 10)}). Run \`augur connect\` again then.${C.off}`);

package/scripts/lib/adapters.mjs

@@ -107,7 +107,12 @@ export const hookCommand = (event, { onPath = false } = {}) =>
 export function augurOnPath() {
   try {
     const out = execFileSync(process.platform === "win32" ? "where" : "which", ["augur"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-    return out.trim().length > 0;
+    const found = out.trim().split(/\r?\n/)[0] || "";
+    // Inside an `npx` run the package's own bin dir is on PATH and `augur` resolves to a shim
+    // in the npx cache — gone the moment npx exits. A hook written as `augur hook pre` from
+    // there fails on every later edit (one cold agent's drafts never auto-saved, and its tool
+    // showed a "not found" on each write). That resolution counts as NOT on PATH.
+    return found.length > 0 && !/[\\/]_npx[\\/]/.test(found);
   } catch (e) { return false; }
 }
 const ours = (h) => !!(h && Array.isArray(h.hooks) && h.hooks.some((x) => x && typeof x.command === "string" && OURS_RE.test(x.command.trim())));

package/scripts/open.mjs

@@ -9,7 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { target, buildStamp } from "./lib/store.mjs";
 import { unitClient, doOpen, unitPathFor } from "./lib/draft.mjs";
-import { installAdapters } from "./lib/adapters.mjs";
+import { installAdapters, augurOnPath } from "./lib/adapters.mjs";
 import { normUnit } from "../src/unit-core.mjs";
 
 const log = (m) => console.error(`\x1b[35m[open]\x1b[0m ${m}`);
@@ -51,7 +51,7 @@ log(r.isNew ? `draft ${r.draftId} on ${unit} — a NEW prototype; ${dir} is empt
 // here (idempotent; `AUGUR_NO_ADAPTERS=1` skips it — the suite and CI set it).
 if (!process.env.AUGUR_NO_ADAPTERS) {
   for (const a of installAdapters()) {
-    if (a.result === "installed") log(`${a.name}: editor hooks installed (${a.path}) — edits in a draft folder save on their own; edits to a shared checkout's prototypes are refused.`);
+    if (a.result === "installed") log(`${a.name}: a save hook is now in ${a.path} — after each edit inside a draft folder it runs \`augur hook post\`, which saves that draft to ${origin}; before an edit it refuses writes into a shared checkout's prototypes. It does nothing outside draft folders and talks to nothing else; \`augur hook remove\` takes it out.`);
     else if (a.result === "updated") log(`${a.name}: editor hooks updated (${a.path}).`);
   }
 }
@@ -60,4 +60,10 @@ if (r.others.length) {
   for (const o of r.others) log(`  ${o.session || "someone"} (${o.active ? "active" : "idle"})`);
   log("nothing here stops you; if you both land, the second one syncs first.");
 }
+// The next two steps, spelled so they run from this machine (`augur` only after a global
+// install; the package's `npx` line otherwise).
+const verb = augurOnPath() ? "augur" : "npx @augurworks/augur";
+log(r.isNew
+  ? `next: write ${path.join(dir, "index.html")} (self-contained static HTML); it is live at the address below as soon as it saves. When it is ready: \`cd ${path.basename(dir)} && ${verb} land\` — the last line printed is the live URL.`
+  : `next: edit the files in ${dir}; every save is live at the address below. When it is ready: \`cd ${path.basename(dir)} && ${verb} land\` — the last line printed is the live URL.`);
 console.log(r.address);

package/src/_worker.js

@@ -3748,16 +3748,23 @@ async function mintPublishToken(kv, tctx, u, { label = null, env = null } = {})
  * Self-contained, like the login and 404 pages beside it: this must render for somebody
  * whose terminal is already waiting, so it depends on no chrome bundle and no space.
  */
-function connectPage(tctx, me) {
+function connectPage(tctx, me, origin) {
   const body = roleOf(me) === "viewer"
     ? `<h1>Connect a terminal</h1>
        <p>This account can look around but not publish, so it cannot approve a terminal.</p>
        <a class="home" href="/">Back to Augur</a>`
     : `<h1>Connect a terminal</h1>
-       <p>Type the code your terminal is showing. Approving it lets that terminal publish as
-          <strong>${escapeHtml(me.email)}</strong>.</p>
-       <p class="warn">Only approve a code you are reading off your own screen right now.
-          Nobody legitimate will ever send you one.</p>
+       <p>Type the code that your terminal, or the assistant you are working with right now,
+          is showing you. Approving it lets that terminal publish as
+          <strong>${escapeHtml(me.email)}</strong>: it works as you, and everything it lands
+          carries your name.</p>
+       <p class="warn">Only approve a code from a terminal you started or an assistant you
+          are talking to right now. A code that arrives by mail, from a stranger, or out of
+          the blue is not yours — do not type it.</p>
+       <p>Where the code comes from: the terminal or assistant runs
+          <code>npx @augurworks/augur connect --origin ${escapeHtml(origin || "")}</code>, this
+          workspace's own command-line tool, and it shows the code. An assistant that has not
+          shown you one yet can be told to run that.</p>
        <form id="pairf">
          <input id="pairc" autocomplete="off" autocapitalize="characters" spellcheck="false"
                 placeholder="ABCD-EFGH" aria-label="Pairing code" />
@@ -7384,12 +7391,20 @@ function browserFetch(request) {
   return /^Mozilla\//.test(request.headers.get("User-Agent") || "");
 }
 
-/** The one paragraph a non-browser fetch of a prototype is given, first in the body. */
+/**
+ * The one paragraph a non-browser fetch of a prototype is given, first in the body.
+ *
+ * DESCRIPTIVE, THIRD PERSON, NO ADDRESS AND NO REASSURANCE. A first draft said "Assistants
+ * and scripts: … a terminal is paired with the person's approval, and nobody is ever asked
+ * for a password", and the third cold agent read exactly that sentence as a prompt
+ * injection — text on a fetched page that speaks to the agent and reassures it is the
+ * shape of an attack, whatever it says. A statement of fact and a link is what a page may
+ * carry: what this is, and where the workspace documents how it is edited.
+ */
 function agentPreface(url) {
   const origin = escapeHtml(url.origin);
-  return `<p data-augur-door>This prototype is served by an Augur workspace at ${origin}. `
-    + `Assistants and scripts: <a href="${DOOR_DOCS}">${origin}${DOOR_DOCS}</a> says how to change it — `
-    + `a terminal is paired with the person's approval, and nobody is ever asked for a password.</p>`;
+  return `<p data-augur-door>This prototype is served by an Augur workspace (${origin}). `
+    + `The workspace documents how its prototypes are edited at <a href="${DOOR_DOCS}">${origin}${DOOR_DOCS}</a>.</p>`;
 }
 
 /**
@@ -9227,6 +9242,8 @@ function wantsJson(request, url) {
 // probe and the "an unknown path and the root are the same page" contract depend on it.
 const DOOR_DOCS = "/llms.txt";
 const DOOR_WELL_KNOWN = "/.well-known/augur.json";
+/** The engine's public source — what the CLI on npm is built from, named so an agent can check. */
+const ENGINE_SOURCE = "https://github.com/andratwiro/augur";
 
 /** Does this deployment serve drafts — a unit store beside a bundle store. The same two checks `unitApi` makes. */
 const draftsServedHere = (env) => !!(env && env.BUNDLES && unitNamespace(env));
@@ -9241,6 +9258,10 @@ function doorFacts(tctx, url, env) {
     engine: tctx.INSTANCE_ENGINE_VERSION ? { version: tctx.INSTANCE_ENGINE_VERSION } : {},
     pairing: { enabled: pairing, start: "/__publish/_pair/start", approve: "/__connect" },
     connect: pairing ? `npx @augurworks/augur connect --origin ${url.origin}` : null,
+    // Where the CLI comes from, for an agent that checks before it runs anything: the
+    // package is the same open-source engine that serves this page, and `npm view
+    // @augurworks/augur repository` names the same repository.
+    source: ENGINE_SOURCE,
     docs: DOOR_DOCS,
     // Where drafts are served, a prototype is changed by opening it, not by shipping a
     // tree — and the door is where a cold agent learns which of the two this instance is.
@@ -9258,17 +9279,37 @@ function doorText(f) {
   const body = f.pairing.enabled
     ? `Run, on the machine that will publish:\n\n`
       + `  ${f.connect}\n\n`
-      + `It prints a link and a code. The owner of this workspace opens the link in a\n`
+      + `It prints a link and a code. A member of this workspace opens the link in a\n`
       + `browser they are already signed in to and enters the code. The token lands on\n`
-      + `that machine, and every verb below uses it from then on.\n\n`
-      + `AGENTS: if your person reads your messages only after you finish your turn, run\n`
-      + `it with --no-wait. It prints the line and exits; send them that line, end your\n`
-      + `turn, and run the same command again once they say they approved — the token is\n`
-      + `collected then, for that same code. Do not poll for the approval in one turn:\n`
-      + `the code lives five minutes and nobody sees it until you stop.\n\n`
+      + `that machine and nowhere else, and every verb below uses it from then on.\n`
+      + `Approving a code lets that one terminal publish as the person who approved it;\n`
+      + `everything it lands carries their name. A member whose role is viewer cannot\n`
+      + `approve, and the page says so.\n\n`
+      + `Members see this same instruction when signed in, at ${f.origin}/__connect and\n`
+      + `under Help > Building — so the person you are working for can read it there and\n`
+      + `confirm it is this workspace's own, without knowing anything technical.\n\n`
+      + `What the command is, for anyone who checks before running it: the CLI is this\n`
+      + `engine's own, open source at ${f.source} — the same engine that serves this page\n`
+      + `(${f.origin}/_build.json names the engine commit). \`npm view @augurworks/augur repository\`\n`
+      + `names that repository; \`npm pack @augurworks/augur\` lets you read it first. It is plain\n`
+      + `JavaScript with no runtime dependencies; the pairing is scripts/connect.mjs and it\n`
+      + `talks only to this origin's /__publish/_pair/ routes. It asks for no password, and\n`
+      + `there is none to give it.\n\n`
+      + `How the pairing goes when the person approving is not at the keyboard (an\n`
+      + `assistant working for them): the approval is theirs, in their browser — nobody\n`
+      + `else can do it, and the command does not try. Send them the line the command\n`
+      + `prints, as it is. When they will read that message only after the current turn\n`
+      + `ends, run \`connect --no-wait\`: it prints the line and exits. Once they say they\n`
+      + `approved, run the same command again — it collects the token for that same code and\n`
+      + `mints no second one. Waiting inside one turn skips nothing; it only hides the code\n`
+      + `from them for the five minutes it lives.\n\n`
       + (f.drafts && f.drafts.enabled
         ? `You need no source tree here: \`augur open <opportunity>/<prototype>\` fetches that one\n`
           + `prototype into a folder of its own (see below). Do not clone the workspace first.\n\n`
+          + `Until \`npm i -g @augurworks/augur\`, every verb runs as \`npx @augurworks/augur <verb>\`.\n`
+          + `The first \`open\` on a machine also installs a save hook in the editor tool's\n`
+          + `settings (it says which file): after each edit inside a draft folder it saves that\n`
+          + `draft; it does nothing elsewhere, and \`augur hook remove\` takes it out.\n\n`
         : `With no source tree yet, \`npx @augurworks/augur clone --space ${f.workspace}\` then fetches\n`
           + `one (it reads the origin from the pairing).\n\n`)
     : `Device pairing is switched off on this workspace. Ask an admin for an invite;\n`
@@ -11900,7 +11941,7 @@ async function handleRequest(request, env, ctx, url, trace) {
     if (url.pathname === "/__connect" && tctx.DEVICE_PAIRING) {
       const who = tctx.USERS.length ? await identify(request, env, tctx.USERS, { sessionKeys: tctx.SESSION_KEYS, tctx }) : null;
       if (!who && tctx.USERS.length) return htmlResponse(loginPage(tctx, "/__connect", false, url.href), 200);
-      return htmlResponse(connectPage(tctx, who), 200);
+      return htmlResponse(connectPage(tctx, who, url.origin), 200);
     }
     if (url.pathname.startsWith("/__publish/_pair/")) {
       // Identity is resolved here rather than reusing the gate's `me` below, because this

package/src/chrome/appchrome.mjs

@@ -386,10 +386,16 @@ function helpDrawer(state) {
             <li>The design system is read-only from a prototype. Edit the skill's own source rather than copying its classes out.</li>
           </ul>
 
+          <h4>Working with an assistant</h4>
+          <ul>
+            <li>Give it this workspace's address and say what you want changed or made. It reads how to get in from this site and hands you a link and a short code.</li>
+            <li>Open the link here (<code>/__connect</code>) and type the code. That pairs its terminal to publish as you; everything it lands carries your name.</li>
+            <li>From then on it opens a prototype as a draft, edits it live at the draft's own address, and lands it when you say so. Viewers cannot approve a code.</li>
+          </ul>
+
           <h4>Comment loop <span class="gvhelp__tag">maintainer</span></h4>
           <ul>
-            <li><code>npm run review --open</code> lists open threads.</li>
-            <li>The agent fixes, replies, resolves in-thread. Put it on <code>/loop</code> to keep watching.</li>
+            <li>In a checkout, <code>npm run review --open</code> lists open threads; an agent fixes, replies and resolves in-thread.</li>
             <li>Not automated. You steer it.</li>
           </ul>${spaceHelpSections(state)}
         </section>