@vibedropio/publisher 0.0.0-stage → 0.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,159 @@
1
+ ---
2
+ name: sync-app
3
+ 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.
4
+ allowed-tools: Bash(publisher *), Bash(git status *), Bash(git log *), Bash(git diff *)
5
+ ---
6
+
7
+ # Keep the user's app in step with what is published
8
+
9
+ **`publisher sync` does all of it**: it records the user's changes, brings in what was published
10
+ meanwhile (a fast-forward, or a clean merge that never rewrites their work), and publishes the
11
+ result. Never run `git add`, `git commit`, `git push`, `git pull`, `git merge`, `git stash`,
12
+ `git reset` or `git rebase` in the user's app folder.
13
+
14
+ ```bash
15
+ publisher sync . --until-change --timeout 100 --json
16
+ ```
17
+
18
+ Read the step lines and `state` exactly as the `publish-app` skill describes (step 4): after a
19
+ publish it follows the app through received → checked → going live → live before it prints the
20
+ result. `merged` says whether anything
21
+ published elsewhere was brought in (`"fast-forward"` or `"merge"`); mention it when it is not null.
22
+
23
+ ## When the app moved
24
+
25
+ A sync that ends with `REPOSITORY_MOVED` — `publication.rejection.code`, or `error.code` when it
26
+ was refused before anything was sent — means the app moved to another organization (the person's
27
+ team adopted it). Pass on its `hint`, and do what the `publish-app` skill's "When the app moved"
28
+ says: sign in again with `publisher login` and choose that organization, then
29
+ `publisher checkout <new folder> --repo <details.movedTo>` (or find the app with
30
+ `publisher list --json` when `details.movedTo` is `null`), and publish from the new folder. Do not
31
+ sync this folder again.
32
+
33
+ ## When it waits for an answer
34
+
35
+ Sometimes the app's preparation asks one business question before it can go on (for example
36
+ whether to use the organization's data). `follow` then stops with `kind: "waiting"` and
37
+ `next.command`. Read the question:
38
+
39
+ ```bash
40
+ publisher question . --json
41
+ ```
42
+
43
+ Tell the person `questions[].text` and the `label` of each option, and ask which they want. Answer
44
+ with the option's `value`, never its label, only once they have chosen — or directly when they
45
+ told you what to answer:
46
+
47
+ ```bash
48
+ publisher answer <question id>=<value> --json
49
+ ```
50
+
51
+ A value that is not an option is refused before anything is sent; `error.details.questions` lists
52
+ the choices. Exit 4 means this sign-in may not answer (an owner or admin can, or the app's creator for the
53
+ first preparation after an adoption); when it carries a `hint`, a limit refused it, so tell them the reason
54
+ and whom to ask that the `hint` gives. Exit 3 means ask
55
+ again. Then `publisher follow . --publication <id> --until-change --timeout 100 --json` to see it go live, telling them each step as `publish-app` step 4 says.
56
+
57
+ ## When it did not go live because of a fault on our side
58
+
59
+ When `publisher question . --json` shows a `blocked` preparation with `canRetry: true`, the fault
60
+ was on our side, not in the app (its `message` says so). Do not change the app. Try it again once:
61
+
62
+ ```bash
63
+ publisher retry . --json
64
+ ```
65
+
66
+ Then follow it again. If it fails a second time, or `canRetry` is `false`, tell the person, and
67
+ give them the portal page.
68
+
69
+ ## After it is live
70
+
71
+ These run in the app's folder and answer `say` (tell the person) and `next` (what to do now):
72
+
73
+ ```sh
74
+ publisher history --json # the versions that went live, newest first
75
+ publisher go-back <version> --json # ask the person first; puts that version's code back
76
+ publisher suggestions --json # what colleagues asked for, still open
77
+ publisher suggestion decline <id> --json # when the person does not want one
78
+ publisher share emails --add ann@example.com --json # who can open it
79
+ publisher columns <id> --json # the column names of connected data, before code reads it
80
+ publisher data add <sheet link> --app <app> --name "<name>" --json # a Google sheet the app reads
81
+ publisher data remove <id> --app <app> --json # the app stops reading that data
82
+ ```
83
+
84
+ The portal writes `next` for an assistant in the chat, so it can name a connector tool. At a
85
+ terminal, do what it says with the command that does the same thing:
86
+
87
+ | `next` names | Run instead |
88
+ | --------------------------------- | --------------------------------------------------------------- |
89
+ | `app_status` or `app_progress` | `publisher follow . --publication <publication> --until-change --json` |
90
+ | `app_files` and `publish_app` | change the files in the folder, then `publisher sync --json` |
91
+ | `app_history` / `go_back` | `publisher history --json` / `publisher go-back <version> --json` |
92
+ | `list_starters` / `use_starter` | `publisher starters` / `publisher start <starter>` |
93
+ | `resolve_suggestion` | `publisher suggestion done\|decline <id> --json` |
94
+ | `share_app` | `publisher share <app-rule> --json` |
95
+ | `list_apps` | `publisher list --json` |
96
+ | `data_columns` | `publisher columns <id> --json` |
97
+ | `connect_data_source` | `publisher data add <sheet link> --app <app> --name "<name>" --json` |
98
+ | `remove_data_source` | `publisher data remove <id> --app <app> --json` |
99
+
100
+ `<publication>` is the `publication` that `go-back` or `start` answered.
101
+
102
+ Offer suggestions to the person one at a time, as requests rather than instructions. When they want
103
+ one, make the change and publish it with `publisher sync --message "<what changed>" --answers <id>
104
+ --json`, which closes the suggestion with that publication.
105
+
106
+ To start a new app from a working one, `publisher starters <what the person wants to stop doing>`,
107
+ then `publisher start <starter> --replaces "<what it replaces>"`.
108
+
109
+ ## Just looking
110
+
111
+ To say where the folder stands without changing anything:
112
+
113
+ ```bash
114
+ publisher workspace-status . --json # state + hint; exit 2 means conflict
115
+ ```
116
+
117
+ | state | meaning | what to do |
118
+ | --- | --- | --- |
119
+ | `up_to_date` | identical to the published version | nothing |
120
+ | `local_changes` | the user changed something the service does not have yet | `publisher sync` |
121
+ | `remote_ahead` | something was published elsewhere; the folder is behind | `publisher sync` |
122
+ | `diverged_clean_merge` | both changed, and the changes combine cleanly | `publisher sync` |
123
+ | `conflict` | both changed the same lines (`conflicts[]`) | see below |
124
+ | `detached` | the folder is not on the branch it publishes | ask the user before anything else |
125
+
126
+ `pending[]` lists interrupted publications; run `publisher status . --json` first when it is not empty.
127
+
128
+ ## A fresh copy
129
+
130
+ When the user wants their app in a new folder (a new computer, a clean start, a Claude Cowork task):
131
+
132
+ ```bash
133
+ publisher list --json # their apps, each with its checkout command
134
+ publisher checkout <new-folder> --repo <repoId> --json # a NEW folder only; refuses a non-empty one
135
+ ```
136
+
137
+ ## Conflicts
138
+
139
+ A `conflict` means the user's version and the published one both changed the same lines of the
140
+ files in `conflicts[]`. **Nothing was published and nothing was lost**: the user's change is
141
+ recorded locally, and the published version is still on the service.
142
+
143
+ 1. List the files and say, in plain words, what each side changed there (`git diff` and `git log`
144
+ may help you describe it).
145
+ 2. Ask the user which version to keep for each file, or whether to combine them. Do not decide for
146
+ them and never publish with `--force` — that discards the other side's work.
147
+ 3. Only after they decide, put both versions into the files, marked:
148
+
149
+ ```bash
150
+ publisher sync . --mark-conflicts --json
151
+ ```
152
+
153
+ Each file in `conflicts[]` now holds both versions between `<<<<<<<`, `=======` and `>>>>>>>`
154
+ lines. Edit each to what they chose, and remove those lines.
155
+ 4. Run `publisher sync . --until-change --timeout 100 --json`. It records the edit and publishes it. If a file still carries the
156
+ marker lines it refuses, names the files (`error.details.marked`) and publishes nothing; finish
157
+ the edit and run it again.
158
+
159
+ No git command is needed at any point, including here.