@minnovate/shadow-publisher 0.6.3 → 0.7.0

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

@@ -1,7 +1,7 @@
 {
   "name": "git-publisher",
   "displayName": "Git Publisher",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "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/sync-app/SKILL.md

@@ -20,6 +20,28 @@ publish it follows the app through received → checked → going live → live
 result. `merged` says whether anything
 published elsewhere was brought in (`"fast-forward"` or `"merge"`); mention it when it is not null.
 
+## When it waits for an answer
+
+Sometimes the app's preparation asks one business question before it can go on (for example
+whether to use the organisation's data). `follow` then stops with `kind: "waiting"` and
+`next.command`. Read the question:
+
+```bash
+publisher question . --json
+```
+
+Tell the person `questions[].text` and the `label` of each option, and ask which they want. Answer
+with the option's `value`, never its label, only once they have chosen — or directly when they
+told you what to answer:
+
+```bash
+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.
+
 ## Just looking
 
 To say where the folder stands without changing anything:

package/dist/publisher.cjs

@@ -2809,6 +2809,12 @@ var PrincipalRecord = object({
   principal: PrincipalId,
   disabled: boolean2(),
   disabledAt: _default(nullable(IsoDate), null),
+  /**
+   * When the credentials tenant made the change this record reflects (ADR-0017), and what a later
+   * event is ordered against: EventBridge does not order deliveries, and a late enable must not undo
+   * a newer disable. Null on a record written by hand, which any event supersedes.
+   */
+  changedAt: _default(nullable(IsoDate), null),
   note: _default(nullable(string2().check(_maxLength(256))), null)
 });
 
@@ -3585,12 +3591,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 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 ask4 = revs.flatMap((r, i) => out[i] === null && !r.startsWith("-") ? [i] : []);
+  if (ask4.length === 0) return out;
+  const { stdout } = await runGit(["cat-file", "--batch-check=%(objectname)", "-Z"], { cwd: dir, input: ask4.map((i) => revs[i]).join("\0") + "\0", ...opts });
   const records = stdout.toString("utf8").split("\0");
   const misses = [];
-  for (const [j, i] of ask3.entries()) {
+  for (const [j, i] of ask4.entries()) {
     const record2 = records[j] ?? "";
     if (record2 && !/ (missing|ambiguous)$/.test(record2)) out[i] = record2;
     else if (!revs[i].includes("^{")) misses.push(i);
@@ -3990,7 +3996,7 @@ async function noteAcceptedPublication(directory, outcome, now = /* @__PURE__ */
   if (!oid) return;
   await advanceWorkspaceBase(directory, { oid, generation: outcome.resultGeneration }, now);
 }
-async function adoptWorkspace(client, directory, call = {}, now = /* @__PURE__ */ new Date()) {
+async function adoptWorkspace(client, directory, call2 = {}, now = /* @__PURE__ */ new Date()) {
   const dir = (0, import_node_path3.resolve)(directory);
   const existing = await getWorkspaceMapping(dir);
   if (existing) return existing;
@@ -3999,13 +4005,13 @@ async function adoptWorkspace(client, directory, call = {}, now = /* @__PURE__ *
   if (!a) throw new PublisherError("LOCAL_STATE", "this folder is not associated with a published repository; run init first");
   const branch = (await currentBranch(dir))?.replace(/^refs\/heads\//, "") ?? null;
   if (!branch) throw new PublisherError("LOCAL_STATE", "HEAD is detached; check out the branch this folder publishes, then run sync again");
-  const repo = await client.getRepository(a.repoId, call);
+  const repo = await client.getRepository(a.repoId, call2);
   const remoteOid = repo.refs[`refs/heads/${branch}`] ?? null;
   const tip = await revParse(dir, `refs/heads/${branch}`);
   let baseOid = null;
   let baseGeneration = 0;
   if (remoteOid) {
-    if (!await objectExists(dir, remoteOid)) await client.fetch({ repoDir: dir, repoId: a.repoId, remote: a.remote }, call);
+    if (!await objectExists(dir, remoteOid)) await client.fetch({ repoDir: dir, repoId: a.repoId, remote: a.remote }, call2);
     const haveRemote = await objectExists(dir, remoteOid);
     if (!tip) {
       baseOid = haveRemote ? remoteOid : null;
@@ -4064,15 +4070,15 @@ async function removeStalePartials(target, repoId) {
   }
   return removed;
 }
-async function checkoutWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new Date()) {
+async function checkoutWorkspace(client, opts, call2 = {}, now = /* @__PURE__ */ new Date()) {
   const target = (0, import_node_path3.resolve)(opts.directory);
   const remote = opts.remote ?? "publisher";
   const empty2 = await isEmptyDir(target);
   if (empty2 === false) throw new PublisherError("LOCAL_STATE", `${target} exists and is not empty; checkout never overlays an existing folder`);
   await (0, import_promises4.mkdir)((0, import_node_path3.dirname)(target), { recursive: true });
   const removed = await removeStalePartials(target, opts.repoId);
-  if (removed.length) call.onProgress?.({ phase: "checkout", message: `removed ${removed.length} interrupted checkout(s)` });
-  const repo = await client.getRepository(opts.repoId, call);
+  if (removed.length) call2.onProgress?.({ phase: "checkout", message: `removed ${removed.length} interrupted checkout(s)` });
+  const repo = await client.getRepository(opts.repoId, call2);
   const branch = opts.branch ?? repo.head.symbolic.replace(/^refs\/heads\//, "");
   const tip = repo.refs[`refs/heads/${branch}`] ?? null;
   if (!tip && Object.keys(repo.refs).length > 0) throw new PublisherError("LOCAL_STATE", `branch ${branch} does not exist on the server`);
@@ -4083,7 +4089,7 @@ async function checkoutWorkspace(client, opts, call = {}, now = /* @__PURE__ */
     await runGit(["init", "-q", `--initial-branch=${branch}`, partial2]);
     await writeAssociation(partial2, { endpoint: client.endpoint, repoId: opts.repoId, remote });
     if (tip) {
-      await client.fetch({ repoDir: partial2, repoId: opts.repoId, remote }, call);
+      await client.fetch({ repoDir: partial2, repoId: opts.repoId, remote }, call2);
       const tracking = `refs/remotes/${remote}/${branch}`;
       const have = await revParse(partial2, tracking);
       if (have !== tip) throw new PublisherError("LOCAL_STATE", `fetched ${tracking} is ${have ?? "missing"}, expected ${tip}; retry the checkout`);
@@ -4121,7 +4127,7 @@ async function countCommits(dir, range) {
   const r = await runGit(["rev-list", "--count", range], { cwd: dir, allowFailure: true });
   return r.code === 0 ? Number(r.stdout.toString("utf8").trim()) : 0;
 }
-async function inspectWorkspace(client, directory, call = {}) {
+async function inspectWorkspace(client, directory, call2 = {}) {
   const dir = (0, import_node_path3.resolve)(directory);
   const mapping = await getWorkspaceMapping(dir);
   const pending = await listPending(dir).catch(() => []);
@@ -4144,7 +4150,7 @@ async function inspectWorkspace(client, directory, call = {}) {
   const hasLocalWork = dirty || untrackedPaths.length > 0;
   const checkedOut = (await currentBranch(dir))?.replace(/^refs\/heads\//, "") ?? null;
   const local = { branch: checkedOut, tip, head, dirty, untracked: untrackedPaths.length, untrackedPaths: untrackedPaths.slice(0, 10), commitsAheadOfBase: 0 };
-  const repo = await client.getRepository(mapping.repoId, call);
+  const repo = await client.getRepository(mapping.repoId, call2);
   const remoteOid = repo.refs[branchRef] ?? null;
   const remote = { oid: remoteOid, generation: repo.generation };
   if (mapping.baseOid && tip) local.commitsAheadOfBase = await countCommits(dir, `${mapping.baseOid}..${tip}`);
@@ -4162,7 +4168,7 @@ async function inspectWorkspace(client, directory, call = {}) {
   }
   if (!tip) return done("remote_ahead", hasLocalWork ? `local branch is unborn and there are ${work}; move them aside, then sync` : "local branch is unborn; sync to fast-forward");
   if (!await objectExists(dir, remoteOid)) {
-    await client.fetch({ repoDir: dir, repoId: mapping.repoId, remote: mapping.remote }, call);
+    await client.fetch({ repoDir: dir, repoId: mapping.repoId, remote: mapping.remote }, call2);
     if (!await objectExists(dir, remoteOid)) return done("remote_ahead", "server tip could not be fetched; retry");
   }
   if (remoteOid === tip)
@@ -4189,10 +4195,10 @@ async function inspectWorkspace(client, directory, call = {}) {
     merge2.conflicts.map((c) => c.path)
   );
 }
-async function syncWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new Date()) {
+async function syncWorkspace(client, opts, call2 = {}, now = /* @__PURE__ */ new Date()) {
   const dir = (0, import_node_path3.resolve)(opts.directory);
-  await adoptWorkspace(client, dir, call, now);
-  const before = await inspectWorkspace(client, dir, call);
+  await adoptWorkspace(client, dir, call2, now);
+  const before = await inspectWorkspace(client, dir, call2);
   if (!before.mapping) throw new PublisherError("LOCAL_STATE", "not a workspace; run checkout");
   const mapping = before.mapping;
   const branchRef = `refs/heads/${mapping.branch}`;
@@ -4216,7 +4222,7 @@ async function syncWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new
       updated = await advanceWorkspaceBase(dir, { oid: before.remote.oid, generation: before.remote.generation }, now);
     }
   }
-  const after = applied ? (await inspectWorkspace(client, dir, call)).state : before.state;
+  const after = applied ? (await inspectWorkspace(client, dir, call2)).state : before.state;
   return { before, applied, mapping: updated, after };
 }
 
@@ -4668,6 +4674,7 @@ async function followRun(input, opts) {
           seen.set(entry.stage, entry.state);
           opts.onStage?.(entry);
         }
+        if (isRecord(run.run) && run.run["status"] === "awaiting-approval") return { kind: "waiting", stages: read.stages };
         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 };
       }
@@ -4729,6 +4736,87 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// ../client/src/preparation.ts
+var PREPARATION = "preparation";
+var STATUSES = ["queued", "running", "needs-choice", "ready", "blocked", "cancelled"];
+function readPreparation(input, opts) {
+  return call(input, opts, void 0);
+}
+function answerPreparation(input, opts) {
+  return call(input, opts, { id: input.id, revision: input.revision, action: "answers", answers: input.answers });
+}
+async function call(input, opts, body) {
+  const fetchImpl = opts.fetch ?? fetch;
+  const url2 = `${input.portal.replace(/\/+$/, "")}/api/v1/terminal/repositories/${encodeURIComponent(input.repoId)}/preparation`;
+  let refreshed = false;
+  for (; ; ) {
+    const answer = await ask2(fetchImpl, url2, await opts.token(), body);
+    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 === 403) return { kind: "forbidden" };
+    if (answer.status === 409) return { kind: "moved-on" };
+    if (answer.status === 404) {
+      const code = isRecord2(answer.body) ? answer.body["error"] : void 0;
+      return code === "no-such-application" ? { kind: "no-application" } : { kind: "unavailable", detail: "the portal does not serve this address" };
+    }
+    if (answer.status === 200) {
+      const view = readView(answer.body);
+      return "detail" in view ? { kind: "malformed", detail: view.detail } : { kind: "view", view };
+    }
+    return { kind: "unavailable", detail: answer.status === 0 ? "the portal could not be reached" : `the portal answered ${answer.status}` };
+  }
+}
+function readView(body) {
+  if (!isRecord2(body)) return { detail: "an answer that is not a preparation" };
+  const { id, revision, status, message, questions, publication } = body;
+  if (typeof id !== "string" || id === "") return { detail: "a preparation with no id" };
+  if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 1) return { detail: "a preparation with no revision" };
+  if (!STATUSES.includes(status)) return { detail: "a preparation with an unknown status" };
+  if (typeof message !== "string") return { detail: "a preparation with no message" };
+  if (!Array.isArray(questions)) return { detail: "a preparation with no list of questions" };
+  const read = [];
+  for (const q of questions) {
+    if (!isRecord2(q) || typeof q["id"] !== "string" || typeof q["text"] !== "string" || !Array.isArray(q["options"]) || q["options"].length === 0) {
+      return { detail: "a question that cannot be answered" };
+    }
+    const options = [];
+    for (const o of q["options"]) {
+      if (!isRecord2(o) || typeof o["value"] !== "string" || typeof o["label"] !== "string") return { detail: "a question with an unreadable option" };
+      options.push({ value: o["value"], label: o["label"] });
+    }
+    read.push({ id: q["id"], text: q["text"], options });
+  }
+  let pub = null;
+  if (isRecord2(publication) && typeof publication["status"] === "string" && typeof publication["message"] === "string") {
+    pub = { status: publication["status"], message: publication["message"], ...typeof publication["url"] === "string" ? { url: publication["url"] } : {} };
+  }
+  return { id, revision, status, message, questions: read, publication: pub };
+}
+async function ask2(fetchImpl, url2, token, body) {
+  try {
+    const res = await fetchImpl(url2, {
+      method: body === void 0 ? "GET" : "POST",
+      headers: { authorization: `Bearer ${token}`, accept: "application/json", ...body === void 0 ? {} : { "content-type": "application/json" } },
+      ...body === void 0 ? {} : { body: JSON.stringify(body) },
+      signal: AbortSignal.timeout(3e4)
+    });
+    const text = await res.text();
+    try {
+      return { status: res.status, body: text ? JSON.parse(text) : null };
+    } catch {
+      return { status: res.status, body: void 0 };
+    }
+  } catch {
+    return { status: 0, body: null };
+  }
+}
+function isRecord2(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");
@@ -4968,13 +5056,13 @@ async function uploadPack(fetchImpl, upload, packPath, size, opts) {
 }
 
 // ../client/src/publish.ts
-async function publish(ctx, repoId, remote, opts, call) {
-  const progress = call.onProgress ?? (() => void 0);
+async function publish(ctx, repoId, remote, opts, call2) {
+  const progress = call2.onProgress ?? (() => void 0);
   const { repoDir } = opts;
   const store2 = await openPending(repoDir);
   const pendings = await store2.list();
   progress({ phase: "resolve", message: "reading repository state" });
-  const repo = await ctx.getRepository(repoId, call);
+  const repo = await ctx.getRepository(repoId, call2);
   const specs = opts.updates ?? [await defaultUpdate(repoDir)];
   let refUpdates = [];
   let nothingNew = null;
@@ -4990,9 +5078,9 @@ async function publish(ctx, repoId, remote, opts, call) {
     const sameIntent = !nothingNew && pending2.baseGeneration === repo.generation && canonicalJson(refUpdates) === canonicalJson(pending2.refUpdates);
     if (sameIntent && (pending2.pack === null || await packFileUsable(pending2))) {
       progress({ phase: "resolve", message: `resuming publication ${pending2.publicationId}` });
-      return runPublication(ctx, repoId, remote, repoDir, store2, pending2, opts, call, true);
+      return runPublication(ctx, repoId, remote, repoDir, store2, pending2, opts, call2, true);
     }
-    const outcome = await resolvePending(ctx, repoDir, remote, pending2, call, store2);
+    const outcome = await resolvePending(ctx, repoDir, remote, pending2, call2, store2);
     if (outcome.state === "finalizing" || outcome.state === "unknown") {
       throw new PublisherError("OUTCOME_UNKNOWN", `publication ${pending2.publicationId} is still being processed; run status before publishing again`, {
         retryable: true,
@@ -5000,7 +5088,7 @@ async function publish(ctx, repoId, remote, opts, call) {
       });
     }
     if (outcome.state === "accepted") {
-      const fresh = await ctx.getRepository(repoId, call);
+      const fresh = await ctx.getRepository(repoId, call2);
       let remaining = [];
       try {
         remaining = await resolveUpdates(repoDir, fresh, specs);
@@ -5008,7 +5096,7 @@ async function publish(ctx, repoId, remote, opts, call) {
         if (!(e instanceof PublisherError && e.code === "LOCAL_STATE")) throw e;
       }
       if (remaining.length === 0) return toOutcome(outcome, true, pending2.refUpdates);
-      return publish(ctx, repoId, remote, opts, call);
+      return publish(ctx, repoId, remote, opts, call2);
     }
   }
   if (nothingNew) throw nothingNew;
@@ -5022,7 +5110,7 @@ async function publish(ctx, repoId, remote, opts, call) {
     const exclude = [];
     for (const info of await batchCheck(repoDir, remoteOids)) if (info.type !== "missing") exclude.push(info.oid);
     const outPath = store2.packPath(publicationId);
-    const built = await buildPack(repoDir, { include: wants, exclude, outPath, ...call.signal ? { signal: call.signal } : {} });
+    const built = await buildPack(repoDir, { include: wants, exclude, outPath, ...call2.signal ? { signal: call2.signal } : {} });
     pack = { sha256: built.sha256, size: built.size, path: outPath };
     progress({ phase: "pack", message: `packed ${built.objectCount} objects (${built.size} bytes)`, bytes: built.size, total: built.size });
   }
@@ -5038,7 +5126,7 @@ async function publish(ctx, repoId, remote, opts, call) {
     finalized: false
   };
   await store2.write(pending);
-  return runPublication(ctx, repoId, remote, repoDir, store2, pending, opts, call, false);
+  return runPublication(ctx, repoId, remote, repoDir, store2, pending, opts, call2, false);
 }
 async function packFileUsable(p) {
   if (!p.pack) return true;
@@ -5049,9 +5137,9 @@ async function packFileUsable(p) {
     return false;
   }
 }
-async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opts, call, resumed) {
+async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opts, call2, resumed) {
   try {
-    return await sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts, call, resumed);
+    return await sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts, call2, resumed);
   } catch (e) {
     throw unconfirmed(e, pending.publicationId);
   }
@@ -5066,8 +5154,8 @@ function unconfirmed(e, publicationId) {
     details: { publicationId, cause: e.code }
   });
 }
-async function sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts, call, resumed) {
-  const progress = call.onProgress ?? (() => void 0);
+async function sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts, call2, resumed) {
+  const progress = call2.onProgress ?? (() => void 0);
   const beginBody = {
     publicationId: pending.publicationId,
     baseGeneration: pending.baseGeneration,
@@ -5078,32 +5166,32 @@ async function sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts,
   let summary = null;
   if (!pending.finalized) {
     progress({ phase: "begin", message: "starting publication" });
-    let begin = (await ctx.transport.request("POST", `/v1/repos/${repoId}/publications`, beginBody, call)).body;
+    let begin = (await ctx.transport.request("POST", `/v1/repos/${repoId}/publications`, beginBody, call2)).body;
     summary = begin.publication;
     if (begin.publication.state === "created") {
       if (begin.upload && pending.pack) {
         progress({ phase: "upload", message: "uploading pack", bytes: 0, total: pending.pack.size });
-        let result = await uploadPack(ctx.fetchImpl, begin.upload, pending.pack.path, pending.pack.size, call);
+        let result = await uploadPack(ctx.fetchImpl, begin.upload, pending.pack.path, pending.pack.size, call2);
         if (result === "expired") {
-          begin = (await ctx.transport.request("POST", `/v1/repos/${repoId}/publications`, beginBody, call)).body;
+          begin = (await ctx.transport.request("POST", `/v1/repos/${repoId}/publications`, beginBody, call2)).body;
           if (!begin.upload) throw new PublisherError("UPLOAD_MISSING", "server did not return fresh upload instructions");
-          result = await uploadPack(ctx.fetchImpl, begin.upload, pending.pack.path, pending.pack.size, call);
+          result = await uploadPack(ctx.fetchImpl, begin.upload, pending.pack.path, pending.pack.size, call2);
           if (result === "expired") throw new PublisherError("NETWORK", "upload authorization expired twice", { retryable: true });
         }
       }
       progress({ phase: "finalize", message: "finalizing" });
-      const fin = await ctx.transport.request("POST", `/v1/repos/${repoId}/publications/${pending.publicationId}/finalize`, {}, call);
+      const fin = await ctx.transport.request("POST", `/v1/repos/${repoId}/publications/${pending.publicationId}/finalize`, {}, call2);
       summary = fin.body.publication;
     }
     pending.finalized = true;
     await store2.write(pending);
   }
   if (opts.wait === false) {
-    summary = summary ?? await ctx.getStatus(repoId, pending.publicationId, call);
+    summary = summary ?? await ctx.getStatus(repoId, pending.publicationId, call2);
     return toOutcome(summary, resumed, pending.refUpdates);
   }
   progress({ phase: "validate", message: "waiting for validation" });
-  summary = await waitForOutcome(ctx, repoId, pending.publicationId, opts.waitTimeoutMs ?? 10 * 6e4, call);
+  summary = await waitForOutcome(ctx, repoId, pending.publicationId, opts.waitTimeoutMs ?? 10 * 6e4, call2);
   if (summary.state === "accepted") {
     await applyTrackingRefs(repoDir, remote, pending.refUpdates);
     await store2.remove(pending.publicationId);
@@ -5114,23 +5202,23 @@ async function sendAndWait(ctx, repoId, remote, repoDir, store2, pending, opts,
   }
   return toOutcome(summary, resumed, pending.refUpdates);
 }
-async function waitForOutcome(ctx, repoId, publicationId, timeoutMs, call) {
+async function waitForOutcome(ctx, repoId, publicationId, timeoutMs, call2) {
   const deadline = Date.now() + timeoutMs;
   let delay2 = 500;
   for (; ; ) {
-    const s = await ctx.getStatus(repoId, publicationId, { ...call, waitSeconds: MAX_WAIT_SECONDS });
+    const s = await ctx.getStatus(repoId, publicationId, { ...call2, waitSeconds: MAX_WAIT_SECONDS });
     if (s.state === "accepted" || s.state === "rejected") return s;
     if (Date.now() > deadline) {
       throw new PublisherError("OUTCOME_UNKNOWN", `publication ${publicationId} has not completed yet; run status later`, { retryable: true, details: { publicationId } });
     }
-    await sleep(delay2, call.signal);
+    await sleep(delay2, call2.signal);
     delay2 = Math.min(delay2 * 2, 5e3);
   }
 }
-async function resolvePending(ctx, repoDir, remote, pending, call, store2) {
+async function resolvePending(ctx, repoDir, remote, pending, call2, store2) {
   let summary;
   try {
-    summary = await ctx.getStatus(pending.repoId, pending.publicationId, call);
+    summary = await ctx.getStatus(pending.repoId, pending.publicationId, call2);
   } catch (e) {
     if (e instanceof PublisherError && e.code === "PUBLICATION_NOT_FOUND") {
       await store2.remove(pending.publicationId);
@@ -5240,13 +5328,13 @@ async function writeManifest(gd, installed) {
   await (0, import_promises8.mkdir)((0, import_node_path6.join)(gd, "publisher"), { recursive: true });
   await (0, import_promises8.writeFile)((0, import_node_path6.join)(gd, "publisher", "installed.json"), JSON.stringify(installed));
 }
-async function fetchRepository(ctx, repoId, opts, call) {
+async function fetchRepository(ctx, repoId, opts, call2) {
   const remote = opts.remote ?? "publisher";
-  const progress = call.onProgress ?? (() => void 0);
+  const progress = call2.onProgress ?? (() => void 0);
   progress({ phase: "fetch", message: "describing repository" });
   const [, { body }, gd] = await Promise.all([
     ensureRemote(opts.repoDir, remote, `${ctx.transport.endpoint}/v1/repos/${repoId}`),
-    ctx.transport.request("GET", `/v1/repos/${repoId}/bundle`, void 0, call),
+    ctx.transport.request("GET", `/v1/repos/${repoId}/bundle`, void 0, call2),
     gitDir(opts.repoDir)
   ]);
   const artifacts = [...body.base ? [{ kind: "bundle", ...body.base }] : [], ...body.packs.map((p) => ({ kind: "pack", ...p }))];
@@ -5257,14 +5345,14 @@ async function fetchRepository(ctx, repoId, opts, call) {
       ctx,
       gd,
       artifacts.filter((a) => !installed.has(a.sha256)),
-      call
+      call2
     );
     if (!await haveAll(opts.repoDir, body.refs)) {
       bytes += await install(
         ctx,
         gd,
         artifacts.filter((a) => installed.has(a.sha256)),
-        call
+        call2
       );
       if (!await haveAll(opts.repoDir, body.refs)) throw new PublisherError("NETWORK", "the downloaded artifacts do not contain every advertised ref", { retryable: true });
     }
@@ -5282,16 +5370,16 @@ async function haveAll(repoDir, refs) {
   if (oids.size === 0) return true;
   return (await batchCheck(repoDir, oids)).every((o) => o.type !== "missing");
 }
-async function install(ctx, gd, artifacts, call) {
+async function install(ctx, gd, artifacts, call2) {
   if (artifacts.length === 0) return 0;
-  const progress = call.onProgress ?? (() => void 0);
+  const progress = call2.onProgress ?? (() => void 0);
   const tmp = await (0, import_promises8.mkdtemp)((0, import_node_path6.join)((0, import_node_os3.tmpdir)(), "gitpub-fetch-"));
   let bytes = 0;
   const total = artifacts.reduce((sum, a) => sum + a.size, 0);
   try {
     for (const a of artifacts) {
       const file = (0, import_node_path6.join)(tmp, `${a.sha256}.${a.kind}`);
-      bytes += await download(ctx.fetchImpl, a.url, file, a.sha256, a.size, call);
+      bytes += await download(ctx.fetchImpl, a.url, file, a.sha256, a.size, call2);
       progress({ phase: "fetch", message: `installing ${a.kind}`, bytes, total });
       if (a.kind === "bundle") {
         await bundleUnbundleObjects(gd, file);
@@ -5322,10 +5410,10 @@ async function updateRefs(repoDir, remote, refs) {
   await refTransaction(repoDir, updates);
   return tracking;
 }
-async function download(fetchImpl, url2, dest, sha256, size, call) {
+async function download(fetchImpl, url2, dest, sha256, size, call2) {
   let res;
   try {
-    res = await fetchImpl(url2, call.signal ? { signal: call.signal } : {});
+    res = await fetchImpl(url2, call2.signal ? { signal: call2.signal } : {});
   } catch (e) {
     throw new PublisherError("NETWORK", `download failed: ${e.message}`, { retryable: true, cause: e });
   }
@@ -5336,7 +5424,7 @@ async function download(fetchImpl, url2, dest, sha256, size, call) {
     transform(chunk, controller) {
       n += chunk.byteLength;
       hash.update(chunk);
-      call.onProgress?.({ phase: "fetch", message: "downloading", bytes: n, total: size });
+      call2.onProgress?.({ phase: "fetch", message: "downloading", bytes: n, total: size });
       controller.enqueue(chunk);
     }
   });
@@ -5392,11 +5480,29 @@ var Publisher = class {
       fetch: this.fetchImpl
     });
   }
-  async getCapabilities(call = {}) {
-    const r = await this.transport.request("GET", "/v1/capabilities", void 0, call);
+  /**
+   * The question the repository's current preparation waits on, and its answer, at the portal that
+   * serves this endpoint — with this publisher's credential and its one refresh, as `followRun`.
+   * The caller confirms the portal's `/config` lists `PREPARATION` first.
+   */
+  async readPreparation(input) {
+    return readPreparation(input, this.portalCall());
+  }
+  async answerPreparation(input) {
+    return answerPreparation(input, this.portalCall());
+  }
+  portalCall() {
+    return {
+      token: this.tokenFn,
+      refresh: async () => !this.opts.token && refreshStoredCredential(this.endpoint, { fetch: this.fetchImpl }),
+      fetch: this.fetchImpl
+    };
+  }
+  async getCapabilities(call2 = {}) {
+    const r = await this.transport.request("GET", "/v1/capabilities", void 0, call2);
     return r.body;
   }
-  async createRepository(options = {}, call = {}) {
+  async createRepository(options = {}, call2 = {}) {
     const body = {
       creationId: options.creationId ?? newCreationId(),
       name: options.name ?? "",
@@ -5404,29 +5510,29 @@ var Publisher = class {
       objectFormat: "sha1",
       grants: options.grants ?? []
     };
-    const r = await this.transport.request("POST", "/v1/repos", body, call);
+    const r = await this.transport.request("POST", "/v1/repos", body, call2);
     return r.body.repository;
   }
-  async getRepository(repoId, call = {}) {
-    const r = await this.transport.request("GET", `/v1/repos/${encodeURIComponent(repoId)}`, void 0, call);
+  async getRepository(repoId, call2 = {}) {
+    const r = await this.transport.request("GET", `/v1/repos/${encodeURIComponent(repoId)}`, void 0, call2);
     return r.body.repository;
   }
   /** One page of the repositories the caller created (ADR-0011). An authenticated route, unlike capabilities. */
-  async listRepositories(options = {}, call = {}) {
+  async listRepositories(options = {}, call2 = {}) {
     const q = new URLSearchParams();
     if (options.state) q.set("state", options.state);
     if (options.limit !== void 0) q.set("limit", String(options.limit));
     if (options.cursor) q.set("cursor", options.cursor);
     const qs = q.toString() ? `?${q.toString()}` : "";
-    return (await this.transport.request("GET", `/v1/repos${qs}`, void 0, call)).body;
+    return (await this.transport.request("GET", `/v1/repos${qs}`, void 0, call2)).body;
   }
-  async getPublicationStatus(repoId, publicationId, call = {}) {
-    const q = call.waitSeconds ? `?wait=${Math.min(call.waitSeconds, MAX_WAIT_SECONDS)}` : "";
+  async getPublicationStatus(repoId, publicationId, call2 = {}) {
+    const q = call2.waitSeconds ? `?wait=${Math.min(call2.waitSeconds, MAX_WAIT_SECONDS)}` : "";
     const r = await this.transport.request(
       "GET",
       `/v1/repos/${encodeURIComponent(repoId)}/publications/${encodeURIComponent(publicationId)}${q}`,
       void 0,
-      call
+      call2
     );
     return r.body.publication;
   }
@@ -5453,32 +5559,32 @@ var Publisher = class {
     return { repoId: a.repoId, remote: a.remote };
   }
   /** Publish existing local commits. Never modifies the worktree; safe to retry and resume. */
-  async publish(options, call = {}) {
+  async publish(options, call2 = {}) {
     const { repoId, remote } = await this.resolveRepo(options.repoDir, options.repoId);
-    const outcome = await publish(this.publishContext(), repoId, remote, options, call);
+    const outcome = await publish(this.publishContext(), repoId, remote, options, call2);
     await noteAcceptedPublication(options.repoDir, outcome);
     return outcome;
   }
   // ---- workspaces (docs/workspace-parity.md) ------------------------------------------------
   /** Create a NEW editable workspace (clone + mapping) for a published repository. */
-  async checkout(options, call = {}) {
-    return checkoutWorkspace(this, options, call);
+  async checkout(options, call2 = {}) {
+    return checkoutWorkspace(this, options, call2);
   }
   /** Make an associated folder a workspace (idempotent); `init` and `sync` both call it. */
-  async adoptWorkspace(directory, call = {}) {
-    return adoptWorkspace(this, directory, call);
+  async adoptWorkspace(directory, call2 = {}) {
+    return adoptWorkspace(this, directory, call2);
   }
   /** Offline: the persisted workspace mapping, or null. */
   async workspace(directory) {
     return getWorkspaceMapping(directory);
   }
   /** Where the workspace stands relative to the server (decided on real objects). */
-  async workspaceStatus(directory, call = {}) {
-    return inspectWorkspace(this, directory, call);
+  async workspaceStatus(directory, call2 = {}) {
+    return inspectWorkspace(this, directory, call2);
   }
   /** Fetch and, with `apply`, fast-forward or merge cleanly; advances the base. */
-  async sync(options, call = {}) {
-    return syncWorkspace(this, options, call);
+  async sync(options, call2 = {}) {
+    return syncWorkspace(this, options, call2);
   }
   /**
    * A creator's whole round trip in one call, so nobody runs git: record their changes, bring in
@@ -5490,7 +5596,7 @@ var Publisher = class {
    * a commit and then an error. `syncWorkspace` itself still never commits or publishes; this is
    * the composition, and the only one.
    */
-  async syncChanges(options, call = {}) {
+  async syncChanges(options, call2 = {}) {
     const dir = options.directory;
     await this.resolveRepo(dir);
     const branch = (await currentBranch(dir))?.replace(/^refs\/heads\//, "") ?? null;
@@ -5499,7 +5605,7 @@ var Publisher = class {
     if (mapped && mapped.branch !== branch)
       throw new PublisherError("LOCAL_STATE", `branch ${branch} is checked out, but this folder publishes ${mapped.branch}; check it out, then run sync again`);
     const recorded = await recordChanges({ dir, ...options.message ? { message: options.message } : {} });
-    const reconciled = await syncWorkspace(this, { directory: dir, apply: true }, call);
+    const reconciled = await syncWorkspace(this, { directory: dir, apply: true }, call2);
     const base = { recorded: { commit: recorded.commit, committed: recorded.committed, excluded: recorded.excluded }, reconciled };
     if (reconciled.after === "conflict") {
       const remote = reconciled.before.remote?.oid ?? null;
@@ -5508,25 +5614,25 @@ var Publisher = class {
     }
     const tip = await revParse(dir, `refs/heads/${branch}`);
     if (tip === null || tip === (reconciled.before.remote?.oid ?? null)) return { ...base, state: "up_to_date", published: null, marked: false };
-    const published = await this.publish({ repoDir: dir }, call);
+    const published = await this.publish({ repoDir: dir }, call2);
     return { ...base, state: published.state === "accepted" ? "published" : published.state === "rejected" ? "rejected" : "unknown", published, marked: false };
   }
   /** Resolve interrupted publications recorded locally without creating duplicates. */
-  async resumePublications(repoDir, call = {}) {
+  async resumePublications(repoDir, call2 = {}) {
     const { remote } = await this.resolveRepo(repoDir);
     const out = [];
     const store2 = await openPending(repoDir);
     for (const p of await store2.list()) {
       if (p.endpoint !== this.endpoint) continue;
       if (!p.finalized) {
-        out.push(await publish(this.publishContext(), p.repoId, remote, { repoDir, publicationId: p.publicationId }, call).catch((e) => rethrowUnlessResolvable(e, p)));
+        out.push(await publish(this.publishContext(), p.repoId, remote, { repoDir, publicationId: p.publicationId }, call2).catch((e) => rethrowUnlessResolvable(e, p)));
         continue;
       }
-      const deadline = Date.now() + (call.waitTimeoutMs ?? 5 * 6e4);
-      let s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call, waitSeconds: MAX_WAIT_SECONDS }, store2);
+      const deadline = Date.now() + (call2.waitTimeoutMs ?? 5 * 6e4);
+      let s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call2, waitSeconds: MAX_WAIT_SECONDS }, store2);
       while (s.state === "finalizing" && Date.now() < deadline) {
-        call.onProgress?.({ phase: "validate", message: `waiting for ${p.publicationId}` });
-        s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call, waitSeconds: MAX_WAIT_SECONDS }, store2);
+        call2.onProgress?.({ phase: "validate", message: `waiting for ${p.publicationId}` });
+        s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call2, waitSeconds: MAX_WAIT_SECONDS }, store2);
       }
       out.push(toOutcome(s, true, p.refUpdates));
     }
@@ -5541,17 +5647,17 @@ var Publisher = class {
    * branches. Every read is a presigned download of the repository's bundle and packs (ADR-0013);
    * artifacts already installed are not downloaded again.
    */
-  async fetch(options, call = {}) {
+  async fetch(options, call2 = {}) {
     const { repoId } = await this.resolveRepo(options.repoDir, options.repoId);
-    return fetchRepository({ transport: this.transport, fetchImpl: this.fetchImpl }, repoId, options, call);
+    return fetchRepository({ transport: this.transport, fetchImpl: this.fetchImpl }, repoId, options, call2);
   }
   publishContext() {
     return {
       transport: this.transport,
       fetchImpl: this.fetchImpl,
       clientInfo: this.clientInfo,
-      getRepository: (repoId, call) => this.getRepository(repoId, call),
-      getStatus: (repoId, publicationId, call) => this.getPublicationStatus(repoId, publicationId, call)
+      getRepository: (repoId, call2) => this.getRepository(repoId, call2),
+      getStatus: (repoId, publicationId, call2) => this.getPublicationStatus(repoId, publicationId, call2)
     };
   }
 };
@@ -5717,7 +5823,7 @@ function resolveChoice(answer, names) {
   }
   return names.find((n) => n.toLowerCase() === a.toLowerCase()) ?? null;
 }
-async function ask2(question) {
+async function ask3(question) {
   const rl = (0, import_promises10.createInterface)({ input: process.stdin, output: process.stderr });
   try {
     return await rl.question(question);
@@ -5735,7 +5841,7 @@ ${purpose}
   names.forEach((n, i) => process.stderr.write(`  ${i + 1}) ${n}
 `));
   for (let attempt = 0; attempt < 3; attempt++) {
-    const answer = await ask2(`
+    const answer = await ask3(`
 Which one? [1-${names.length}, or a name] `);
     if (answer === null) return null;
     const chosen = resolveChoice(answer, names);
@@ -5751,7 +5857,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 ask2(suggested ? `
+    const answer = await ask3(suggested ? `
 Profile name [${suggested}]: ` : `
 Profile name: `);
     if (answer === null) return null;
@@ -5874,8 +5980,9 @@ async function followPublication(p, endpoint, o, opts) {
     { 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 } };
+  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;
@@ -5888,8 +5995,10 @@ function stageLine(e, json) {
 function inPortal(portal, lead, verb) {
   return `${lead} ${verb} in the portal${portal === null ? "" : `: ${portal}`}.`;
 }
-function progressHint(r, 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":
@@ -5915,6 +6024,78 @@ function progressHint(r, portal) {
   }
 }
 
+// src/question.ts
+async function questionAt(p, endpoint, repoId, opts = {}) {
+  const at = await portalAt(endpoint, opts);
+  if ("reason" in at) return at;
+  return shown(at.portal, await p.readPreparation({ portal: at.portal, repoId }));
+}
+async function answerAt(p, endpoint, repoId, specs, opts = {}) {
+  const answers = parseSpecs(specs);
+  const at = await portalAt(endpoint, opts);
+  if ("reason" in at) return at;
+  const read = shown(at.portal, await p.readPreparation({ portal: at.portal, repoId }));
+  if (read.kind !== "view") return read;
+  if (read.questions.length === 0) throw new PublisherError("LOCAL_STATE", `nothing is waiting for an answer (the preparation is ${read.preparation.status})`);
+  for (const [id, value] of Object.entries(answers)) {
+    const question = read.questions.find((q) => q.id === id);
+    if (question === void 0) {
+      throw new PublisherError("INVALID_REQUEST", `no pending question "${id}"; pending: ${read.questions.map((q) => q.id).join(", ")}`, {
+        details: { questions: read.questions }
+      });
+    }
+    const values = question.options.map((o) => o.value);
+    if (!values.includes(value)) {
+      throw new PublisherError("INVALID_REQUEST", `"${value}" is not one of ${values.join(", ")} for "${id}"`, { details: { questions: read.questions } });
+    }
+  }
+  return shown(at.portal, await p.answerPreparation({ portal: at.portal, repoId, id: read.preparation.id, revision: read.preparation.revision, answers }));
+}
+function parseSpecs(specs) {
+  if (specs.length === 0) throw new PublisherError("INVALID_REQUEST", "answer takes one or more question=value");
+  const answers = {};
+  for (const spec of specs) {
+    const at = spec.indexOf("=");
+    if (at <= 0 || at === spec.length - 1) throw new PublisherError("INVALID_REQUEST", `"${spec}" is not question=value`);
+    answers[spec.slice(0, at)] = spec.slice(at + 1);
+  }
+  return answers;
+}
+async function portalAt(endpoint, opts) {
+  const derived = portalForEndpoint(endpoint);
+  const confirmed = derived === null ? null : await confirmPortal(derived, endpoint, opts.fetch);
+  if (derived === null || confirmed === null) return { kind: "unavailable", reason: "no-portal", portal: null, hint: "Answer it in the portal." };
+  if (!confirmed.terminal.includes(PREPARATION)) {
+    return { kind: "unavailable", reason: "no-route", portal: derived, hint: `This portal cannot show the question in the terminal yet. Answer it in the portal: ${derived}.` };
+  }
+  return { portal: derived };
+}
+function shown(portal, r) {
+  switch (r.kind) {
+    case "view": {
+      const { questions, ...preparation } = r.view;
+      return { kind: "view", portal, preparation, questions, hint: hintFor(r.view) };
+    }
+    case "no-application":
+      throw new PublisherError("NOT_FOUND", "this repository has no application in your organisation yet; publish it first");
+    case "moved-on":
+      throw new PublisherError("UNAVAILABLE", "the preparation moved on before the answer arrived; run publisher question again", { retryable: true });
+    case "unauthorized":
+      throw new PublisherError("UNAUTHORIZED", "the portal did not accept this sign-in; run publisher login");
+    case "forbidden":
+      throw new PublisherError("FORBIDDEN", "the portal will not let this sign-in answer for this organisation (an owner or admin can)");
+    case "unavailable":
+      throw new PublisherError("UNAVAILABLE", `the portal could not be asked: ${r.detail}`, { retryable: true });
+    case "malformed":
+      throw new PublisherError("UNAVAILABLE", `the portal's answer could not be read: ${r.detail}`);
+  }
+}
+function hintFor(view) {
+  if (view.questions.length === 0) return "Nothing is waiting for an answer.";
+  const how = view.questions.map((q) => `${q.id}=<${q.options.map((o) => o.value).join("|")}>`).join(" ");
+  return `It is waiting for your answer. Run: publisher answer ${how}`;
+}
+
 // src/main.ts
 var USAGE = `publisher \u2014 publish an app's Git history to the serverless Git backend
 
@@ -5951,6 +6132,10 @@ Usage:
                                                         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 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
+                                                        the question's options is refused before anything is sent
   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)
@@ -6322,6 +6507,27 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       out({ publicationId, progress: await followPublication(p, endpoint, publication, { onStage: emitStage, log, timeoutMs }) });
       return 0;
     }
+    /**
+     * The business question the app's current preparation waits on, from this folder's repository.
+     * Exit 0 whether or not one is pending: `questions` says which. An outage is exit 3, never "none".
+     */
+    case "question": {
+      const dir = dirArg(1);
+      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");
+      out({ repoId, ...await questionAt(p, endpoint, repoId) });
+      return 0;
+    }
+    /** Answer it, as `question=value` pairs, re-reading the preparation first. */
+    case "answer": {
+      const dir = (0, import_node_path8.resolve)(".");
+      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");
+      out({ repoId, ...await answerAt(p, endpoint, repoId, cmd.slice(1)) });
+      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.6.3",
+  "version": "0.7.0",
   "description": "publisher: publish an app's Git history to the serverless Git backend",
   "license": "Apache-2.0",
   "type": "module",