@minnovate/shadow-publisher 0.3.0 → 0.6.0

package/dist/publisher.cjs

@@ -28,7 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/main.ts
-var import_node_path7 = require("node:path");
+var import_node_path8 = require("node:path");
 
 // ../protocol/src/versions.ts
 var PROTOCOL_VERSION = 1;
@@ -44,6 +44,7 @@ var PUBLICATION_ID_RE = new RegExp(`^pub_${ULID_BODY}$`);
 var CREATION_ID_RE = new RegExp(`^${ULID_BODY}$`);
 var TRANSACTION_ID_RE = new RegExp(`^(pub|cmp)_${ULID_BODY}$`);
 var PRINCIPAL_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._@-]{0,127}$/;
+var ORG_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 var SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 function ulid(now = Date.now()) {
   let time3 = now;
@@ -92,6 +93,10 @@ var ERROR_CODES = [
   "UNAUTHORIZED",
   "FORBIDDEN",
   "REF_FORBIDDEN",
+  // The credential names no organisation, so there is nothing to publish a repository FOR. Its own
+  // code rather than FORBIDDEN: a caller can act on it (sign in again, choosing an organisation),
+  // and a test that could not tell it from "you may not" would prove nothing about the check.
+  "ORGANISATION_REQUIRED",
   // repositories
   "REPOSITORY_NOT_FOUND",
   "REPOSITORY_CONFLICT",
@@ -133,6 +138,7 @@ var HTTP_STATUS_FOR_CODE = {
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   REF_FORBIDDEN: 403,
+  ORGANISATION_REQUIRED: 403,
   REPOSITORY_NOT_FOUND: 404,
   REPOSITORY_CONFLICT: 409,
   REPOSITORY_ARCHIVED: 409,
@@ -2585,6 +2591,7 @@ var PublicationId = string2().check(_regex(PUBLICATION_ID_RE));
 var TransactionId = string2().check(_regex(TRANSACTION_ID_RE));
 var CreationId = string2().check(_regex(CREATION_ID_RE));
 var PrincipalId = string2().check(_regex(PRINCIPAL_ID_RE));
+var OrgId = string2().check(_regex(ORG_ID_RE));
 var Sha256Hex = string2().check(_regex(SHA256_HEX_RE));
 var Oid = string2().check(_regex(/^[0-9a-f]{40}$|^[0-9a-f]{64}$/));
 var IsoDate = iso_exports.datetime({ offset: true });
@@ -2666,7 +2673,19 @@ var MetaRecord = object({
   objectFormat: ObjectFormat,
   createdAt: IsoDate,
   createdBy: PrincipalId,
-  creationId: CreationId
+  creationId: CreationId,
+  /**
+   * The organisation that published this repository, and what `repoId` is derived from: "that
+   * organisation publishes a repository" is the product's sentence.
+   *
+   * `null` is what a record written BEFORE repositories were org-scoped reads as, and every such
+   * record is still readable, cloneable and publishable — `tests/compat/fixtures/schema-v1` is one,
+   * and the promise that it stays readable is why this field is not required. What `null` must
+   * never do is default: the worker refuses to ANNOUNCE a publication it cannot attribute
+   * (`packages/worker/src/publish.ts`), because a consumer that guessed would create an
+   * application in an organisation nobody chose. Every repository created since carries one.
+   */
+  org: _default(nullable(OrgId), null)
 });
 var GrantPattern = string2().check(
   _minLength(1),
@@ -3566,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);
@@ -3971,6 +3990,47 @@ 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()) {
+  const dir = (0, import_node_path3.resolve)(directory);
+  const existing = await getWorkspaceMapping(dir);
+  if (existing) return existing;
+  const section = await getConfigSection(dir, "publisher").catch(() => null);
+  const a = section ? associationFrom(section) : null;
+  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 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);
+    const haveRemote = await objectExists(dir, remoteOid);
+    if (!tip) {
+      baseOid = haveRemote ? remoteOid : null;
+      baseGeneration = haveRemote ? repo.generation : 0;
+    } else if (haveRemote && (remoteOid === tip || await isAncestor(dir, remoteOid, tip))) {
+      baseOid = remoteOid;
+      baseGeneration = repo.generation;
+    } else if (haveRemote) {
+      const r = await runGit(["merge-base", tip, remoteOid], { cwd: dir, allowFailure: true });
+      const shared = r.code === 0 ? r.stdout.toString("utf8").trim() : "";
+      baseOid = shared === "" ? null : shared;
+    }
+  }
+  await writeMapping(dir, {
+    endpoint: a.endpoint,
+    repoId: a.repoId,
+    remote: a.remote,
+    branch,
+    baseOid,
+    baseGeneration,
+    checkedOutAt: now.toISOString(),
+    baseAdvancedAt: now.toISOString()
+  });
+  return await getWorkspaceMapping(dir);
+}
 async function isEmptyDir(p) {
   try {
     return (await (0, import_promises4.readdir)(p)).length === 0;
@@ -4065,7 +4125,16 @@ async function inspectWorkspace(client, directory, call = {}) {
   const dir = (0, import_node_path3.resolve)(directory);
   const mapping = await getWorkspaceMapping(dir);
   const pending = await listPending(dir).catch(() => []);
-  if (!mapping) return { state: "unassociated", mapping: null, local: null, remote: null, pending, conflicts: [], hint: "not a workspace; run checkout" };
+  if (!mapping)
+    return {
+      state: "unassociated",
+      mapping: null,
+      local: null,
+      remote: null,
+      pending,
+      conflicts: [],
+      hint: "not a workspace yet; run sync here (an associated folder adopts itself), or checkout to create one"
+    };
   const branchRef = `refs/heads/${mapping.branch}`;
   const tip = await revParse(dir, branchRef);
   const head = await revParse(dir, "HEAD");
@@ -4088,27 +4157,31 @@ async function inspectWorkspace(client, directory, call = {}) {
     );
   }
   if (!remoteOid) {
-    if (!tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; commit, then publish` : "empty on both sides");
-    return done("local_changes", "the server has no such branch yet; publish to create it");
+    if (!tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; publisher sync records and publishes them` : "empty on both sides");
+    return done("local_changes", "the server has no such branch yet; publisher sync creates it");
   }
   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);
     if (!await objectExists(dir, remoteOid)) return done("remote_ahead", "server tip could not be fetched; retry");
   }
-  if (remoteOid === tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; commit, then publish` : "in sync with the server");
+  if (remoteOid === tip)
+    return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; publisher sync records and publishes them` : "in sync with the server");
   if (await isAncestor(dir, remoteOid, tip))
-    return done("local_changes", hasLocalWork ? `local commits and ${work}; commit, then publish` : "local commits not yet published; publish");
+    return done(
+      "local_changes",
+      hasLocalWork ? `local commits and ${work}; publisher sync records and publishes them` : "local commits not yet published; publisher sync publishes them"
+    );
   if (await isAncestor(dir, tip, remoteOid))
     return done(
       "remote_ahead",
-      hasLocalWork ? `server moved ahead and there are ${work}; commit or stash them, then sync to fast-forward` : "server moved ahead; sync to fast-forward"
+      hasLocalWork ? `server moved ahead and there are ${work}; publisher sync records them, brings the server's changes in and publishes` : "server moved ahead; publisher sync brings it in"
     );
   const merge2 = await mergeRemote({ repoDir: dir, ours: branchRef, theirs: remoteOid, apply: false });
   if (merge2.ok)
     return done(
       "diverged_clean_merge",
-      hasLocalWork ? `both sides changed, merge is clean; commit or stash the ${work}, then sync --apply` : "both sides changed, merge is clean; sync --apply, then publish"
+      hasLocalWork ? `both sides changed, merge is clean; publisher sync records the ${work}, merges and publishes` : "both sides changed, merge is clean; publisher sync merges and publishes"
     );
   return done(
     "conflict",
@@ -4118,6 +4191,7 @@ async function inspectWorkspace(client, directory, call = {}) {
 }
 async function syncWorkspace(client, opts, call = {}, 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);
   if (!before.mapping) throw new PublisherError("LOCAL_STATE", "not a workspace; run checkout");
   const mapping = before.mapping;
@@ -4125,7 +4199,7 @@ async function syncWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new
   let applied = null;
   if (before.state === "detached") throw new PublisherError("LOCAL_STATE", before.hint);
   if (opts.apply && before.remote?.oid && (before.state === "remote_ahead" || before.state === "diverged_clean_merge")) {
-    if (before.local?.dirty) throw new PublisherError("LOCAL_STATE", "the working tree has uncommitted changes; commit or stash them before sync --apply");
+    if (before.local?.dirty) throw new PublisherError("LOCAL_STATE", "the working tree has uncommitted changes; record them first (publisher sync does)");
     if (!before.local?.tip) {
       await runGit(["checkout", "-q", "-B", mapping.branch, before.remote.oid], { cwd: dir });
       applied = "fast-forward";
@@ -4419,18 +4493,6 @@ async function updateEntry(url2, change) {
   await writeCredentials(file);
 }
 
-// ../client/src/fetch.ts
-var import_node_fs5 = require("node:fs");
-var import_promises7 = require("node:fs/promises");
-var import_node_os3 = require("node:os");
-var import_node_path5 = require("node:path");
-var import_promises8 = require("node:stream/promises");
-var import_node_stream2 = require("node:stream");
-var import_node_crypto4 = require("node:crypto");
-
-// ../client/src/publish.ts
-var import_promises6 = require("node:fs/promises");
-
 // ../client/src/transport.ts
 function assertCredentialEndpoint(endpoint) {
   let url2;
@@ -4536,6 +4598,328 @@ function sleep(ms, signal) {
   });
 }
 
+// ../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 && isRecord(answer.body) && typeof answer.body["error"] === "string") return { kind: "unauthorized" };
+    if (answer.status === 404 || answer.status === 401) 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;
+}
+async function confirmPortal(portal, endpoint, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(`${portal}/api/v1/config`, { signal: AbortSignal.timeout(1e4) });
+    if (!res.ok) return false;
+    const body = await res.json();
+    const named = body?.publishingEndpoint;
+    const bare = (u) => u.replace(/\/+$/, "");
+    return typeof named === "string" && bare(named) === bare(endpoint);
+  } catch {
+    return false;
+  }
+}
+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");
+var DEFAULT_EXCLUDED_DIRS = [
+  ".git",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".parcel-cache",
+  ".aws",
+  ".ssh",
+  ".gnupg",
+  ".idea",
+  ".terraform",
+  ".pytest_cache",
+  ".mypy_cache",
+  "coverage",
+  ".DS_Store"
+];
+var DEFAULT_EXCLUDED_FILES = [
+  /^\.env(\..*)?$/,
+  /\.(pem|key|p12|pfx|jks|keystore)$/i,
+  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+  /^\.npmrc$/,
+  /^\.pypirc$/,
+  /^\.netrc$/,
+  /\.(log|tmp|swp)$/i,
+  /^\.DS_Store$/,
+  /^Thumbs\.db$/i,
+  /^credentials(\.json)?$/i,
+  /^service-account.*\.json$/i,
+  /^\.git(modules|attributes)?$/
+];
+async function onboardFolder(opts) {
+  const dir = opts.dir;
+  const policy = opts.policy ?? {};
+  const maxBytes = policy.maxFileBytes ?? 50 * 1024 * 1024;
+  let initialized = false;
+  if (await isGitRepo(dir)) {
+    const head = await headCommit(dir);
+    if (head && !policy.allowExistingHistory) {
+      throw new PublisherError("LOCAL_STATE", "folder is already a Git repository with history; commit your changes and use publish instead of init");
+    }
+  } else {
+    await initWorkRepo(dir, opts.branch ?? "main");
+    initialized = true;
+  }
+  const excluded = [];
+  const candidates = [];
+  const extra = policy.exclude ?? [];
+  const walk = async (d) => {
+    for (const e of await (0, import_promises6.readdir)(d, { withFileTypes: true })) {
+      if (opts.signal?.aborted) throw new PublisherError("CANCELLED", "cancelled");
+      const full = (0, import_node_path5.join)(d, e.name);
+      const rel = (0, import_node_path5.relative)(dir, full).split(import_node_path5.sep).join("/");
+      if (e.isSymbolicLink()) {
+        excluded.push({ path: rel, reason: "symbolic link" });
+        continue;
+      }
+      if (e.isDirectory()) {
+        if (excludedDir(rel, e.name, extra)) {
+          excluded.push({ path: rel + "/", reason: "excluded by policy" });
+          continue;
+        }
+        await walk(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (excludedFile(rel, e.name, extra)) {
+        excluded.push({ path: rel, reason: "excluded by policy" });
+        continue;
+      }
+      const st = await (0, import_promises6.stat)(full);
+      if (st.size > maxBytes) {
+        excluded.push({ path: rel, reason: `larger than ${maxBytes} bytes` });
+        continue;
+      }
+      candidates.push(rel);
+    }
+  };
+  await walk(dir);
+  const ignored = await checkIgnore(dir, candidates);
+  const selected = candidates.filter((p) => !ignored.has(p)).sort();
+  for (const p of ignored) excluded.push({ path: p, reason: "ignored by .gitignore" });
+  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded, initialized };
+  const commit = await commitPaths(dir, selected, {
+    message: opts.message ?? "Initial publication",
+    ...opts.authorName ? { authorName: opts.authorName } : {},
+    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  return { repoDir: dir, commit, committed: selected, excluded, initialized };
+}
+function excludedDir(rel, name, extra) {
+  return DEFAULT_EXCLUDED_DIRS.includes(name) || extra.some((p) => matches(rel, name, p));
+}
+function excludedFile(rel, name, extra) {
+  return DEFAULT_EXCLUDED_FILES.some((re) => re.test(name)) || extra.some((p) => matches(rel, name, p));
+}
+async function recordChanges(opts) {
+  const dir = opts.dir;
+  if (!await isGitRepo(dir)) throw new PublisherError("LOCAL_STATE", "this folder is not published yet; run publisher init first");
+  const maxBytes = opts.policy?.maxFileBytes ?? 50 * 1024 * 1024;
+  const extra = opts.policy?.exclude ?? [];
+  const excluded = [];
+  const selected = [];
+  const entries = await statusPorcelain(dir);
+  if (await mergeInProgress(dir)) {
+    const marked = [];
+    for (const { code, path } of entries) {
+      if (!UNMERGED.has(code)) continue;
+      const text = await (0, import_promises6.readFile)((0, import_node_path5.join)(dir, path), "utf8").catch(() => "");
+      if (/^<{7} /m.test(text) && /^>{7} /m.test(text)) marked.push(path);
+    }
+    if (marked.length)
+      throw new PublisherError(
+        "LOCAL_STATE",
+        `still marked as conflicting: ${marked.join(", ")}; keep one version (or both) in each, remove the <<<<<<< ======= >>>>>>> lines, then sync again`,
+        { details: { marked } }
+      );
+  }
+  for (const { code, path } of entries) {
+    if (code !== "??") {
+      selected.push(path);
+      continue;
+    }
+    const parts = path.split("/");
+    const name = parts[parts.length - 1];
+    const dirs = parts.slice(0, -1);
+    const inExcludedDir = dirs.findIndex((d, i) => excludedDir(dirs.slice(0, i + 1).join("/"), d, extra));
+    if (inExcludedDir >= 0) {
+      excluded.push({ path: dirs.slice(0, inExcludedDir + 1).join("/") + "/", reason: "excluded by policy" });
+      continue;
+    }
+    if (excludedFile(path, name, extra)) {
+      excluded.push({ path, reason: "excluded by policy" });
+      continue;
+    }
+    const st = await (0, import_promises6.lstat)((0, import_node_path5.join)(dir, path));
+    if (st.isSymbolicLink()) {
+      excluded.push({ path, reason: "symbolic link" });
+      continue;
+    }
+    if (st.size > maxBytes) {
+      excluded.push({ path, reason: `larger than ${maxBytes} bytes` });
+      continue;
+    }
+    selected.push(path);
+  }
+  const unique = dedupe(excluded);
+  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded: unique, initialized: false };
+  const commit = await commitPaths(dir, selected.sort(), {
+    message: opts.message ?? "Update",
+    ...opts.authorName ? { authorName: opts.authorName } : {},
+    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  return { repoDir: dir, commit, committed: selected, excluded: unique, initialized: false };
+}
+var UNMERGED = /* @__PURE__ */ new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
+async function mergeInProgress(dir) {
+  return (await runGit(["rev-parse", "-q", "--verify", "MERGE_HEAD"], { cwd: dir, allowFailure: true })).code === 0;
+}
+function dedupe(excluded) {
+  const seen = /* @__PURE__ */ new Set();
+  return excluded.filter((e) => seen.has(e.path) ? false : (seen.add(e.path), true));
+}
+function matches(rel, base, pattern) {
+  if (pattern.includes("*")) {
+    const re = new RegExp(
+      "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+    );
+    return re.test(base) || re.test(rel);
+  }
+  return base === pattern || rel === pattern || rel.startsWith(pattern.replace(/\/$/, "") + "/");
+}
+async function checkIgnore(dir, paths) {
+  if (paths.length === 0) return /* @__PURE__ */ new Set();
+  const r = await runGit(["check-ignore", "--stdin", "-z"], { cwd: dir, input: paths.join("\0") + "\0", allowFailure: true });
+  if (r.code !== 0) return /* @__PURE__ */ new Set();
+  return new Set(r.stdout.toString("utf8").split("\0").filter(Boolean));
+}
+
+// ../client/src/fetch.ts
+var import_node_fs5 = require("node:fs");
+var import_promises8 = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_node_path6 = require("node:path");
+var import_promises9 = require("node:stream/promises");
+var import_node_stream2 = require("node:stream");
+var import_node_crypto4 = require("node:crypto");
+
+// ../client/src/publish.ts
+var import_promises7 = require("node:fs/promises");
+
 // ../client/src/upload.ts
 var import_node_fs4 = require("node:fs");
 var import_node_stream = require("node:stream");
@@ -4614,7 +4998,7 @@ async function publish(ctx, repoId, remote, opts, call) {
       } catch (e) {
         if (!(e instanceof PublisherError && e.code === "LOCAL_STATE")) throw e;
       }
-      if (remaining.length === 0) return toOutcome(outcome, true);
+      if (remaining.length === 0) return toOutcome(outcome, true, pending2.refUpdates);
       return publish(ctx, repoId, remote, opts, call);
     }
   }
@@ -4690,7 +5074,7 @@ async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opt
   }
   if (opts.wait === false) {
     summary = summary ?? await ctx.getStatus(repoId, pending.publicationId, call);
-    return toOutcome(summary, resumed);
+    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);
@@ -4700,9 +5084,9 @@ async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opt
     progress({ phase: "done", message: `published generation ${summary.resultGeneration}` });
   } else if (summary.state === "rejected") {
     await store2.remove(pending.publicationId);
-    if (pending.pack) await (0, import_promises6.rm)(pending.pack.path, { force: true });
+    if (pending.pack) await (0, import_promises7.rm)(pending.pack.path, { force: true });
   }
-  return toOutcome(summary, resumed);
+  return toOutcome(summary, resumed, pending.refUpdates);
 }
 async function waitForOutcome(ctx, repoId, publicationId, timeoutMs, call) {
   const deadline = Date.now() + timeoutMs;
@@ -4749,7 +5133,7 @@ async function resolvePending(ctx, repoDir, remote, pending, call, store2) {
   }
   return summary;
 }
-function toOutcome(s, resumed) {
+function toOutcome(s, resumed, updates) {
   return {
     publicationId: s.publicationId,
     repoId: s.repoId,
@@ -4758,10 +5142,23 @@ function toOutcome(s, resumed) {
     resultGeneration: s.resultGeneration,
     refs: s.refs,
     rejection: s.rejection,
+    next: publishNext(s.rejection, updates[0]?.ref ?? null),
     resumed,
     summary: s
   };
 }
+var REF_MOVED = /* @__PURE__ */ new Set(["NON_FAST_FORWARD", "EXPECTED_OLD_MISMATCH", "STALE_GENERATION"]);
+function publishNext(rejection, published) {
+  if (rejection === null || !REF_MOVED.has(rejection.code)) return null;
+  const named = rejection.details?.["ref"];
+  const ref = typeof named === "string" ? named : published;
+  const name = ref?.replace(/^refs\/heads\//, "") ?? "main";
+  return {
+    action: "sync-and-publish",
+    ask: `${name} moved since your last fetch: someone else published to it. Sync brings those changes in without rewriting yours, and publishes the result.`,
+    command: `publisher sync`
+  };
+}
 async function defaultUpdate(repoDir) {
   const branch = await currentBranch(repoDir);
   if (!branch) throw new PublisherError("LOCAL_STATE", "detached HEAD: specify which ref to publish");
@@ -4807,15 +5204,15 @@ function trackingRef(remote, ref) {
 // ../client/src/fetch.ts
 async function installedManifest(gd) {
   try {
-    const parsed = JSON.parse(await (0, import_promises7.readFile)((0, import_node_path5.join)(gd, "publisher", "installed.json"), "utf8"));
+    const parsed = JSON.parse(await (0, import_promises8.readFile)((0, import_node_path6.join)(gd, "publisher", "installed.json"), "utf8"));
     return new Set(Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : []);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
 async function writeManifest(gd, installed) {
-  await (0, import_promises7.mkdir)((0, import_node_path5.join)(gd, "publisher"), { recursive: true });
-  await (0, import_promises7.writeFile)((0, import_node_path5.join)(gd, "publisher", "installed.json"), JSON.stringify(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) {
   const remote = opts.remote ?? "publisher";
@@ -4862,13 +5259,14 @@ async function haveAll(repoDir, refs) {
 async function install(ctx, gd, artifacts, call) {
   if (artifacts.length === 0) return 0;
   const progress = call.onProgress ?? (() => void 0);
-  const tmp = await (0, import_promises7.mkdtemp)((0, import_node_path5.join)((0, import_node_os3.tmpdir)(), "gitpub-fetch-"));
+  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_path5.join)(tmp, `${a.sha256}.${a.kind}`);
+      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);
-      progress({ phase: "fetch", message: `installing ${a.kind}`, bytes, total: a.size });
+      progress({ phase: "fetch", message: `installing ${a.kind}`, bytes, total });
       if (a.kind === "bundle") {
         await bundleUnbundleObjects(gd, file);
       } else {
@@ -4876,7 +5274,7 @@ async function install(ctx, gd, artifacts, call) {
       }
     }
   } finally {
-    await (0, import_promises7.rm)(tmp, { recursive: true, force: true });
+    await (0, import_promises8.rm)(tmp, { recursive: true, force: true });
   }
   return bytes;
 }
@@ -4916,7 +5314,7 @@ async function download(fetchImpl, url2, dest, sha256, size, call) {
       controller.enqueue(chunk);
     }
   });
-  await (0, import_promises8.pipeline)(import_node_stream2.Readable.fromWeb(res.body.pipeThrough(counted)), (0, import_node_fs5.createWriteStream)(dest));
+  await (0, import_promises9.pipeline)(import_node_stream2.Readable.fromWeb(res.body.pipeThrough(counted)), (0, import_node_fs5.createWriteStream)(dest));
   if (n !== size || hash.digest("hex") !== sha256) throw new PublisherError("NETWORK", "downloaded artifact failed checksum verification", { retryable: true });
   return n;
 }
@@ -4924,6 +5322,11 @@ async function download(fetchImpl, url2, dest, sha256, size, call) {
 // ../client/src/publisher.ts
 var CLIENT_NAME = "git-publisher-client";
 var CLIENT_VERSION = "0.1.0";
+async function markConflicts(dir, remote) {
+  const who = { GIT_AUTHOR_NAME: "Publisher", GIT_AUTHOR_EMAIL: "publisher@localhost", GIT_COMMITTER_NAME: "Publisher", GIT_COMMITTER_EMAIL: "publisher@localhost" };
+  const r = await runGit(["merge", "--no-ff", "--no-commit", "--no-verify", remote], { cwd: dir, env: { extra: who }, allowFailure: true });
+  if (r.code !== 0 && !await mergeInProgress(dir)) throw new PublisherError("GIT", `could not mark the conflicts: ${r.stderr.trim()}`);
+}
 var Publisher = class {
   constructor(opts) {
     this.opts = opts;
@@ -4950,6 +5353,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;
@@ -5022,6 +5438,10 @@ var Publisher = class {
   async checkout(options, call = {}) {
     return checkoutWorkspace(this, options, call);
   }
+  /** Make an associated folder a workspace (idempotent); `init` and `sync` both call it. */
+  async adoptWorkspace(directory, call = {}) {
+    return adoptWorkspace(this, directory, call);
+  }
   /** Offline: the persisted workspace mapping, or null. */
   async workspace(directory) {
     return getWorkspaceMapping(directory);
@@ -5034,6 +5454,37 @@ var Publisher = class {
   async sync(options, call = {}) {
     return syncWorkspace(this, options, call);
   }
+  /**
+   * A creator's whole round trip in one call, so nobody runs git: record their changes, bring in
+   * what the service has (fast-forward or a clean merge, never a rewrite), and publish. It stops,
+   * having published nothing, on a conflict; the recorded commit stays, so nothing is lost.
+   *
+   * Everything that can refuse without touching the folder refuses first: a folder with no
+   * association (or one pinned elsewhere) and a HEAD off the workspace branch would otherwise get
+   * 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 = {}) {
+    const dir = options.directory;
+    await this.resolveRepo(dir);
+    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 mapped = await getWorkspaceMapping(dir);
+    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 base = { recorded: { commit: recorded.commit, committed: recorded.committed, excluded: recorded.excluded }, reconciled };
+    if (reconciled.after === "conflict") {
+      const remote = reconciled.before.remote?.oid ?? null;
+      if (options.markConflicts && remote) await markConflicts(dir, remote);
+      return { ...base, state: "conflict", published: null, marked: options.markConflicts === true && remote !== null };
+    }
+    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);
+    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 = {}) {
     const { remote } = await this.resolveRepo(repoDir);
@@ -5051,7 +5502,7 @@ var Publisher = class {
         call.onProgress?.({ phase: "validate", message: `waiting for ${p.publicationId}` });
         s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call, waitSeconds: MAX_WAIT_SECONDS }, store2);
       }
-      out.push(toOutcome(s, true));
+      out.push(toOutcome(s, true, p.refUpdates));
     }
     for (const o of out) await noteAcceptedPublication(repoDir, o);
     return out;
@@ -5087,120 +5538,6 @@ function createPublisher(opts) {
   return new Publisher(opts);
 }
 
-// ../client/src/onboard.ts
-var import_promises9 = require("node:fs/promises");
-var import_node_path6 = require("node:path");
-var DEFAULT_EXCLUDED_DIRS = [
-  ".git",
-  "node_modules",
-  ".venv",
-  "venv",
-  "__pycache__",
-  ".cache",
-  ".next",
-  ".nuxt",
-  ".turbo",
-  ".parcel-cache",
-  ".aws",
-  ".ssh",
-  ".gnupg",
-  ".idea",
-  ".terraform",
-  ".pytest_cache",
-  ".mypy_cache",
-  "coverage",
-  ".DS_Store"
-];
-var DEFAULT_EXCLUDED_FILES = [
-  /^\.env(\..*)?$/,
-  /\.(pem|key|p12|pfx|jks|keystore)$/i,
-  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
-  /^\.npmrc$/,
-  /^\.pypirc$/,
-  /^\.netrc$/,
-  /\.(log|tmp|swp)$/i,
-  /^\.DS_Store$/,
-  /^Thumbs\.db$/i,
-  /^credentials(\.json)?$/i,
-  /^service-account.*\.json$/i,
-  /^\.git(modules|attributes)?$/
-];
-async function onboardFolder(opts) {
-  const dir = opts.dir;
-  const policy = opts.policy ?? {};
-  const maxBytes = policy.maxFileBytes ?? 50 * 1024 * 1024;
-  let initialized = false;
-  if (await isGitRepo(dir)) {
-    const head = await headCommit(dir);
-    if (head && !policy.allowExistingHistory) {
-      throw new PublisherError("LOCAL_STATE", "folder is already a Git repository with history; commit your changes and use publish instead of init");
-    }
-  } else {
-    await initWorkRepo(dir, opts.branch ?? "main");
-    initialized = true;
-  }
-  const excluded = [];
-  const candidates = [];
-  const extra = policy.exclude ?? [];
-  const walk = async (d) => {
-    for (const e of await (0, import_promises9.readdir)(d, { withFileTypes: true })) {
-      if (opts.signal?.aborted) throw new PublisherError("CANCELLED", "cancelled");
-      const full = (0, import_node_path6.join)(d, e.name);
-      const rel = (0, import_node_path6.relative)(dir, full).split(import_node_path6.sep).join("/");
-      if (e.isSymbolicLink()) {
-        excluded.push({ path: rel, reason: "symbolic link" });
-        continue;
-      }
-      if (e.isDirectory()) {
-        if (DEFAULT_EXCLUDED_DIRS.includes(e.name) || extra.some((p) => matches(rel, e.name, p))) {
-          excluded.push({ path: rel + "/", reason: "excluded by policy" });
-          continue;
-        }
-        await walk(full);
-        continue;
-      }
-      if (!e.isFile()) continue;
-      if (DEFAULT_EXCLUDED_FILES.some((re) => re.test(e.name)) || extra.some((p) => matches(rel, e.name, p))) {
-        excluded.push({ path: rel, reason: "excluded by policy" });
-        continue;
-      }
-      const st = await (0, import_promises9.stat)(full);
-      if (st.size > maxBytes) {
-        excluded.push({ path: rel, reason: `larger than ${maxBytes} bytes` });
-        continue;
-      }
-      candidates.push(rel);
-    }
-  };
-  await walk(dir);
-  const ignored = await checkIgnore(dir, candidates);
-  const selected = candidates.filter((p) => !ignored.has(p)).sort();
-  for (const p of ignored) excluded.push({ path: p, reason: "ignored by .gitignore" });
-  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded, initialized };
-  const commit = await commitPaths(dir, selected, {
-    message: opts.message ?? "Initial publication",
-    ...opts.authorName ? { authorName: opts.authorName } : {},
-    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
-    ...opts.signal ? { signal: opts.signal } : {}
-  });
-  return { repoDir: dir, commit, committed: selected, excluded, initialized };
-}
-function matches(rel, base, pattern) {
-  if (pattern.includes("*")) {
-    const re = new RegExp(
-      "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
-    );
-    return re.test(base) || re.test(rel);
-  }
-  return base === pattern || rel === pattern || rel.startsWith(pattern.replace(/\/$/, "") + "/");
-}
-async function checkIgnore(dir, paths) {
-  if (paths.length === 0) return /* @__PURE__ */ new Set();
-  const r = await runGit(["check-ignore", "--stdin", "-z"], { cwd: dir, input: paths.join("\0") + "\0", allowFailure: true });
-  if (r.code !== 0) return /* @__PURE__ */ new Set();
-  return new Set(r.stdout.toString("utf8").split("\0").filter(Boolean));
-}
-
 // ../client/src/migrate.ts
 async function fetchCapabilities(endpoint, fetchImpl = fetch, signal) {
   const res = await fetchImpl(`${normalize(endpoint)}/v1/capabilities`, { method: "GET", ...signal ? { signal } : {} });
@@ -5354,7 +5691,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);
@@ -5372,7 +5709,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);
@@ -5388,7 +5725,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;
@@ -5411,6 +5748,7 @@ var OPTIONS = {
   repo: { type: "string" },
   message: { type: "string" },
   publication: { type: "string" },
+  timeout: { type: "string" },
   branch: { type: "string" },
   ours: { type: "string" },
   theirs: { type: "string" },
@@ -5420,7 +5758,9 @@ var OPTIONS = {
   quiet: { type: "boolean" },
   force: { type: "boolean" },
   apply: { type: "boolean" },
+  "mark-conflicts": { type: "boolean" },
   help: { type: "boolean" },
+  version: { type: "boolean" },
   "set-default": { type: "boolean" },
   // A flag of its own, not a negation of --wait: there is no --wait.
   "no-wait": { type: "boolean" }
@@ -5434,10 +5774,122 @@ function parseArgs(argv) {
   }
 }
 
+// src/skills.ts
+var import_node_child_process3 = require("node:child_process");
+var import_node_fs6 = require("node:fs");
+var import_node_path7 = require("node:path");
+var MARKETPLACE = "shadow-publisher";
+var PLUGIN = "git-publisher";
+function packageRoot() {
+  return (0, import_node_path7.join)((0, import_node_path7.dirname)((0, import_node_fs6.realpathSync)(process.argv[1])), "..");
+}
+function packageVersion() {
+  try {
+    return JSON.parse((0, import_node_fs6.readFileSync)((0, import_node_path7.join)(packageRoot(), "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+function claude(args) {
+  return new Promise((resolve3) => {
+    let stdout = "";
+    let stderr = "";
+    const child = (0, import_node_child_process3.spawn)("claude", args, { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", (d) => stdout += d.toString("utf8"));
+    child.stderr.on("data", (d) => stderr += d.toString("utf8"));
+    child.on("error", (e) => resolve3({ code: null, stdout, stderr: e.message, missing: e.code === "ENOENT" }));
+    child.on("close", (code) => resolve3({ code, stdout, stderr, missing: false }));
+  });
+}
+async function installSkills({ log }) {
+  const source = (0, import_node_path7.join)(packageRoot(), "dist", "claude");
+  if (!(0, import_node_fs6.existsSync)((0, import_node_path7.join)(source, ".claude-plugin", "marketplace.json"))) {
+    throw new PublisherError("LOCAL_STATE", `this publisher carries no skills at ${source}; reinstall it with: npm install -g @minnovate/shadow-publisher`);
+  }
+  const step = async (what, args) => {
+    log(what);
+    const r = await claude(args);
+    if (r.missing) {
+      throw new PublisherError(
+        "LOCAL_STATE",
+        'Claude Code is not installed, or "claude" is not on PATH. Install it from https://claude.com/claude-code, then run: publisher skills install'
+      );
+    }
+    if (r.code !== 0) throw new PublisherError("LOCAL_STATE", `"claude ${args.slice(0, 3).join(" ")}" failed: ${(r.stderr || r.stdout).trim()}`);
+  };
+  await step("Adding the publisher to Claude Code\u2026", ["plugin", "marketplace", "add", source, "--scope", "user"]);
+  await step("Installing its skills\u2026", ["plugin", "install", `${PLUGIN}@${MARKETPLACE}`, "--scope", "user"]);
+  return {
+    ok: true,
+    plugin: `${PLUGIN}@${MARKETPLACE}`,
+    marketplace: MARKETPLACE,
+    source,
+    version: packageVersion(),
+    message: "The publisher skills are installed in Claude Code for your user. Start a new Claude Code session (or run /reload-plugins in an open one) and ask it to publish your app."
+  };
+}
+
+// src/follow.ts
+async function followPublication(p, endpoint, o, opts) {
+  const derived = portalForEndpoint(endpoint);
+  const portal = derived !== null && await confirmPortal(derived, endpoint, opts.fetch) ? derived : null;
+  const elsewhere = (reason) => ({ kind: "unavailable", reason, portal, hint: inPortal(portal, "Published.", "Follow it") });
+  if (portal === null) return elsewhere("no-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
 
 Usage:
+  publisher skills install                              add the publisher's skills to Claude Code (user scope);
+                                                        run it again after updating the publisher
   publisher login                                       sign in. With NO arguments it asks the
                                                         portal where publishing lives, opens a
                                                         browser to confirm who you are, and asks
@@ -5447,19 +5899,35 @@ Usage:
       [--profile <name>] [--set-default] [--token <token>]
   publisher logout (--endpoint <url> | --profile <name>)
   publisher profile list | profile use <name> | profile remove <name>
-  publisher init [dir] [--name <name>] [--repo <id>]    create (or attach to) a repository and associate this folder
-  publisher publish [dir] [--ref <ref>]... [--force] [--no-wait]
+  publisher init [dir] [--name <name>] [--repo <id>]    create (or attach to) a repository, associate this folder
+                                                        and record it as a workspace (so sync works here)
+  publisher publish [dir] [--ref <ref>]... [--force] [--no-wait]   publish commits as they are; to save and publish
+                                                        a change, use sync
   publisher status [dir] [--publication <id>]           resolve pending/interrupted publications
   publisher fetch [dir]
   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] [--apply]                         fetch; with --apply fast-forward or merge cleanly, advance the base
+  publisher sync [dir] [--message <text>]               THE way to save and publish a change: records the folder's
+                                                        changes (never .env, keys or node_modules), brings in what
+                                                        was published meanwhile (fast-forward or a clean merge,
+                                                        never a rewrite) and publishes. Stops on a conflict with
+                                                        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)
   publisher migrate [dir] [--to <url>]                   re-point a folder whose service moved (asks the service where)
 
-Global flags: --endpoint <url>, --profile <name>, --token, --json, --quiet
+Global flags: --endpoint <url>, --profile <name>, --token, --json, --quiet, --version
+
+A creator never needs git: init once, then sync after every change.
 
 Which endpoint a command uses, first hit wins:
   --endpoint <url>              an explicit URL; needs no stored profile
@@ -5495,7 +5963,11 @@ async function main(argv) {
     process.stderr.write(`\r[${e.phase}] ${e.message}${pct}          `);
     if (e.phase === "done") process.stderr.write("\n");
   };
-  const dirArg = (i) => (0, import_node_path7.resolve)(cmd[i] ?? ".");
+  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;
@@ -5524,6 +5996,11 @@ async function main(argv) {
     const token = str2(flags["token"]);
     return { endpoint, p: createPublisher({ endpoint, endpointSource: source, ...token ? { token } : {}, clientName: "git-publisher-cli", clientVersion: CLIENT_VERSION }) };
   };
+  if (flags["version"] === true) {
+    process.stdout.write(`${packageVersion()}
+`);
+    return 0;
+  }
   switch (flags["help"] === true ? "help" : cmd[0]) {
     case void 0:
     case "help":
@@ -5669,19 +6146,30 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
         await p.getRepository(repoId);
       }
       await p.associate(dir, repoId);
+      const workspace = await p.adoptWorkspace(dir).catch(() => null);
       out({
         ok: true,
         repoId,
         created,
         endpoint,
         dir,
-        onboarding: onboarding ? { commit: onboarding.commit, committed: onboarding.committed.length, excluded: onboarding.excluded } : null
+        onboarding: onboarding ? { commit: onboarding.commit, committed: onboarding.committed.length, excluded: onboarding.excluded } : null,
+        workspace: workspace === null ? null : { branch: workspace.branch, baseOid: workspace.baseOid, baseGeneration: workspace.baseGeneration }
       });
       return 0;
     }
     case "publish": {
       let finishPublish2 = function(o) {
-        out({ state: o.state, publicationId: o.publicationId, repoId: o.repoId, generation: o.resultGeneration, refs: o.refs, rejection: o.rejection, resumed: o.resumed });
+        out({
+          state: o.state,
+          publicationId: o.publicationId,
+          repoId: o.repoId,
+          generation: o.resultGeneration,
+          refs: o.refs,
+          rejection: o.rejection,
+          resumed: o.resumed,
+          ...o.next === null ? {} : { next: o.next }
+        });
         return o.state === "accepted" ? 0 : o.state === "rejected" ? 2 : 3;
       };
       var finishPublish = finishPublish2;
@@ -5717,7 +6205,13 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       const resolved = await p.resumePublications(dir, { onProgress: progress });
       out({
         pending: pending.map((x) => x.publicationId),
-        resolved: resolved.map((o) => ({ publicationId: o.publicationId, state: o.state, generation: o.resultGeneration, rejection: o.rejection }))
+        resolved: resolved.map((o) => ({
+          publicationId: o.publicationId,
+          state: o.state,
+          generation: o.resultGeneration,
+          rejection: o.rejection,
+          ...o.next === null ? {} : { next: o.next }
+        }))
       });
       return resolved.every((o) => o.state === "accepted") ? 0 : resolved.some((o) => o.state === "rejected") ? 2 : 3;
     }
@@ -5745,12 +6239,63 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       out(s);
       return s.state === "conflict" ? 2 : 0;
     }
+    /**
+     * The creator's one verb: record the folder's changes, bring in what the service has, publish.
+     * `--apply` is what this was before it recorded and published, and is still accepted, so a
+     * `sync --apply` written down anywhere does the whole round trip rather than failing.
+     */
     case "sync": {
       const dir = dirArg(1);
-      const { p } = await client(dir);
-      const r = await p.sync({ directory: dir, apply: flags["apply"] === true, ...optStr(flags, "message") }, { onProgress: progress });
-      out({ ok: true, before: r.before.state, applied: r.applied, after: r.after, base: { oid: r.mapping.baseOid, generation: r.mapping.baseGeneration }, hint: r.before.hint });
-      return r.after === "conflict" ? 2 : 0;
+      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,
+        recorded: r.recorded,
+        merged: r.reconciled.applied,
+        conflicts: r.reconciled.before.conflicts,
+        marked: r.marked,
+        publication: o === null ? null : {
+          state: o.state,
+          publicationId: o.publicationId,
+          generation: o.resultGeneration,
+          refs: o.refs,
+          rejection: o.rejection,
+          ...o.next === null ? {} : { next: o.next }
+        },
+        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 });
+      out(r);
+      return 0;
     }
     case "merge-check": {
       const dir = dirArg(1);
@@ -5796,6 +6341,20 @@ function demand(r, input) {
       throw new PublisherError("LOCAL_STATE", `not connected to a publishing service yet.${run}`, { details });
   }
 }
+function syncHint(state, conflicts, marked) {
+  switch (state) {
+    case "published":
+      return "Your changes are saved and published.";
+    case "up_to_date":
+      return "Nothing new to publish: the service already has this version.";
+    case "conflict":
+      return marked ? `Both versions are now in ${conflicts.join(", ")}, between <<<<<<< and >>>>>>> lines. Edit each to what should be kept, remove those lines, then run publisher sync.` : `Your changes and the published version both changed ${conflicts.join(", ")}. Nothing was published and nothing was lost; decide which version to keep.`;
+    case "rejected":
+      return "The service refused the publication; see publication.rejection.";
+    default:
+      return "The publication was sent but its outcome is not known yet; run publisher status.";
+  }
+}
 function formatHuman(v) {
   return JSON.stringify(v, null, 2);
 }