@minnovate/shadow-publisher 0.8.4 → 0.9.1

package/dist/claude/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "git-publisher",
   "displayName": "Git Publisher",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "description": "Publish an app folder's Git history to the serverless Git publishing backend and keep it updated (\"publish my app\", \"update my app\", \"fetch the engineered version\").",
   "author": { "name": "git-publisher project" },
   "keywords": ["git", "publish", "deploy", "serverless"]

package/dist/claude/plugin/skills/publish-app/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: publish-app
 description: Publish or update the user's app (a folder) with the publisher. Use when the user says "publish my app", "update my app", "save my changes", "push my changes", "save this version online", or asks to resolve an interrupted publication. Handles first-time setup, every later update, interruption recovery and conflicts by running the `publisher` command; never uses git to commit or push.
-allowed-tools: Bash(publisher *), Bash(git status *), Bash(git diff *), Bash(git log *)
+allowed-tools: Bash(publisher *), Bash(npm install -g @minnovate/shadow-publisher*), Bash(git status *), Bash(git diff *), Bash(git log *)
 ---
 
 # Publish or update the user's app
@@ -25,14 +25,16 @@ Every command accepts `--json` and prints exactly one JSON object on stdout. Exi
 publisher --version
 ```
 
-If the command is not found, tell the user the publisher is not installed and that one command
-installs it: `npm install -g @minnovate/shadow-publisher` (it needs Node.js 22). Stop there.
+If the command is not found, install it: `npm install -g @minnovate/shadow-publisher` (it needs
+Node.js 22). In a Claude Cowork task this is normal: the sandbox starts empty every time, so install it
+without asking. On the person's own computer, say in one line that you are installing the
+publisher. If `npm` itself is missing, tell them Node.js 22 must be installed first, and stop.
 
 ```bash
 publisher doctor --json
 ```
 
-- `gitOk:false` → tell the user Git 2.46 or later must be installed; stop.
+- `gitOk:false` → tell the user Git 2.43 or later must be installed; stop.
 - Otherwise do exactly what **`next.action`** says. `doctor` works this out for you, and the same
   `next` object rides on `error.details` of any command that cannot resolve a connection — so you
   never have to interpret `credentials`, `endpoint` or `profiles` yourself.
@@ -40,11 +42,27 @@ publisher doctor --json
 | `next.action` | What it means | What to do |
 |---|---|---|
 | `"ready"` | Signed in and pointed somewhere. | **Nothing. Go to step 2 and do not mention any of this.** |
-| `"sign-in"` | Not connected to anything yet. | **Ask them nothing** — `next.ask` is `null`. Just run `next.command` (`publisher login --json`). It finds the service, opens their browser and prints a code for them to confirm; tell them to expect that, and wait. Use `--portal <url>` only if they say they are on a different platform. |
+| `"sign-in"` | Not connected to anything yet. | **Ask them nothing** — `next.ask` is `null`. Run `next.command` the way "Signing in" below says. Use `--portal <url>` only if they say they are on a different platform. |
 | `"choose-profile"` | Several places are set up and none is marked usual. | Show `next.profiles` and ask `next.ask`. Then run `next.command` with the name they picked. |
-| `"reauthenticate"` | The place is known; the credential is gone or expired. | Just run `next.command`. `next.ask` is `null` — do **not** ask them for anything; the browser sign-in asks them itself. |
+| `"reauthenticate"` | The place is known; the credential is gone or expired. | Run `next.command` the way "Signing in" below says. `next.ask` is `null` — do **not** ask them for anything; the browser sign-in asks them itself. |
 | `"bind-endpoint"` | A token is set in the environment, but nothing said where it may go. | **Stop** and tell them publishing is blocked by a token set in this shell. `next.command` is `null` on purpose: never set `GIT_PUBLISHER_ENDPOINT` or pass `--endpoint` yourself — that is exactly the choice the check leaves to whoever set the token. |
 
+### Signing in
+
+`publisher login` waits until the person has confirmed a code in their browser, and your shell may
+show nothing until a command ends. So never run it in the foreground. Start it in the background with
+its output going to a file, and read the file:
+
+```bash
+publisher login --json > /tmp/publisher-login.log 2>&1 &
+```
+
+Within a few seconds the log shows `To sign in, open:` with a link under it, and `and confirm the
+code:` with the code under it. Give the person both, as a link they can click, and say the page will ask them to sign in with their work account.
+Then read the log every few seconds until it holds a JSON object (`ok: true`), for up to ten minutes.
+In a Claude Cowork task this happens again in every new task, because the sandbox forgets the
+sign-in when the task ends.
+
 **Never ask the user for a token, an endpoint, a URL or a credential — in any words.** They are
 publishing an app; they do not know what those are, and you do not need them: `login` discovers
 where publishing lives and signs them in through their browser. `next.ask` is `null` whenever
@@ -68,36 +86,36 @@ know what was left out (the exclusion rules are a safety net, not a secret scann
 ## 3. Every publish, the first one included
 
 ```bash
-publisher sync . --message "<a few words on what changed>" --timeout 90 --json
+publisher sync . --message "<a few words on what changed>" --until-change --timeout 100 --json
 ```
 
 That one command records what changed in the folder, brings in anything published meanwhile (a
 fast-forward or a clean merge — it never rewrites the user's work), and publishes the result. Write
 the message in the user's words ("Add a contact page"), not git's.
 
-## 4. Reading the result
+## 4. Telling them how it goes, step by step
 
-After a publish, the command follows the app going live, asking every 5 seconds, for at most
-`--timeout` seconds. Keep that at 90: your shell tool shows output only when a command ends, and
-cuts one off after two minutes. With `--json` it prints one line per step, then the result object
-as the LAST line.
+After a publish, the app goes through four steps: **received**, **checked**, **going live**,
+**live**. It takes a few minutes, and the person sees nothing unless you tell them. So the command
+returns as soon as the next step starts (`--until-change`), and you tell them, then wait for the
+next one:
 
-If the run is still going when the 90 seconds are up, `progress.kind` is `"timed-out"` and
-`progress.next.command` picks it up. Run it (it is `publisher follow --publication <id> --json`;
-add `--timeout 90`) and repeat until `progress.kind` is no longer `"timed-out"`, up to about 15
-minutes in all. Each call prints the steps as they now stand, from the first: relay only the ones
-you have not relayed yet.
+1. Read the result from the LAST line of the output (the lines before it are the steps, as JSON).
+2. If `progress.kind` is `"moving"` or `"timed-out"`, the app is still on its way. Tell the person
+   where it is in one short sentence, in their language — `progress.hint` says it ("Now: going
+   live.") — then run `progress.next.command` exactly as given, adding `--timeout 100`.
+3. Repeat until `progress.kind` is anything else, for up to about 15 minutes in all. Then tell them
+   how it ended (below).
 
-```json
-{"event":"stage","stage":"running","word":"checked","state":"in-progress","at":"2026-09-23T10:00:10Z"}
-```
+Name a step only by its `word` — **received**, **checked**, **going live**, **live** — never by
+its `stage` name, and never a step no line said. Each call starts by printing the steps as they
+stand: tell only what is new.
 
-Relay each step in its `word` — **received**, **checked**, **going live**, **live** — and nothing
-else: not the `stage` name, not a step you guessed. Read the result from the last line. **If the
-command was cut off while following**, the publication had already succeeded before the following
-began: say it is published, and follow it with `publisher follow --publication <publicationId>
---timeout 90 --json` (the id is in the `sync` output's `publication`, or `publisher status`). Do
-not run `sync` again to find out. `--no-wait` skips the following, for when the user asks not to wait.
+**If a command was cut off while following**, the publication had already succeeded before the
+following began: say it is published, and follow it with `publisher follow <folder> --publication
+<publicationId> --until-change --timeout 100 --json` (the id is in the `sync` output's
+`publication`, or `publisher status`). Do not run `sync` again to find out. `--no-wait` skips the
+following, for when the person asks not to wait.
 
 `state` says what happened; `hint` is one sentence you may pass on as it is.
 
@@ -108,7 +126,7 @@ not run `sync` again to find out. `--no-wait` skips the following, for when the
     checked, and this organisation does not deploy automatically. `"failed"`: it stopped at
     `failedAt`; the portal says why — do not guess the reason. `"stopped"`: a newer publication
     replaced it.
-  - `"timed-out"`: still going; run `progress.next.command` as above. After about 15 minutes in
+  - `"moving"` or `"timed-out"`: still going; follow it as step 4 says. After about 15 minutes in
     all, stop and point them to the portal (`progress.portal`).
   - `"unauthorized"`: published, but the portal did not accept this sign-in; run `publisher login`
     before the next publish.
@@ -134,7 +152,28 @@ not run `sync` again to find out. `--no-wait` skips the following, for when the
 - Exit code 4: run `publisher doctor --json` and follow `next.action` (normally `reauthenticate`:
   run `next.command`). Never ask the user for a token.
 
-## 5. Interrupted earlier?
+## 5. A folder that starts empty
+
+On a new computer, or in a Claude Cowork task (whose sandbox starts empty every time), the app the
+person means is not here yet. Find it, and bring it into a new folder:
+
+```bash
+publisher list --json
+```
+
+`apps[]` lists what they published, newest first, each with its `name` and a `checkout` command.
+Ask which one only if the name does not settle it, then run its `checkout` command and work in that
+folder. Never `sync` an empty new folder in its place: that makes a second app.
+
+## If the service cannot be reached
+
+In a sandbox (Claude Cowork, Claude Code on the web) a `NETWORK` error, or `CONNECT tunnel failed,
+response 403`, usually means the sandbox's network does not allow the platform. Tell the person that
+their Claude settings must allow the platform's domain and its storage (`*.s3.<region>.amazonaws.com`)
+under Settings → Capabilities, or that their organisation's owner must, on a Team or Enterprise plan.
+Do not retry until they say it is done.
+
+## 6. Interrupted earlier?
 
 If a previous publish was interrupted (network loss, closed session), `publisher status . --json`
 resumes or resolves it. Always run it before starting a new sync when the last result was unknown.

package/dist/claude/plugin/skills/sync-app/SKILL.md

@@ -12,7 +12,7 @@ result. Never run `git add`, `git commit`, `git push`, `git pull`, `git merge`,
 `git reset` or `git rebase` in the user's app folder.
 
 ```bash
-publisher sync . --json
+publisher sync . --until-change --timeout 100 --json
 ```
 
 Read the step lines and `state` exactly as the `publish-app` skill describes (step 4): after a
@@ -40,7 +40,7 @@ publisher answer <question id>=<value> --json
 
 A value that is not an option is refused before anything is sent; `error.details.questions` lists
 the choices. Exit 4 means this sign-in may not answer (an owner or admin can); exit 3 means ask
-again. Then `publisher follow . --publication <id> --json` to see it go live.
+again. Then `publisher follow . --publication <id> --until-change --timeout 100 --json` to see it go live, telling them each step as `publish-app` step 4 says.
 
 ## Just looking
 
@@ -63,9 +63,10 @@ publisher workspace-status . --json      # state + hint; exit 2 means conflict
 
 ## A fresh copy
 
-When the user wants their app in a new folder (a new computer, a clean start):
+When the user wants their app in a new folder (a new computer, a clean start, a Claude Cowork task):
 
 ```bash
+publisher list --json                                     # their apps, each with its checkout command
 publisher checkout <new-folder> --repo <repoId> --json   # a NEW folder only; refuses a non-empty one
 ```
 
@@ -87,7 +88,7 @@ recorded locally, and the published version is still on the service.
 
    Each file in `conflicts[]` now holds both versions between `<<<<<<<`, `=======` and `>>>>>>>`
    lines. Edit each to what they chose, and remove those lines.
-4. Run `publisher sync . --json`. It records the edit and publishes it. If a file still carries the
+4. Run `publisher sync . --until-change --timeout 100 --json`. It records the edit and publishes it. If a file still carries the
    marker lines it refuses, names the files (`error.details.marked`) and publishes nothing; finish
    the edit and run it again.
 

package/dist/publisher.cjs

@@ -2564,13 +2564,14 @@ var LimitsSchema = object({
   maxTemporaryBytes: _default(positiveInt(), 3 * 512 * 1024 * 1024),
   /** wall-clock bound for a single validation git command */
   gitTimeoutMs: _default(positiveInt(), 3e5),
-  // ---- per-account bounds ----
+  // ---- per-organisation bounds ----
   /**
-   * repositories one person may create, counted from the owner index; anyone may sign up and
-   * publish, so this bounds one account (docs/proposals/personal-organisations.md §8). Service
-   * principals are not counted. Defaulted so an older server reads as the default, not a failure.
+   * ACTIVE repositories an organisation may hold when it sets no quota of its own in users
+   * (ADR-0014 A1); anyone may sign up and publish, so this bounds one account's organisation.
+   * Named `maxRepositoriesPerPrincipal` before 0.9.0, when it counted a creator's repositories.
+   * Defaulted so an older server reads as the default, not a failure.
    */
-  maxRepositoriesPerPrincipal: _default(positiveInt(), 25)
+  maxRepositoriesPerOrganisation: _default(positiveInt(), 25)
 });
 var DEFAULT_LIMITS = {
   maxPackBytes: 256 * 1024 * 1024,
@@ -2588,7 +2589,7 @@ var DEFAULT_LIMITS = {
   maxProcessMemoryBytes: 2 * 1024 * 1024 * 1024,
   maxTemporaryBytes: 3 * 512 * 1024 * 1024,
   gitTimeoutMs: 3e5,
-  maxRepositoriesPerPrincipal: 25
+  maxRepositoriesPerOrganisation: 25
 };
 
 // ../protocol/src/storage-schema.ts
@@ -3511,12 +3512,6 @@ async function gitVersion() {
   cachedVersion = m[1];
   return cachedVersion;
 }
-var MINIMUM_GIT_VERSION = "2.46.0";
-async function assertGitVersion(minimum = MINIMUM_GIT_VERSION) {
-  const v = await gitVersion();
-  if (compareVersions(v, minimum) < 0) throw new PublisherError("GIT", `git ${v} is older than the minimum ${minimum}`);
-  return v;
-}
 function compareVersions(a, b) {
   const pa = a.split(".").map(Number);
   const pb = b.split(".").map(Number);
@@ -4725,6 +4720,7 @@ async function followRun(input, opts) {
   let last = null;
   let lastError = null;
   let refreshed = false;
+  let answered = false;
   for (; ; ) {
     const answer = await ask(fetchImpl, url2, await opts.token());
     if (answer.status === 401 && !refreshed && opts.refresh !== void 0) {
@@ -4742,15 +4738,19 @@ async function followRun(input, opts) {
         if (read2 === null) return { kind: "unavailable", reason: "no-stages" };
         if ("malformed" in read2) return { kind: "malformed", detail: read2.malformed };
         last = read2.stages;
+        let moved = false;
         for (const entry of read2.stages) {
           if (entry.state === "pending" || seen.get(entry.stage) === entry.state) continue;
           seen.set(entry.stage, entry.state);
           opts.onStage?.(entry);
+          moved = true;
         }
         if (isRecord2(run.run) && run.run["status"] === "awaiting-approval") return { kind: "waiting", stages: read2.stages };
         const end = ending(read2.stages);
         if (end !== null) return { kind: "settled", ending: end, failedAt: read2.stages.find((s) => s.state === "failed")?.word ?? null, stages: read2.stages };
+        if (opts.untilChange === true && moved && answered) return { kind: "moving", stages: read2.stages };
       }
+      answered = true;
       lastError = null;
     } else {
       lastError = answer.status === 0 ? "the portal could not be reached" : `the portal answered ${answer.status}`;
@@ -5880,6 +5880,108 @@ async function discoverEndpoint(portal, fetchImpl = fetch) {
   return endpoint;
 }
 
+// src/git-minimum.ts
+var CLIENT_GIT_MINIMUM = "2.43.0";
+function gitSupported(version2) {
+  return compareVersions(version2, CLIENT_GIT_MINIMUM) >= 0;
+}
+
+// src/follow.ts
+async function followPublication(p, endpoint, o, opts) {
+  const derived = portalForEndpoint(endpoint);
+  const confirmed = derived === null ? null : await confirmPortal(derived, endpoint, opts.fetch);
+  const portal = confirmed === null ? null : derived;
+  const elsewhere = (reason) => ({ kind: "unavailable", reason, portal, hint: inPortal(portal, "Published.", "Follow it") });
+  if (portal === null || confirmed === null) return elsewhere("no-portal");
+  if (!confirmed.terminal.includes(RUN_PROGRESS)) {
+    const noRoute = { kind: "unavailable", reason: "no-route" };
+    return { ...noRoute, portal, hint: progressHint(noRoute, portal) };
+  }
+  const refs = Object.entries(o.refs ?? {});
+  if (refs.length !== 1) return elsewhere("several-refs");
+  const [ref, commit] = refs[0];
+  opts.log("Following it: received -> checked -> going live -> live. Ctrl-C stops watching; the publication is already saved.");
+  const outcome = await p.followRun(
+    { portal, repoId: o.repoId, publicationId: o.publicationId, ref, commit },
+    { onStage: opts.onStage, ...opts.timeoutMs === void 0 ? {} : { timeoutMs: opts.timeoutMs }, ...opts.untilChange === true ? { untilChange: true } : {} }
+  );
+  const answerable = confirmed.terminal.includes(PREPARATION);
+  const dir = shellWord(opts.dir);
+  const next = outcome.kind === "timed-out" || outcome.kind === "moving" ? { action: "follow", command: `publisher follow ${dir} --publication ${o.publicationId}${opts.untilChange === true ? " --until-change" : ""} --json` } : outcome.kind === "waiting" && answerable ? { action: "question", command: `publisher question ${dir} --json` } : void 0;
+  return { ...outcome, portal, hint: progressHint(outcome, portal, answerable), ...next === void 0 ? {} : { next } };
+}
+function followTimeoutMs(flag) {
+  if (flag === void 0) return FOLLOW_TIMEOUT_MS;
+  if (!/^[1-9][0-9]*$/.test(flag)) throw new PublisherError("INVALID_REQUEST", `--timeout takes a whole number of seconds, not ${JSON.stringify(flag)}`);
+  return Math.min(Number(flag) * 1e3, FOLLOW_TIMEOUT_MS);
+}
+function shellWord(path) {
+  return /^[A-Za-z0-9_./-]+$/.test(path) ? path : `'${path.replace(/'/g, `'\\''`)}'`;
+}
+function stageEmitter(json, quiet) {
+  return (e) => {
+    if (json) process.stdout.write(stageLine(e, true) + "\n");
+    else if (!quiet) process.stderr.write(stageLine(e, false) + "\n");
+  };
+}
+function stageLine(e, json) {
+  return json ? JSON.stringify({ event: "stage", stage: e.stage, word: e.word, state: e.state, at: e.at }) : `  ${e.word}: ${e.state.replace("-", " ")}`;
+}
+function inPortal(portal, lead, verb) {
+  return `${lead} ${verb} in the portal${portal === null ? "" : `: ${portal}`}.`;
+}
+function progressHint(r, portal, answerable = false) {
+  switch (r.kind) {
+    case "waiting":
+      return answerable ? "It is waiting for an answer from you. Run publisher question to see it." : inPortal(portal, "It is waiting for an answer from you.", "Answer it");
+    case "settled":
+      switch (r.ending) {
+        case "live":
+          return "Your app is live.";
+        case "not-deployed":
+          return "Published and checked; this organisation does not deploy automatically.";
+        case "failed":
+          return inPortal(portal, `It stopped at "${r.failedAt ?? "a step"}".`, "See why");
+        case "stopped":
+          return "A newer publication replaced this one before it went live.";
+      }
+      break;
+    case "moving": {
+      const now = r.stages.find((s) => s.state === "in-progress") ?? r.stages.filter((s) => s.state !== "pending").at(-1);
+      return `Now: ${now?.word ?? "received"}. Run next.command to wait for the next step.`;
+    }
+    case "timed-out":
+      return inPortal(portal, `Still going${r.lastError === null ? "" : ` (${r.lastError})`}; run next.command to keep following.`, "Or follow it");
+    case "unavailable":
+      return inPortal(portal, "Published. This portal cannot show progress in the terminal yet.", "Follow it");
+    case "unauthorized":
+      return inPortal(portal, "Published, but the portal did not accept this sign-in (run publisher login).", "Follow it");
+    case "forbidden":
+      return inPortal(portal, "Published, but the portal would not show this sign-in the run.", "Follow it");
+    case "malformed":
+      return inPortal(portal, `Published, but the portal's answer about the run could not be read (${r.detail}).`, "Follow it");
+  }
+}
+
+// src/list.ts
+async function listApps(p, opts = {}) {
+  const page = await p.listRepositories({ state: opts.archived ? "archived" : "active", limit: 200, ...opts.cursor ? { cursor: opts.cursor } : {} });
+  const apps = page.repositories.map((r) => ({
+    repoId: r.repoId,
+    name: r.name,
+    createdAt: r.createdAt,
+    publishedAt: r.lastTransaction?.committedAt ?? null,
+    archived: r.archived,
+    checkout: `publisher checkout ${shellWord(folderFor(r.name))} --repo ${r.repoId} --json`
+  })).sort((a, b) => (b.publishedAt ?? b.createdAt).localeCompare(a.publishedAt ?? a.createdAt));
+  const hint = apps.length === 0 ? "You have not published an app from this sign-in yet." : "To work on one in a new folder, run its checkout command.";
+  return { apps, nextCursor: page.nextCursor, hint };
+}
+function folderFor(name) {
+  const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug2 === "" ? "app" : slug2;
+}
+
 // src/init.ts
 async function repositoryForInit(p, endpoint, name, opts = {}) {
   const portal = portalForEndpoint(endpoint);
@@ -5981,6 +6083,7 @@ var OPTIONS = {
   ours: { type: "string" },
   theirs: { type: "string" },
   to: { type: "string" },
+  cursor: { type: "string" },
   ref: { type: "string", multiple: true },
   json: { type: "boolean" },
   quiet: { type: "boolean" },
@@ -5990,8 +6093,10 @@ var OPTIONS = {
   help: { type: "boolean" },
   version: { type: "boolean" },
   "set-default": { type: "boolean" },
+  archived: { type: "boolean" },
   // A flag of its own, not a negation of --wait: there is no --wait.
-  "no-wait": { type: "boolean" }
+  "no-wait": { type: "boolean" },
+  "until-change": { type: "boolean" }
 };
 function parseArgs(argv) {
   try {
@@ -6057,69 +6162,6 @@ async function installSkills({ log }) {
   };
 }
 
-// src/follow.ts
-async function followPublication(p, endpoint, o, opts) {
-  const derived = portalForEndpoint(endpoint);
-  const confirmed = derived === null ? null : await confirmPortal(derived, endpoint, opts.fetch);
-  const portal = confirmed === null ? null : derived;
-  const elsewhere = (reason) => ({ kind: "unavailable", reason, portal, hint: inPortal(portal, "Published.", "Follow it") });
-  if (portal === null || confirmed === null) return elsewhere("no-portal");
-  if (!confirmed.terminal.includes(RUN_PROGRESS)) {
-    const noRoute = { kind: "unavailable", reason: "no-route" };
-    return { ...noRoute, portal, hint: progressHint(noRoute, portal) };
-  }
-  const refs = Object.entries(o.refs ?? {});
-  if (refs.length !== 1) return elsewhere("several-refs");
-  const [ref, commit] = refs[0];
-  opts.log("Following it: received -> checked -> going live -> live. Ctrl-C stops watching; the publication is already saved.");
-  const outcome = await p.followRun(
-    { portal, repoId: o.repoId, publicationId: o.publicationId, ref, commit },
-    { onStage: opts.onStage, ...opts.timeoutMs === void 0 ? {} : { timeoutMs: opts.timeoutMs } }
-  );
-  const answerable = confirmed.terminal.includes(PREPARATION);
-  const next = outcome.kind === "timed-out" ? { action: "follow", command: `publisher follow --publication ${o.publicationId} --json` } : outcome.kind === "waiting" && answerable ? { action: "question", command: "publisher question --json" } : void 0;
-  return { ...outcome, portal, hint: progressHint(outcome, portal, answerable), ...next === void 0 ? {} : { next } };
-}
-function followTimeoutMs(flag) {
-  if (flag === void 0) return FOLLOW_TIMEOUT_MS;
-  if (!/^[1-9][0-9]*$/.test(flag)) throw new PublisherError("INVALID_REQUEST", `--timeout takes a whole number of seconds, not ${JSON.stringify(flag)}`);
-  return Math.min(Number(flag) * 1e3, FOLLOW_TIMEOUT_MS);
-}
-function stageLine(e, json) {
-  return json ? JSON.stringify({ event: "stage", stage: e.stage, word: e.word, state: e.state, at: e.at }) : `  ${e.word}: ${e.state.replace("-", " ")}`;
-}
-function inPortal(portal, lead, verb) {
-  return `${lead} ${verb} in the portal${portal === null ? "" : `: ${portal}`}.`;
-}
-function progressHint(r, portal, answerable = false) {
-  switch (r.kind) {
-    case "waiting":
-      return answerable ? "It is waiting for an answer from you. Run publisher question to see it." : inPortal(portal, "It is waiting for an answer from you.", "Answer it");
-    case "settled":
-      switch (r.ending) {
-        case "live":
-          return "Your app is live.";
-        case "not-deployed":
-          return "Published and checked; this organisation does not deploy automatically.";
-        case "failed":
-          return inPortal(portal, `It stopped at "${r.failedAt ?? "a step"}".`, "See why");
-        case "stopped":
-          return "A newer publication replaced this one before it went live.";
-      }
-      break;
-    case "timed-out":
-      return inPortal(portal, `Still going${r.lastError === null ? "" : ` (${r.lastError})`}; run next.command to keep following.`, "Or follow it");
-    case "unavailable":
-      return inPortal(portal, "Published. This portal cannot show progress in the terminal yet.", "Follow it");
-    case "unauthorized":
-      return inPortal(portal, "Published, but the portal did not accept this sign-in (run publisher login).", "Follow it");
-    case "forbidden":
-      return inPortal(portal, "Published, but the portal would not show this sign-in the run.", "Follow it");
-    case "malformed":
-      return inPortal(portal, `Published, but the portal's answer about the run could not be read (${r.detail}).`, "Follow it");
-  }
-}
-
 // src/question.ts
 async function questionAt(p, endpoint, repoId, opts = {}) {
   const at = await portalAt(endpoint, opts);
@@ -6213,6 +6255,8 @@ Usage:
                                                         a change, use sync
   publisher status [dir] [--publication <id>]           resolve pending/interrupted publications
   publisher fetch [dir]
+  publisher list [--archived] [--cursor <c>]            the apps you published, newest first, each with the
+                                                        checkout command that brings it into a new folder
   publisher checkout <dir> --repo <id> [--branch <name>]  create a NEW editable workspace (never overlays a folder)
   publisher workspace-status [dir]                      offline mapping + where the workspace stands (real three-way check)
   publisher sync [dir] [--message <text>] [--name <app>] THE way to publish: a folder linked to nothing first gets its
@@ -6228,7 +6272,7 @@ Usage:
       [--timeout <seconds>]                             follow for at most this long; if it is still going, the
                                                         result's next.command picks it up
   publisher follow [dir] --publication <id>             follow an accepted publication's run where a sync left it
-      [--timeout <seconds>]
+      [--timeout <seconds>] [--until-change]            --until-change (sync too): return at the next step, to tell it
   publisher question [dir] [--repo <id>]                the question the app's preparation waits on, if any,
                                                         with each option's value (answering needs owner or admin)
   publisher answer <question>=<value>... [--repo <id>]  answer it from this folder; a value that is not one of
@@ -6277,10 +6321,7 @@ async function main(argv) {
     if (e.phase === "done") process.stderr.write("\n");
   };
   const dirArg = (i) => (0, import_node_path8.resolve)(cmd[i] ?? ".");
-  const emitStage = (e) => {
-    if (json) process.stdout.write(stageLine(e, true) + "\n");
-    else if (!quiet) process.stderr.write(stageLine(e, false) + "\n");
-  };
+  const following = { onStage: stageEmitter(json, quiet), log, untilChange: flags["until-change"] === true };
   const resolutionInput = async (dir) => {
     let association;
     if (dir && await isGitRepo(dir)) association = (await readAssociation(dir))?.endpoint;
@@ -6353,7 +6394,7 @@ async function main(argv) {
       out({
         node: process.version,
         git,
-        gitOk: git ? await assertGitVersion().then(() => true).catch(() => false) : false,
+        gitOk: git !== null && gitSupported(git),
         endpoint: s.resolution.kind === "resolved" ? s.resolution.endpoint : null,
         endpointSource: s.resolution.kind === "resolved" ? s.resolution.source : null,
         profile: s.resolution.kind === "resolved" ? s.resolution.profile ?? null : null,
@@ -6536,6 +6577,9 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       out({ ok: true, repoId: r.repoId, generation: r.generation, remote: r.remote, refs: r.refs, tracking: r.tracking, bytes: r.bytes });
       return 0;
     }
+    case "list":
+      out(await listApps((await client()).p, { archived: flags["archived"] === true, cursor: str2(flags["cursor"]) }));
+      return 0;
     case "checkout": {
       const dir = dirArg(1);
       const repoId = str2(flags["repo"]);
@@ -6565,7 +6609,7 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       const linked = await isGitRepo(dir) && await readAssociation(dir) !== null ? null : await linkFolder(p, endpoint, dir, {});
       const r = await p.syncChanges({ directory: dir, markConflicts: flags["mark-conflicts"] === true, ...optStr(flags, "message") }, { onProgress: progress });
       const o = r.published;
-      const followed = o !== null && o.state === "accepted" && flags["no-wait"] !== true ? await followPublication(p, endpoint, o, { onStage: emitStage, log, timeoutMs }) : null;
+      const followed = o !== null && o.state === "accepted" && flags["no-wait"] !== true ? await followPublication(p, endpoint, o, { ...following, timeoutMs, dir }) : null;
       out({
         ok: r.state === "published" || r.state === "up_to_date",
         state: r.state,
@@ -6604,7 +6648,7 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       if (publication.state !== "accepted") {
         throw new PublisherError("LOCAL_STATE", `publication ${publicationId} is ${publication.state}, not accepted; run publisher status`);
       }
-      out({ publicationId, progress: await followPublication(p, endpoint, publication, { onStage: emitStage, log, timeoutMs }) });
+      out({ publicationId, progress: await followPublication(p, endpoint, publication, { ...following, timeoutMs, dir }) });
       return 0;
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnovate/shadow-publisher",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "description": "publisher: publish an app's Git history to the serverless Git backend",
   "license": "Apache-2.0",
   "type": "module",