@minnovate/shadow-publisher 0.3.0 → 0.6.0

package/README.md

@@ -4,11 +4,18 @@ Publish an app's Git history to the serverless Git publishing backend.
 
 ```sh
 npm install -g @minnovate/shadow-publisher
-publisher --help
-publisher login
+publisher skills install     # adds the publisher's skills to Claude Code
 ```
 
-Needs Node 22.12 or later and git 2.46 or later on `PATH`. The package is one bundled file with no
-runtime dependencies.
+Then ask Claude Code to publish your app. Without Claude Code:
+
+```sh
+publisher login              # signs you in through your browser
+publisher init . --name my-app
+publisher sync               # after every change: saves it and publishes it; no git needed
+```
+
+Needs Node 22.12 or later and git 2.46 or later on `PATH`. The package is one bundled file, and the
+Claude Code skills beside it, with no runtime dependencies.
 
 Apache-2.0 licensed; see `LICENSE`.

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

@@ -0,0 +1,12 @@
+{
+  "name": "shadow-publisher",
+  "owner": { "name": "Minnovate" },
+  "description": "The publisher's Claude Code skills: publish an app and keep it in sync, without git.",
+  "plugins": [
+    {
+      "name": "git-publisher",
+      "source": "./plugin",
+      "description": "Publish an app folder and keep it updated (\"publish my app\", \"save my changes\", \"get the latest version\")."
+    }
+  ]
+}

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

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

@@ -0,0 +1,16 @@
+# Git Publisher plugin for Claude Code
+
+Thin adapter: two skills (`publish-app`, `sync-app`) that drive the `publisher` CLI
+(`@minnovate/shadow-publisher`, `packages/cli`) from PATH. All publication, retry, resume and merge
+logic lives in the shared client library; the skills only orchestrate, and a creator's changes are
+saved and published with `publisher sync`, never with git.
+
+It ships inside the npm package, and `publisher skills install` installs it into Claude Code.
+
+Runtime requirements in the environment where Claude Code runs: the publisher installed
+(`npm install -g @minnovate/shadow-publisher`, Node.js 22), Git ≥ 2.46 on PATH, outbound HTTPS to
+the portal's domain (sign-in and publishing at `/publish`) and the S3 bucket host for direct
+uploads/downloads.
+
+See `integrations/claude/README.md` for installation, authentication, uninstall and the verified
+environments.

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

@@ -0,0 +1,156 @@
+---
+name: publish-app
+description: Publish or update the user's app (a folder) with the publisher. Use when the user says "publish my app", "update my app", "save my changes", "push my changes", "save this version online", or asks to resolve an interrupted publication. Handles first-time setup, every later update, interruption recovery and conflicts by running the `publisher` command; never uses git to commit or push.
+allowed-tools: Bash(publisher *), Bash(git status *), Bash(git diff *), Bash(git log *)
+---
+
+# Publish or update the user's app
+
+You publish the user's app folder with the `publisher` command. All saving, merging, publishing,
+retry and resume logic lives in it; your job is to run it, read its `--json` output, and tell the
+user what happened in plain language. Never explain S3, packs, commits, sessions or tokens.
+
+**`publisher sync` is how a change is saved and published. Never run `git add`, `git commit`,
+`git push` or `git stash` in the user's app folder**, and never add a git remote. `sync` records the
+folder's changes itself — and leaves out `.env` files, keys, `node_modules` and anything larger than
+50 MB, which a hand-made commit would not. You may read with `git status`, `git diff` and `git log`
+to describe a change; nothing else.
+
+Every command accepts `--json` and prints exactly one JSON object on stdout. Exit codes:
+`0` success · `1` local/usage error · `2` rejected or conflict · `3` outcome not yet known · `4` authentication.
+
+## 1. Preflight (run once)
+
+```bash
+publisher --version
+```
+
+If the command is not found, tell the user the publisher is not installed and that one command
+installs it: `npm install -g @minnovate/shadow-publisher` (it needs Node.js 22). Stop there.
+
+```bash
+publisher doctor --json
+```
+
+- `gitOk:false` → tell the user Git 2.46 or later must be installed; stop.
+- Otherwise do exactly what **`next.action`** says. `doctor` works this out for you, and the same
+  `next` object rides on `error.details` of any command that cannot resolve a connection — so you
+  never have to interpret `credentials`, `endpoint` or `profiles` yourself.
+
+| `next.action` | What it means | What to do |
+|---|---|---|
+| `"ready"` | Signed in and pointed somewhere. | **Nothing. Go to step 2 and do not mention any of this.** |
+| `"sign-in"` | Not connected to anything yet. | **Ask them nothing** — `next.ask` is `null`. Just run `next.command` (`publisher login --json`). It finds the service, opens their browser and prints a code for them to confirm; tell them to expect that, and wait. Use `--portal <url>` only if they say they are on a different platform. |
+| `"choose-profile"` | Several places are set up and none is marked usual. | Show `next.profiles` and ask `next.ask`. Then run `next.command` with the name they picked. |
+| `"reauthenticate"` | The place is known; the credential is gone or expired. | Just run `next.command`. `next.ask` is `null` — do **not** ask them for anything; the browser sign-in asks them itself. |
+| `"bind-endpoint"` | A token is set in the environment, but nothing said where it may go. | **Stop** and tell them publishing is blocked by a token set in this shell. `next.command` is `null` on purpose: never set `GIT_PUBLISHER_ENDPOINT` or pass `--endpoint` yourself — that is exactly the choice the check leaves to whoever set the token. |
+
+**Never ask the user for a token, an endpoint, a URL or a credential — in any words.** They are
+publishing an app; they do not know what those are, and you no longer need them: `login` discovers
+where publishing lives and signs them in through their browser. `next.ask` is `null` whenever
+nothing needs asking, which is now every case except choosing between connections they already
+have; when it is not null it is already phrased for them, so pass it on rather than rewriting it.
+
+If they name an environment ("publish to dev"), pass `--profile dev` on each command rather than
+changing their default.
+
+## 2. First publication of a folder
+
+Run in the app folder (the folder the user is working in):
+
+```bash
+publisher info --json            # exit 1 with LOCAL_STATE "not associated" means: not published yet
+```
+
+If not associated:
+
+```bash
+publisher init . --name "<app name>" --json
+```
+
+`init` prepares the folder with an explicit file selection: it excludes `.git`, `node_modules`,
+build caches, `.env*`, keys/certificates and files larger than 50 MB, and it respects
+`.gitignore`. Show the user the `onboarding.excluded` list so they know what was left out (the
+exclusion rules are a safety net, not a secret scanner). Then publish it with step 3.
+
+## 3. Every update — and the first publish after `init`
+
+```bash
+publisher sync . --message "<a few words on what changed>" --timeout 90 --json
+```
+
+That one command records what changed in the folder, brings in anything published meanwhile (a
+fast-forward or a clean merge — it never rewrites the user's work), and publishes the result. Write
+the message in the user's words ("Add a contact page"), not git's.
+
+## 4. Reading the result
+
+After a publish, the command follows the app going live, asking every 5 seconds, for at most
+`--timeout` seconds. Keep that at 90: your shell tool shows output only when a command ends, and
+cuts one off after two minutes. With `--json` it prints one line per step, then the result object
+as the LAST line.
+
+If the run is still going when the 90 seconds are up, `progress.kind` is `"timed-out"` and
+`progress.next.command` picks it up. Run it (it is `publisher follow --publication <id> --json`;
+add `--timeout 90`) and repeat until `progress.kind` is no longer `"timed-out"`, up to about 15
+minutes in all. Each call prints the steps as they now stand, from the first: relay only the ones
+you have not relayed yet.
+
+```json
+{"event":"stage","stage":"running","word":"checked","state":"in-progress","at":"2026-09-23T10:00:10Z"}
+```
+
+Relay each step in its `word` — **received**, **checked**, **going live**, **live** — and nothing
+else: not the `stage` name, not a step you guessed. Read the result from the last line. **If the
+command was cut off while following**, the publication had already succeeded before the following
+began: say it is published, and follow it with `publisher follow --publication <publicationId>
+--timeout 90 --json` (the id is in the `sync` output's `publication`, or `publisher status`). Do
+not run `sync` again to find out. `--no-wait` skips the following, for when the user asks not to wait.
+
+`state` says what happened; `hint` is one sentence you may pass on as it is.
+
+- `"published"` → the app was published. Mention what was recorded (`recorded.committed`) and, if
+  `recorded.excluded` is not empty, what was left out and why. Then read `progress` (null with
+  `--no-wait`) and pass on its `hint`:
+  - `kind: "settled"` with `ending` `"live"`: the app is live. `"not-deployed"`: published and
+    checked, and this organisation does not deploy automatically. `"failed"`: it stopped at
+    `failedAt`; the portal says why — do not guess the reason. `"stopped"`: a newer publication
+    replaced it.
+  - `"timed-out"`: still going; run `progress.next.command` as above. After about 15 minutes in
+    all, stop and point them to the portal (`progress.portal`).
+  - `"unauthorized"`: published, but the portal did not accept this sign-in; run `publisher login`
+    before the next publish.
+  - `"unavailable"`, `"forbidden"` or `"malformed"`: the publish itself succeeded, but this
+    terminal cannot show the steps. Tell them to follow it in the portal. Never report a step that
+    no `stage` line said.
+- `"up_to_date"` → nothing new to publish; the service already has this version.
+- `"conflict"` → the user's change and a published change touched the same lines of
+  `conflicts[]`. **Nothing was published and nothing was lost.** Do not resolve it on your own and
+  never publish with `--force`. Follow the `sync-app` skill's conflict section.
+- `"rejected"` with `publication.rejection.code`:
+  - `NON_FAST_FORWARD` / `STALE_GENERATION` / `EXPECTED_OLD_MISMATCH`: somebody published in the
+    moment between the merge and the publish. Run `publisher sync . --json` once more
+    (`publication.next.command` says the same).
+  - `REF_FORBIDDEN`: the user may not publish this branch; tell them which branch and stop.
+  - `MISSING_OBJECTS`: the local copy is incomplete (for example a shallow clone). Tell the user to
+    publish from a complete copy: `publisher checkout <new folder> --repo <id>`.
+  - `LIMIT_EXCEEDED`, `PACK_INVALID`: quote the message; suggest removing very large files from the
+    folder if the message mentions size.
+- `"unknown"` / exit code 3: the publication was sent but its outcome is not known yet. Run
+  `publisher status . --json`; it waits for and resolves interrupted publications without creating
+  duplicates. Repeat once if it still says `finalizing`.
+- Exit code 4: run `publisher doctor --json` and follow `next.action` (normally `reauthenticate`:
+  run `next.command`). Never ask the user for a token.
+
+## 5. Interrupted earlier?
+
+If a previous publish was interrupted (network loss, closed session), `publisher status . --json`
+resumes or resolves it. Always run it before starting a new sync when the last result was unknown.
+
+## Rules
+
+- `publisher sync` is the only way a change is saved and published. Never `git add`, `git commit`,
+  `git push`, `git stash`, `git reset`, `git rebase`, and never modify remotes.
+- Never print tokens or signed URLs. The publisher already redacts them.
+- Never publish with `--force` unless the user explicitly asks to overwrite the published history
+  and understands the other side's changes will be discarded.

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

@@ -0,0 +1,72 @@
+---
+name: sync-app
+description: Bring the published (possibly engineered) version of the user's app into their folder, together with their own changes, and publish the result. Use when the user says "get the latest version", "sync my app", "sync with the engineering changes", when a publish was refused because somebody else published first, or when a sync reported a conflict. Never overwrites local work and never uses git to commit.
+allowed-tools: Bash(publisher *), Bash(git status *), Bash(git log *), Bash(git diff *)
+---
+
+# Keep the user's app in step with what is published
+
+**`publisher sync` does all of it**: it records the user's changes, brings in what was published
+meanwhile (a fast-forward, or a clean merge that never rewrites their work), and publishes the
+result. Never run `git add`, `git commit`, `git push`, `git pull`, `git merge`, `git stash`,
+`git reset` or `git rebase` in the user's app folder.
+
+```bash
+publisher sync . --json
+```
+
+Read the step lines and `state` exactly as the `publish-app` skill describes (step 4): after a
+publish it follows the app through received → checked → going live → live before it prints the
+result. `merged` says whether anything
+published elsewhere was brought in (`"fast-forward"` or `"merge"`); mention it when it is not null.
+
+## Just looking
+
+To say where the folder stands without changing anything:
+
+```bash
+publisher workspace-status . --json      # state + hint; exit 2 means conflict
+```
+
+| state | meaning | what to do |
+| --- | --- | --- |
+| `up_to_date` | identical to the published version | nothing |
+| `local_changes` | the user changed something the service does not have yet | `publisher sync` |
+| `remote_ahead` | something was published elsewhere; the folder is behind | `publisher sync` |
+| `diverged_clean_merge` | both changed, and the changes combine cleanly | `publisher sync` |
+| `conflict` | both changed the same lines (`conflicts[]`) | see below |
+| `detached` | the folder is not on the branch it publishes | ask the user before anything else |
+
+`pending[]` lists interrupted publications; run `publisher status . --json` first when it is not empty.
+
+## A fresh copy
+
+When the user wants their app in a new folder (a new computer, a clean start):
+
+```bash
+publisher checkout <new-folder> --repo <repoId> --json   # a NEW folder only; refuses a non-empty one
+```
+
+## Conflicts
+
+A `conflict` means the user's version and the published one both changed the same lines of the
+files in `conflicts[]`. **Nothing was published and nothing was lost**: the user's change is
+recorded locally, and the published version is still on the service.
+
+1. List the files and say, in plain words, what each side changed there (`git diff` and `git log`
+   may help you describe it).
+2. Ask the user which version to keep for each file, or whether to combine them. Do not decide for
+   them and never publish with `--force` — that discards the other side's work.
+3. Only after they decide, put both versions into the files, marked:
+
+   ```bash
+   publisher sync . --mark-conflicts --json
+   ```
+
+   Each file in `conflicts[]` now holds both versions between `<<<<<<<`, `=======` and `>>>>>>>`
+   lines. Edit each to what they chose, and remove those lines.
+4. Run `publisher sync . --json`. It records the edit and publishes it. If a file still carries the
+   marker lines it refuses, names the files (`error.details.marked`) and publishes nothing; finish
+   the edit and run it again.
+
+No git command is needed at any point, including here.