@augurworks/augur 0.15.8 → 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.8",
+  "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}`);
@@ -70,6 +71,11 @@ async function post(pathPart, body) {
 // 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; }
@@ -178,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,7 +3748,7 @@ 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>
@@ -3761,6 +3761,10 @@ function connectPage(tctx, me) {
        <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" />
@@ -9275,22 +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`
-      + `The CLI is this engine's own, open source at ${f.source} — the same engine that\n`
-      + `serves this page; \`npm view @augurworks/augur repository\` names that repository.\n\n`
-      + `AGENTS: the approval is the person's act, in their browser — you cannot approve\n`
-      + `it from here and must not try; your part is to send them the line and collect\n`
-      + `the token afterwards. If your person reads your messages only after you finish\n`
-      + `your turn, run it with --no-wait: it prints the line and exits. Send them that\n`
-      + `line, end your turn, and run the same command again once they say they approved —\n`
-      + `the token is collected then, for that same code, and no second code is minted.\n`
-      + `Waiting inside one turn skips nothing; it only hides the code from them for the\n`
-      + `five minutes it lives.\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`
@@ -11922,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>