@minnovate/shadow-publisher 0.5.0 → 0.6.1

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

@@ -1,7 +1,7 @@
 {
   "name": "git-publisher",
   "displayName": "Git Publisher",
-  "version": "0.5.0",
+  "version": "0.6.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

@@ -76,7 +76,7 @@ exclusion rules are a safety net, not a secret scanner). Then publish it with st
 ## 3. Every update — and the first publish after `init`
 
 ```bash
-publisher sync . --message "<a few words on what changed>" --json
+publisher sync . --message "<a few words on what changed>" --timeout 90 --json
 ```
 
 That one command records what changed in the folder, brings in anything published meanwhile (a
@@ -85,12 +85,44 @@ the message in the user's words ("Add a contact page"), not git's.
 
 ## 4. Reading the result
 
+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.
+
+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.
+
+```json
+{"event":"stage","stage":"running","word":"checked","state":"in-progress","at":"2026-09-23T10:00:10Z"}
+```
+
+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.
+
 `state` says what happened; `hint` is one sentence you may pass on as it is.
 
 - `"published"` → the app was published. Mention what was recorded (`recorded.committed`) and, if
-  `recorded.excluded` is not empty, what was left out and why. Then tell them the portal shows the
-  app moving through **received → checked → going live → live**, and that it appears there within
-  a few minutes. (The publisher cannot follow those steps from here yet.)
+  `recorded.excluded` is not empty, what was left out and why. Then read `progress` (null with
+  `--no-wait`) and pass on its `hint`:
+  - `kind: "settled"` with `ending` `"live"`: the app is live. `"not-deployed"`: published and
+    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
+    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.
+  - `"unavailable"`, `"forbidden"` or `"malformed"`: the publish itself succeeded, but this
+    terminal cannot show the steps. Tell them to follow it in the portal. Never report a step that
+    no `stage` line said.
 - `"up_to_date"` → nothing new to publish; the service already has this version.
 - `"conflict"` → the user's change and a published change touched the same lines of
   `conflicts[]`. **Nothing was published and nothing was lost.** Do not resolve it on your own and

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

@@ -15,7 +15,9 @@ result. Never run `git add`, `git commit`, `git push`, `git pull`, `git merge`,
 publisher sync . --json
 ```
 
-Read `state` exactly as the `publish-app` skill describes (step 4). `merged` says whether anything
+Read the step lines and `state` exactly as the `publish-app` skill describes (step 4): after a
+publish it follows the app through received → checked → going live → live before it prints the
+result. `merged` says whether anything
 published elsewhere was brought in (`"fast-forward"` or `"merge"`); mention it when it is not null.
 
 ## Just looking

package/dist/publisher.cjs

@@ -3585,12 +3585,12 @@ async function resolveRevs(dir, revs, opts = {}) {
   const out = revs.map(
     (r) => r.startsWith("-") ? null : r.includes("\0") ? new PublisherError("INVALID_REQUEST", "NUL in git argument") : null
   );
-  const ask2 = revs.flatMap((r, i) => out[i] === null && !r.startsWith("-") ? [i] : []);
-  if (ask2.length === 0) return out;
-  const { stdout } = await runGit(["cat-file", "--batch-check=%(objectname)", "-Z"], { cwd: dir, input: ask2.map((i) => revs[i]).join("\0") + "\0", ...opts });
+  const ask3 = revs.flatMap((r, i) => out[i] === null && !r.startsWith("-") ? [i] : []);
+  if (ask3.length === 0) return out;
+  const { stdout } = await runGit(["cat-file", "--batch-check=%(objectname)", "-Z"], { cwd: dir, input: ask3.map((i) => revs[i]).join("\0") + "\0", ...opts });
   const records = stdout.toString("utf8").split("\0");
   const misses = [];
-  for (const [j, i] of ask2.entries()) {
+  for (const [j, i] of ask3.entries()) {
     const record2 = records[j] ?? "";
     if (record2 && !/ (missing|ambiguous)$/.test(record2)) out[i] = record2;
     else if (!revs[i].includes("^{")) misses.push(i);
@@ -4493,6 +4493,236 @@ async function updateEntry(url2, change) {
   await writeCredentials(file);
 }
 
+// ../client/src/transport.ts
+function assertCredentialEndpoint(endpoint) {
+  let url2;
+  try {
+    url2 = new URL(endpoint);
+  } catch {
+    throw new PublisherError("INVALID_REQUEST", `endpoint is not a URL: ${endpoint}`);
+  }
+  const loopback = url2.hostname === "127.0.0.1" || url2.hostname === "localhost" || url2.hostname === "[::1]";
+  if (url2.protocol !== "https:" && !(url2.protocol === "http:" && loopback)) {
+    throw new PublisherError("INVALID_REQUEST", `endpoint must be https (plain http only on loopback): ${url2.origin}`);
+  }
+}
+var Transport = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.endpoint = opts.endpoint.replace(/\/+$/, "");
+  }
+  opts;
+  fetchImpl;
+  endpoint;
+  async request(method, path, body, ro = {}) {
+    const retries = ro.retries ?? this.opts.maxRetries ?? 4;
+    let attempt = 0;
+    let refreshed = false;
+    for (; ; ) {
+      attempt++;
+      try {
+        return await this.once(method, path, body, ro);
+      } catch (e) {
+        if (e instanceof PublisherError && e.httpStatus === 401 && !refreshed && this.opts.refresh) {
+          refreshed = true;
+          if (await this.opts.refresh()) continue;
+        }
+        if (!(e instanceof PublisherError) || !e.retryable || attempt > retries || ro.signal?.aborted) throw e;
+        const delay2 = (this.opts.retryDelayMs ?? 300) * 2 ** (attempt - 1) * (0.5 + Math.random());
+        await sleep(Math.min(delay2, 1e4), ro.signal);
+      }
+    }
+  }
+  async once(method, path, body, ro) {
+    assertCredentialEndpoint(this.endpoint);
+    const token = await this.opts.token();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new PublisherError("NETWORK", "request timed out", { retryable: true })), this.opts.timeoutMs ?? 6e4);
+    const onAbort = () => controller.abort(new PublisherError("CANCELLED", "cancelled"));
+    ro.signal?.addEventListener("abort", onAbort, { once: true });
+    if (ro.signal?.aborted) onAbort();
+    try {
+      let res;
+      try {
+        res = await this.fetchImpl(`${this.endpoint}${path}`, {
+          method,
+          headers: {
+            authorization: `Bearer ${token}`,
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            [CLIENT_HEADER]: `${this.opts.clientName}/${this.opts.clientVersion}`,
+            ...body !== void 0 ? { "content-type": "application/json" } : {},
+            ...ro.headers ?? {}
+          },
+          ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+          signal: controller.signal
+        });
+      } catch (e) {
+        if (controller.signal.aborted && controller.signal.reason instanceof PublisherError) throw controller.signal.reason;
+        throw new PublisherError("NETWORK", `request failed: ${e.message}`, { retryable: true, cause: e });
+      }
+      const text = await res.text();
+      let parsed = null;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = null;
+        }
+      }
+      if (res.ok) return { status: res.status, body: parsed, headers: res.headers };
+      const err = parsed?.error;
+      const code = err && ERROR_CODES.includes(err.code) ? err.code : res.status >= 500 ? "UNAVAILABLE" : "INVALID_REQUEST";
+      throw new PublisherError(code, err?.message ?? `HTTP ${res.status}`, {
+        retryable: err?.retryable ?? (res.status === 429 || res.status >= 500),
+        httpStatus: res.status,
+        ...err?.details ? { details: err.details } : {}
+      });
+    } finally {
+      clearTimeout(timer);
+      ro.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve3, reject) => {
+    const t = setTimeout(resolve3, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(new PublisherError("CANCELLED", "cancelled"));
+      },
+      { once: true }
+    );
+  });
+}
+
+// ../client/src/run-progress.ts
+var RUN_STAGES = ["received", "running", "deploying", "live"];
+var STAGE_WORDS = { received: "received", running: "checked", deploying: "going live", live: "live" };
+var STATES = ["pending", "in-progress", "done", "failed", "skipped"];
+function readStages(run) {
+  if (!isRecord(run)) return { malformed: "a run that is not an object" };
+  if (!Object.hasOwn(run, "stages")) return null;
+  const stages = run["stages"];
+  if (!Array.isArray(stages) || stages.length !== RUN_STAGES.length) return { malformed: "stages that are not exactly four" };
+  const out = [];
+  for (const [index, entry] of stages.entries()) {
+    const stage = RUN_STAGES[index];
+    if (!isRecord(entry) || entry["stage"] !== stage) return { malformed: `stage ${index + 1} is not ${stage}` };
+    const state = entry["state"];
+    if (!STATES.includes(state)) return { malformed: `stage ${stage} has an unknown state` };
+    const at = entry["at"];
+    if (typeof at !== "string" && at !== null) return { malformed: `stage ${stage} has an unreadable time` };
+    out.push({ stage, word: STAGE_WORDS[stage], state, at });
+  }
+  return { stages: out };
+}
+function ending(stages) {
+  if (stages.some((s) => s.state === "pending" || s.state === "in-progress")) return null;
+  if (stages.some((s) => s.state === "failed")) return "failed";
+  if (stages[3].state === "done") return "live";
+  if (stages[1].state === "done" && stages[2].state === "skipped") return "not-deployed";
+  return "stopped";
+}
+var POLL_INTERVAL_MS = 5e3;
+var FOLLOW_TIMEOUT_MS = 15 * 6e4;
+async function followRun(input, opts) {
+  const fetchImpl = opts.fetch ?? fetch;
+  const sleep2 = opts.sleep ?? sleep;
+  const now = opts.now ?? Date.now;
+  const interval = opts.intervalMs ?? POLL_INTERVAL_MS;
+  const deadline = now() + (opts.timeoutMs ?? FOLLOW_TIMEOUT_MS);
+  const query = new URLSearchParams({ publication: input.publicationId, ref: input.ref, commit: input.commit });
+  const url2 = `${input.portal.replace(/\/+$/, "")}/api/v1/terminal/repositories/${encodeURIComponent(input.repoId)}/runs?${query}`;
+  const seen = /* @__PURE__ */ new Map();
+  let last = null;
+  let lastError = null;
+  let refreshed = false;
+  for (; ; ) {
+    const answer = await ask(fetchImpl, url2, await opts.token());
+    if (answer.status === 401 && !refreshed && opts.refresh !== void 0) {
+      refreshed = true;
+      if (await opts.refresh()) continue;
+    }
+    if (answer.status === 401) return { kind: "unauthorized" };
+    if (answer.status === 404) return { kind: "unavailable", reason: "no-route" };
+    if (answer.status === 403) return { kind: "forbidden" };
+    if (answer.status === 200) {
+      const run = soleRun(answer.body);
+      if ("detail" in run) return { kind: "malformed", detail: run.detail };
+      if (run.run !== null) {
+        const read = readStages(run.run);
+        if (read === null) return { kind: "unavailable", reason: "no-stages" };
+        if ("malformed" in read) return { kind: "malformed", detail: read.malformed };
+        last = read.stages;
+        for (const entry of read.stages) {
+          if (entry.state === "pending" || seen.get(entry.stage) === entry.state) continue;
+          seen.set(entry.stage, entry.state);
+          opts.onStage?.(entry);
+        }
+        const end = ending(read.stages);
+        if (end !== null) return { kind: "settled", ending: end, failedAt: read.stages.find((s) => s.state === "failed")?.word ?? null, stages: read.stages };
+      }
+      lastError = null;
+    } else {
+      lastError = answer.status === 0 ? "the portal could not be reached" : `the portal answered ${answer.status}`;
+    }
+    if (now() + interval > deadline) return { kind: "timed-out", stages: last, lastError };
+    await sleep2(interval);
+  }
+}
+function soleRun(body) {
+  if (!isRecord(body) || !Array.isArray(body["runs"])) return { detail: "an answer with no list of runs" };
+  const runs = body["runs"];
+  if (runs.length > 1) return { detail: "more than the one run this publication started" };
+  return { run: runs[0] ?? null };
+}
+async function ask(fetchImpl, url2, token) {
+  try {
+    const res = await fetchImpl(url2, { headers: { authorization: `Bearer ${token}`, accept: "application/json" }, signal: AbortSignal.timeout(3e4) });
+    const text = await res.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      if (res.status === 200) return { status: 200, body: void 0 };
+    }
+    return { status: res.status, body };
+  } catch {
+    return { status: 0, body: null };
+  }
+}
+function portalForEndpoint(endpoint) {
+  let url2;
+  try {
+    url2 = new URL(endpoint);
+  } catch {
+    return null;
+  }
+  if (url2.protocol !== "https:" || url2.pathname.replace(/\/+$/, "") !== "/publish") return null;
+  return url2.origin;
+}
+var RUN_PROGRESS = "run-progress";
+async function confirmPortal(portal, endpoint, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(`${portal}/api/v1/config`, { signal: AbortSignal.timeout(1e4) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const named = body?.publishingEndpoint;
+    const bare = (u) => u.replace(/\/+$/, "");
+    if (typeof named !== "string" || bare(named) !== bare(endpoint)) return null;
+    const terminal = body?.terminal;
+    return { terminal: Array.isArray(terminal) && terminal.every((name) => typeof name === "string") ? terminal : [] };
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // ../client/src/onboard.ts
 var import_promises6 = require("node:fs/promises");
 var import_node_path5 = require("node:path");
@@ -4693,111 +4923,6 @@ var import_node_crypto4 = require("node:crypto");
 // ../client/src/publish.ts
 var import_promises7 = require("node:fs/promises");
 
-// ../client/src/transport.ts
-function assertCredentialEndpoint(endpoint) {
-  let url2;
-  try {
-    url2 = new URL(endpoint);
-  } catch {
-    throw new PublisherError("INVALID_REQUEST", `endpoint is not a URL: ${endpoint}`);
-  }
-  const loopback = url2.hostname === "127.0.0.1" || url2.hostname === "localhost" || url2.hostname === "[::1]";
-  if (url2.protocol !== "https:" && !(url2.protocol === "http:" && loopback)) {
-    throw new PublisherError("INVALID_REQUEST", `endpoint must be https (plain http only on loopback): ${url2.origin}`);
-  }
-}
-var Transport = class {
-  constructor(opts) {
-    this.opts = opts;
-    this.fetchImpl = opts.fetch ?? fetch;
-    this.endpoint = opts.endpoint.replace(/\/+$/, "");
-  }
-  opts;
-  fetchImpl;
-  endpoint;
-  async request(method, path, body, ro = {}) {
-    const retries = ro.retries ?? this.opts.maxRetries ?? 4;
-    let attempt = 0;
-    let refreshed = false;
-    for (; ; ) {
-      attempt++;
-      try {
-        return await this.once(method, path, body, ro);
-      } catch (e) {
-        if (e instanceof PublisherError && e.httpStatus === 401 && !refreshed && this.opts.refresh) {
-          refreshed = true;
-          if (await this.opts.refresh()) continue;
-        }
-        if (!(e instanceof PublisherError) || !e.retryable || attempt > retries || ro.signal?.aborted) throw e;
-        const delay2 = (this.opts.retryDelayMs ?? 300) * 2 ** (attempt - 1) * (0.5 + Math.random());
-        await sleep(Math.min(delay2, 1e4), ro.signal);
-      }
-    }
-  }
-  async once(method, path, body, ro) {
-    assertCredentialEndpoint(this.endpoint);
-    const token = await this.opts.token();
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new PublisherError("NETWORK", "request timed out", { retryable: true })), this.opts.timeoutMs ?? 6e4);
-    const onAbort = () => controller.abort(new PublisherError("CANCELLED", "cancelled"));
-    ro.signal?.addEventListener("abort", onAbort, { once: true });
-    if (ro.signal?.aborted) onAbort();
-    try {
-      let res;
-      try {
-        res = await this.fetchImpl(`${this.endpoint}${path}`, {
-          method,
-          headers: {
-            authorization: `Bearer ${token}`,
-            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
-            [CLIENT_HEADER]: `${this.opts.clientName}/${this.opts.clientVersion}`,
-            ...body !== void 0 ? { "content-type": "application/json" } : {},
-            ...ro.headers ?? {}
-          },
-          ...body !== void 0 ? { body: JSON.stringify(body) } : {},
-          signal: controller.signal
-        });
-      } catch (e) {
-        if (controller.signal.aborted && controller.signal.reason instanceof PublisherError) throw controller.signal.reason;
-        throw new PublisherError("NETWORK", `request failed: ${e.message}`, { retryable: true, cause: e });
-      }
-      const text = await res.text();
-      let parsed = null;
-      if (text) {
-        try {
-          parsed = JSON.parse(text);
-        } catch {
-          parsed = null;
-        }
-      }
-      if (res.ok) return { status: res.status, body: parsed, headers: res.headers };
-      const err = parsed?.error;
-      const code = err && ERROR_CODES.includes(err.code) ? err.code : res.status >= 500 ? "UNAVAILABLE" : "INVALID_REQUEST";
-      throw new PublisherError(code, err?.message ?? `HTTP ${res.status}`, {
-        retryable: err?.retryable ?? (res.status === 429 || res.status >= 500),
-        httpStatus: res.status,
-        ...err?.details ? { details: err.details } : {}
-      });
-    } finally {
-      clearTimeout(timer);
-      ro.signal?.removeEventListener("abort", onAbort);
-    }
-  }
-};
-function sleep(ms, signal) {
-  return new Promise((resolve3, reject) => {
-    const t = setTimeout(resolve3, ms);
-    signal?.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(t);
-        reject(new PublisherError("CANCELLED", "cancelled"));
-      },
-      { once: true }
-    );
-  });
-}
-
 // ../client/src/upload.ts
 var import_node_fs4 = require("node:fs");
 var import_node_stream = require("node:stream");
@@ -5231,6 +5356,19 @@ var Publisher = class {
   fetchImpl;
   tokenFn;
   clientInfo;
+  /**
+   * Follow the run an accepted publication started, at the portal that serves this endpoint, with
+   * this publisher's own credential and its one refresh — the portal verifies the same token the
+   * control API does.
+   */
+  async followRun(input, opts = {}) {
+    return followRun(input, {
+      ...opts,
+      token: this.tokenFn,
+      refresh: async () => !this.opts.token && refreshStoredCredential(this.endpoint, { fetch: this.fetchImpl }),
+      fetch: this.fetchImpl
+    });
+  }
   async getCapabilities(call = {}) {
     const r = await this.transport.request("GET", "/v1/capabilities", void 0, call);
     return r.body;
@@ -5556,7 +5694,7 @@ function resolveChoice(answer, names) {
   }
   return names.find((n) => n.toLowerCase() === a.toLowerCase()) ?? null;
 }
-async function ask(question) {
+async function ask2(question) {
   const rl = (0, import_promises10.createInterface)({ input: process.stdin, output: process.stderr });
   try {
     return await rl.question(question);
@@ -5574,7 +5712,7 @@ ${purpose}
   names.forEach((n, i) => process.stderr.write(`  ${i + 1}) ${n}
 `));
   for (let attempt = 0; attempt < 3; attempt++) {
-    const answer = await ask(`
+    const answer = await ask2(`
 Which one? [1-${names.length}, or a name] `);
     if (answer === null) return null;
     const chosen = resolveChoice(answer, names);
@@ -5590,7 +5728,7 @@ Name this connection, so you never have to type ${endpoint} again.
 (for example: prod, dev, staging)
 `);
   for (let attempt = 0; attempt < 3; attempt++) {
-    const answer = await ask(suggested ? `
+    const answer = await ask2(suggested ? `
 Profile name [${suggested}]: ` : `
 Profile name: `);
     if (answer === null) return null;
@@ -5613,6 +5751,7 @@ var OPTIONS = {
   repo: { type: "string" },
   message: { type: "string" },
   publication: { type: "string" },
+  timeout: { type: "string" },
   branch: { type: "string" },
   ours: { type: "string" },
   theirs: { type: "string" },
@@ -5693,6 +5832,66 @@ 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 next = outcome.kind === "timed-out" ? { action: "follow", command: `publisher follow --publication ${o.publicationId} --json` } : void 0;
+  return { ...outcome, portal, hint: progressHint(outcome, portal), ...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) {
+  switch (r.kind) {
+    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/main.ts
 var USAGE = `publisher \u2014 publish an app's Git history to the serverless Git backend
 
@@ -5723,6 +5922,12 @@ Usage:
                                                         nothing published and nothing lost. No git needed
       [--mark-conflicts]                                on a conflict, put both versions in each file, marked,
                                                         to edit; the next sync records and publishes the edit
+      [--no-wait]                                       don't follow the app going live afterwards (received ->
+                                                        checked -> going live -> live, up to 15 minutes)
+      [--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>]
   publisher merge-check [dir] --ours <ref> --theirs <ref> [--apply]
   publisher info [dir]                                   repository state as seen by the server
   publisher doctor                                       environment check (node, git, credentials, association)
@@ -5767,6 +5972,10 @@ 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 resolutionInput = async (dir) => {
     let association;
     if (dir && await isGitRepo(dir)) association = (await readAssociation(dir))?.endpoint;
@@ -6045,9 +6254,11 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
      */
     case "sync": {
       const dir = dirArg(1);
-      const { p } = await client(dir);
+      const timeoutMs = followTimeoutMs(str2(flags["timeout"]));
+      const { p, endpoint } = await client(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;
       out({
         ok: r.state === "published" || r.state === "up_to_date",
         state: r.state,
@@ -6063,10 +6274,31 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
           rejection: o.rejection,
           ...o.next === null ? {} : { next: o.next }
         },
-        hint: syncHint(r.state, r.reconciled.before.conflicts, r.marked)
+        hint: syncHint(r.state, r.reconciled.before.conflicts, r.marked),
+        progress: followed
       });
       return r.state === "published" || r.state === "up_to_date" ? 0 : r.state === "unknown" ? 3 : 2;
     }
+    /**
+     * Pick up following a run where a bounded `sync --timeout` (or an interrupted one) left it. The
+     * ref and commit come from git-publisher's own record of the publication, so the command needs
+     * only its id. Each call reports the stages as they now stand, from the first.
+     */
+    case "follow": {
+      const dir = dirArg(1);
+      const publicationId = str2(flags["publication"]);
+      if (!publicationId) throw new PublisherError("INVALID_REQUEST", "follow requires --publication <id>");
+      const timeoutMs = followTimeoutMs(str2(flags["timeout"]));
+      const { p, endpoint } = await client(dir);
+      const repoId = str2(flags["repo"]) ?? (await readAssociation(dir))?.repoId;
+      if (!repoId) throw new PublisherError("LOCAL_STATE", "no repository association; pass --repo");
+      const publication = await p.getPublicationStatus(repoId, publicationId);
+      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 }) });
+      return 0;
+    }
     case "skills": {
       if (cmd[1] !== "install") throw new PublisherError("INVALID_REQUEST", `unknown skills command: ${cmd[1] ?? "(none)"}; expected install`);
       const r = await installSkills({ log });

package/package.json

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