gutterpress 0.11.23-alpha.5 → 0.11.23-alpha.7

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.
Files changed (40) hide show
  1. package/README.md +1 -1
  2. package/dist/api/index.d.ts +4 -2
  3. package/dist/api/index.js +14 -6
  4. package/dist/{build-4qv9wvrx.js → build-w572wq10.js} +7 -7
  5. package/dist/{cli-a35w7wzg.js → cli-31anr0r9.js} +107 -56
  6. package/dist/{cli-pth362d8.js → cli-3cvq3n1c.js} +18 -16
  7. package/dist/{cli-yxfznmsq.js → cli-5ba6bm6z.js} +1 -1
  8. package/dist/{cli-w97xcpag.js → cli-6pv84kf3.js} +4 -4
  9. package/dist/{cli-2t3krcfy.js → cli-eatdqx3z.js} +1 -1
  10. package/dist/{cli-nk0efg2x.js → cli-mmgtqnmr.js} +1 -1
  11. package/dist/{cli-de8ydmm7.js → cli-wyg7qstd.js} +3 -3
  12. package/dist/cli.js +12 -12
  13. package/dist/{doctor-5nh3t346.js → doctor-2f3zqmza.js} +3 -3
  14. package/dist/{ext-nhcep6h6.js → ext-0cgky8n3.js} +7 -7
  15. package/dist/{extension-restore-x3mtn844.js → extension-restore-e7je32pr.js} +4 -4
  16. package/dist/{extension-restore-55kp0ksq.js → extension-restore-vghc58vx.js} +2 -2
  17. package/dist/{index-h6yk5tjx.js → index-cw03e9p4.js} +107 -56
  18. package/dist/{index-9ye22m7r.js → index-fp7xwvpr.js} +3 -3
  19. package/dist/{index-t3jkavdz.js → index-hphcn7th.js} +3 -3
  20. package/dist/{index-agrkfbkv.js → index-nfysshcc.js} +252 -69
  21. package/dist/index.js +14 -6
  22. package/dist/lib/remote-auth/repair.d.ts +2 -2
  23. package/dist/lib/remote-auth/revisions.d.ts +64 -0
  24. package/dist/lib/remote-auth/scorched-earth.d.ts +2 -2
  25. package/dist/lib/remote-auth/sync-messages.d.ts +28 -27
  26. package/dist/lib/remote-auth/sync-types.d.ts +3 -0
  27. package/dist/lib/remote-auth/sync.d.ts +7 -8
  28. package/dist/lib/remote-auth/transport.d.ts +8 -1
  29. package/dist/lib/source-provider.d.ts +80 -35
  30. package/dist/{new-5a4w2vkh.js → new-88rkrv71.js} +10 -10
  31. package/dist/{plugins-mm8270tn.js → plugins-3aj0wc5h.js} +1 -1
  32. package/dist/{plugins-cfzf26b8.js → plugins-sprxsz5d.js} +3 -3
  33. package/dist/{preflight-jma71n0j.js → preflight-11dg1qkk.js} +7 -7
  34. package/dist/{preview-kmx4h7gv.js → preview-nftp782j.js} +7 -7
  35. package/dist/{publish-62843020.js → publish-6tgxfck9.js} +7 -7
  36. package/dist/render.js +2 -2
  37. package/dist/{source-provider-knmcam50.js → source-provider-n7vehh6t.js} +15 -3
  38. package/dist/{source-provider-98k5deda.js → source-provider-tgzet3j5.js} +15 -3
  39. package/dist/{validate-vvmrd85g.js → validate-pktqrye5.js} +7 -7
  40. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -32,6 +32,7 @@ import {
32
32
  connectGoogleDrive,
33
33
  connectPublishProvider,
34
34
  defaultConfigDir,
35
+ deleteRevision,
35
36
  deleteSnippet,
36
37
  describeVersions,
37
38
  diagnoseProjectRemote,
@@ -79,6 +80,7 @@ import {
79
80
  readPageSetup,
80
81
  readPublishSettings,
81
82
  refreshRemoteCopies,
83
+ renameRevision,
82
84
  repairOnlineBackup,
83
85
  reportMissingTools,
84
86
  requireGoogleClientCredentials,
@@ -117,7 +119,7 @@ import {
117
119
  substituteVariables,
118
120
  syncProject,
119
121
  testRemoteAccess
120
- } from "./index-agrkfbkv.js";
122
+ } from "./index-nfysshcc.js";
121
123
  import {
122
124
  DEFAULT_NPM_REGISTRY,
123
125
  MANIFEST_FILENAMES,
@@ -147,7 +149,7 @@ import {
147
149
  setExtensionEnabled,
148
150
  updateExtensions,
149
151
  validateProjectExtensions
150
- } from "./index-t3jkavdz.js";
152
+ } from "./index-hphcn7th.js";
151
153
  import {
152
154
  BUNDLED_EXTENSIONS,
153
155
  EXTENSION_MANIFEST_FILENAME,
@@ -163,7 +165,7 @@ import {
163
165
  pathEscapesFolder,
164
166
  readExtensionMeta,
165
167
  resolveExtension
166
- } from "./index-9ye22m7r.js";
168
+ } from "./index-fp7xwvpr.js";
167
169
  import"./index-ht1bcqdd.js";
168
170
  import {
169
171
  BUILD_DIAGNOSTIC_CODES
@@ -184,14 +186,16 @@ import {
184
186
  RESTORE_BACKUP_MESSAGE,
185
187
  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
186
188
  countUnversionedChanges,
189
+ createRevision,
187
190
  isNoChangesError,
188
- listLocalBranches,
191
+ listRevisions,
189
192
  providerFor,
190
193
  resolveLogger,
191
194
  restoreVersionWithBackup,
195
+ revisionNameFrom,
192
196
  switchBranch,
193
197
  whenGitIdle
194
- } from "./index-h6yk5tjx.js";
198
+ } from "./index-cw03e9p4.js";
195
199
  import {
196
200
  EXTENSIONS_DIR
197
201
  } from "./index-5x42amh8.js";
@@ -236,6 +240,7 @@ export {
236
240
  ruleRiskyProps,
237
241
  ruleRemoteUrls,
238
242
  revokeGoogleCredential,
243
+ revisionNameFrom,
239
244
  restoreVersionWithBackup,
240
245
  restorePinnedExtensions,
241
246
  restoreFailureMessage,
@@ -257,6 +262,7 @@ export {
257
262
  repoRootForSource,
258
263
  repairOnlineBackup,
259
264
  reorderExtensions,
265
+ renameRevision,
260
266
  removeExtension,
261
267
  refreshRemoteCopies,
262
268
  readyProbeExpr,
@@ -280,6 +286,7 @@ export {
280
286
  loadManifestWithPath,
281
287
  loadManifest,
282
288
  listSnippets,
289
+ listRevisions,
283
290
  listRepoBooks,
284
291
  listPublishProviders,
285
292
  listPublishAccounts,
@@ -290,7 +297,6 @@ export {
290
297
  listMergedSnippets,
291
298
  listMarkerComponents,
292
299
  listLocationVariants,
293
- listLocalBranches,
294
300
  listGitHubRepositories,
295
301
  listGitHubBranches,
296
302
  listCustomTemplates,
@@ -331,7 +337,9 @@ export {
331
337
  describeVersions,
332
338
  describeExtension,
333
339
  deleteSnippet,
340
+ deleteRevision,
334
341
  defaultConfigDir,
342
+ createRevision,
335
343
  countUnversionedChanges,
336
344
  connectPublishProvider,
337
345
  connectGoogleDrive,
@@ -1,6 +1,6 @@
1
1
  import type { SyncOutcome, SyncProjectOptions } from "./sync-types.ts";
2
- /** Message recorded on the version a repair saves. */
3
- export declare const REPAIR_SNAPSHOT_MESSAGE = "Repaired online backup";
2
+ /** Message recorded on the version a repair saves (older history says "Repaired online backup"). */
3
+ export declare const REPAIR_SNAPSHOT_MESSAGE = "Repaired the online copy";
4
4
  export interface RepairOnlineBackupOptions extends Pick<SyncProjectOptions, "projectDir" | "credential" | "tokenStore" | "authorName" | "authorEmail" | "logFile" | "httpClient"> {
5
5
  /**
6
6
  * Where the old `.git` and the fresh download go — chosen by the host,
@@ -0,0 +1,64 @@
1
+ import { defaultGitHttp } from "./git-http.ts";
2
+ import type { HostCredential, TokenStore } from "./token-store.ts";
3
+ /** How the online copy is reached: the same options `refreshRemoteCopies` takes. */
4
+ interface OnlineOptions {
5
+ credential?: HostCredential;
6
+ tokenStore?: TokenStore;
7
+ httpClient?: typeof defaultGitHttp;
8
+ }
9
+ export interface RenameRevisionOptions extends OnlineOptions {
10
+ projectDir: string;
11
+ from: string;
12
+ /** The new name as typed; spaces become hyphens. */
13
+ to: string;
14
+ }
15
+ export interface DeleteRevisionOptions extends OnlineOptions {
16
+ projectDir: string;
17
+ name: string;
18
+ /** Also remove it from the online copy (when it is there); default: this computer only. */
19
+ everywhere?: boolean;
20
+ /** Delete even though the revision holds versions found nowhere else. */
21
+ discard?: boolean;
22
+ }
23
+ /**
24
+ * Rename a revision. The open revision may be renamed (the book stays open on it).
25
+ *
26
+ * One that is also in the online copy is renamed there too, in an order that
27
+ * never loses anything, so each failure leaves a known state:
28
+ * 1. send the new name online — a failure leaves everything as it was;
29
+ * 2. remove the old name online — a failure removes the new name again, so
30
+ * everything is as it was; only if that can't be done either (the network
31
+ * dropped between the two) does the online copy keep both names, which the
32
+ * error says;
33
+ * 3. rename on this computer — only a local failure is possible here, and it
34
+ * leaves the online copy renamed and this computer under the old name, still
35
+ * listed (the new name shows as online-only).
36
+ * A revision kept only in the online copy is renamed there (steps 1 and 2), with
37
+ * the tracking ref (what this computer last heard) standing in for its tip.
38
+ * Offline or a rejected sign-in: nothing is renamed, anywhere.
39
+ */
40
+ export declare function renameRevision(options: RenameRevisionOptions): Promise<{
41
+ current: string | null;
42
+ name: string;
43
+ }>;
44
+ /**
45
+ * Delete a revision. Never the open one. By default only on this computer
46
+ * (a copy in the online copy stays, and shows as online-only); `everywhere`
47
+ * removes it from the online copy first, then here — a failure online leaves
48
+ * everything as it was, a failure here leaves it removed online and still
49
+ * listed on this computer. A revision kept only in the online copy has nothing
50
+ * here to remove: it is deleted from the online copy, as `everywhere` does, with
51
+ * the tracking ref (what this computer last heard) standing in for its tip.
52
+ *
53
+ * Nothing found only in the revision is deleted without a second look: when it
54
+ * holds versions found in no other revision (and, unless deleted everywhere, not
55
+ * in the online copy), the first call returns how many and deletes nothing; the
56
+ * caller asks and calls again with `discard: true`.
57
+ */
58
+ export declare function deleteRevision(options: DeleteRevisionOptions): Promise<{
59
+ deleted: true;
60
+ } | {
61
+ deleted: false;
62
+ versionsOnlyHere: number;
63
+ }>;
64
+ export {};
@@ -1,12 +1,12 @@
1
1
  import type { SyncProjectOptions } from "./sync-types.ts";
2
2
  export interface ScorchedEarthOptions extends Pick<SyncProjectOptions, "projectDir" | "credential" | "tokenStore" | "logFile" | "httpClient"> {
3
- /** Where the full copy of the folder goes — OUTSIDE the folder. Kept indefinitely. */
3
+ /** Where the safety folder goes — OUTSIDE the book's folder. Kept indefinitely. */
4
4
  backupDir: string;
5
5
  }
6
6
  export interface ScorchedEarthResult {
7
7
  /** The folder that was reset (the repo root of `projectDir`). */
8
8
  dir: string;
9
- /** Where the full copy of the folder (old `.git` included) was kept. */
9
+ /** Where the safety folder (the old folder, `.git` included) was kept. */
10
10
  backupDir: string;
11
11
  /** The branch the fresh copy has checked out. */
12
12
  branch?: string;
@@ -1,39 +1,40 @@
1
1
  /**
2
- * Author-language copy for sync (never raw git words). Extracted from sync.ts
3
- * so the transport and orchestrator modules share ONE source of these
4
- * strings — their exact wording is part of the observable contract (the host
5
- * renders them verbatim).
2
+ * Author-language copy for backing up and getting the latest — never sync,
3
+ * push, pull, repository, branch or snapshot. Extracted from sync.ts so the
4
+ * transport and orchestrator modules share ONE source of these strings — their
5
+ * exact wording is part of the observable contract (the host renders them
6
+ * verbatim).
6
7
  */
7
- export declare const MSG_UP_TO_DATE = "Everything is in sync.";
8
- export declare const MSG_UP_TO_DATE_PULLED = "Everything is in sync. The latest online changes were downloaded to this computer.";
8
+ export declare const MSG_UP_TO_DATE = "You're up to date with the online copy.";
9
+ export declare const MSG_UP_TO_DATE_PULLED = "You're up to date. The latest changes from the online copy were downloaded to this computer.";
9
10
  export declare const MSG_SYNCED = "Your changes are online.";
10
11
  export declare const MSG_SYNCED_MERGED = "Your changes are online, combined with changes from the online copy.";
11
- export declare const MSG_OFFLINE = "Your changes are saved on this computer. Gutterpress couldn't reach the online repository \u2014 try syncing again when you're back online.";
12
- export declare const MSG_AUTH = "The online repository didn't accept the saved connection. Reconnect and try again.";
13
- export declare const MSG_INSECURE_TRANSPORT = "This book's online address isn't secure, so the saved connection wasn't sent \u2014 connections are never sent over an insecure address. Switch the address to a secure one (starting with https), or to a local loopback address for a server on this computer, to sync.";
14
- export declare const MSG_BUSY = "The online copy is changing very quickly right now. Your work is saved on this computer \u2014 try Sync again in a moment.";
12
+ export declare const MSG_OFFLINE = "Your changes are saved on this computer. Gutterpress couldn't reach the online copy \u2014 try again when you're back online.";
13
+ export declare const MSG_AUTH = "The online copy didn't accept the saved sign-in. Sign in again and try again.";
14
+ export declare const MSG_INSECURE_TRANSPORT = "This book's online copy is at an address that isn't secure, so the saved sign-in wasn't sent \u2014 sign-ins are never sent over an insecure address. Switch the address to a secure one (starting with https), or to a local loopback address for a server on this computer, to back up.";
15
+ export declare const MSG_BUSY = "The online copy is changing very quickly right now. Your work is saved on this computer \u2014 try again in a moment.";
15
16
  /**
16
- * The book's own version history is unreadable — a damaged or missing
17
- * `.git`. Says the three things that are actually true and useful: the writing
18
- * is safe, the HISTORY is what broke, and (sync always has a remote, so this
19
- * always applies here) Repair online backup is the way back.
17
+ * The book's own versions are unreadable — a damaged or missing `.git`. Says
18
+ * the three things that are actually true and useful: the writing is safe, the
19
+ * VERSIONS are what broke, and (backing up always has an online copy, so this
20
+ * always applies here) "Repair the online copy" is the way back.
20
21
  */
21
- export declare const MSG_HISTORY_UNREADABLE = "This book's version history can't be read, so syncing can't continue. Your writing is safe \u2014 every file is still here on this computer. Use Repair online backup (in Where your work is kept) to get history and syncing working again.";
22
- export declare const MSG_UNRELATED = "This book and the online copy have no history in common, so they can't be combined. Either the online address points at a different book, or this book's own history was lost and started over. Your writing is safe \u2014 every file is still here on this computer. Check the online address; if it is correct, use Repair online backup (in Where your work is kept).";
23
- export declare const MSG_NO_REMOTE = "This book isn't connected to an online repository yet.";
24
- export declare const MSG_SSH_REMOTE = "This book's online address uses SSH (git@\u2026), which Gutterpress can't sync to. Switch it to the web (HTTPS) address to sync from here.";
25
- export declare const MSG_NO_BRANCH = "This book's version history isn't on a named branch, so it can't be synced right now.";
26
- /** Message recorded on the automatic pre-sync snapshot (D5 invariant).
27
- * Pre-0.10.1 history carries the old spelling "Snapshot before syncing". */
28
- export declare const SYNC_SNAPSHOT_MESSAGE = "Automatic backup of your work";
22
+ export declare const MSG_HISTORY_UNREADABLE = "This book's versions can't be read, so backing up can't continue. Your writing is safe \u2014 every file is still here on this computer. Use \"Repair the online copy\" (in Book setup \u2192 Online copy) to get versions and backing up working again.";
23
+ export declare const MSG_UNRELATED = "This book and the online copy have no versions in common, so they can't be combined. Either the online copy's address points at a different book, or this book's own versions were lost and started over. Your writing is safe \u2014 every file is still here on this computer. Check the online copy's address; if it is correct, use \"Repair the online copy\" (in Book setup \u2192 Online copy).";
24
+ export declare const MSG_NO_REMOTE = "This book doesn't have an online copy yet.";
25
+ export declare const MSG_SSH_REMOTE = "This book's online copy uses an SSH address (git@\u2026), which Gutterpress can't back up to. Switch it to the web (HTTPS) address to back up from here.";
26
+ export declare const MSG_NO_BRANCH = "This book isn't on a named revision, so it can't be backed up right now.";
27
+ /** Message recorded on the automatic version saved before backing up (D5 invariant).
28
+ * Older history carries the spellings "Automatic backup of your work" and,
29
+ * before 0.10.1, "Snapshot before syncing". */
30
+ export declare const SYNC_SNAPSHOT_MESSAGE = "Automatic version before backing up";
29
31
  /**
30
32
  * Message recorded when an edit reached disk while the fetch was in flight —
31
- * after the pre-sync snapshot, before the merge (see the re-snapshot in
32
- * `syncProject`). Distinct wording so the race is legible in history; the
33
- * copy is already writer-voiced, so it deliberately stays unchanged (every
34
- * rename permanently grows the timeline's superseded-spelling list).
33
+ * after the pre-backup version, before the merge (see the re-snapshot in
34
+ * `syncProject`). Distinct wording so the race is legible in history. Older
35
+ * history carries the spelling "Saved the edit you made while syncing".
35
36
  */
36
- export declare const SYNC_LATE_EDIT_MESSAGE = "Saved the edit you made while syncing";
37
+ export declare const SYNC_LATE_EDIT_MESSAGE = "Saved the edit you made while backing up";
37
38
  /**
38
39
  * The keep-both sibling contract, kept HERE rather than in converge-merge.ts
39
40
  * because every consumer needs it and converge-merge pulls in isomorphic-git:
@@ -54,6 +54,9 @@ export type SyncOutcome = {
54
54
  * and then hold the push — the converge report still surfaces here. */
55
55
  combinedFiles?: string[];
56
56
  keptBothFiles?: KeptBothFile[];
57
+ /** A pull-merge-only pass that held the push: this computer has versions
58
+ * the online copy lacks. Never set when the tips already matched. */
59
+ pushDeferred?: true;
57
60
  } | {
58
61
  status: "auth";
59
62
  message: string;
@@ -29,26 +29,25 @@ export declare function isUnrelatedHistories(e: unknown): boolean;
29
29
  */
30
30
  export declare function syncProject(options: SyncProjectOptions): Promise<SyncOutcome>;
31
31
  /**
32
- * Fetch every branch the remote has, so the project's copy list reflects what
32
+ * Fetch every branch the remote has, so the book's revision list reflects what
33
33
  * exists online rather than only what this clone happened to fetch before.
34
34
  *
35
- * The copy picker reads refs off disk (`listLocalBranches`). That makes a
36
- * branch pushed from anywhere else — another machine, the web UI, an agent
37
- * opening a PR — invisible here until someone runs `git fetch` in a terminal,
38
- * which is precisely the thing this app exists to avoid. So the picker calls
39
- * this first.
35
+ * `listRevisions` reads refs off disk. That makes a branch pushed from anywhere
36
+ * else — another machine, the web UI, an agent opening a PR — invisible here
37
+ * until someone runs `git fetch` in a terminal, which is precisely the thing
38
+ * this app exists to avoid. So the revision list calls this first.
40
39
  *
41
40
  * Unlike `fetchRemoteTip` this deliberately does NOT use `singleBranch`: the
42
41
  * whole point is the branches we do not have yet. It only ever writes
43
42
  * remote-tracking refs (`refs/remotes/<remote>/*`) — no local branch, no
44
43
  * working-tree change, no merge — so it is safe to call on a dirty tree.
45
44
  * `prune` drops tracking refs for branches deleted online, so the list cannot
46
- * offer a copy that is gone.
45
+ * offer a revision that is gone.
47
46
  *
48
47
  * Best-effort by contract: offline, unauthenticated, or no remote at all
49
48
  * resolves to `{ refreshed: false, reason }` rather than throwing. A stale
50
49
  * list beats an error dialog over a control the author did not explicitly ask
51
- * to sync — but it reports WHY, because a picker that silently omits copies
50
+ * to sync — but it reports WHY, because a list that silently omits revisions
52
51
  * is indistinguishable from a broken one, which is the bug this whole
53
52
  * function exists to fix.
54
53
  */
@@ -107,8 +107,15 @@ export declare function currentBranchOrThrow(dir: string): Promise<string>;
107
107
  export declare function guardTrackingRef<T>(dir: string, ref: string, cache: GitCache, fn: () => Promise<T>): Promise<T>;
108
108
  /**
109
109
  * Fetch the tracked branch's online tip. Returns `null` when the online
110
- * repository has no such branch yet (a freshly created empty repo).
110
+ * copy has no such revision yet (a freshly created empty repo, or a revision
111
+ * started on this computer).
111
112
  */
112
113
  export declare function fetchRemoteTip(dir: string, branch: string, transport: RemoteTransport, http: typeof httpNode, cache: GitCache): Promise<string | null>;
114
+ /**
115
+ * The online copy's tip for `branch` as the server advertises it right now.
116
+ * Reads refs only (`listServerRefs`: no objects downloaded, no history walked,
117
+ * nothing written); `undefined` when the online copy has no such revision.
118
+ */
119
+ export declare function serverTip(transport: RemoteTransport, branch: string, http: typeof httpNode): Promise<string | undefined>;
113
120
  /** First 8 chars of an oid for diagnostic log lines (null-safe). */
114
121
  export declare function short(oid: string | null | undefined): string;
@@ -8,7 +8,7 @@ import type { ProjectCapabilities, ProjectSource } from "./project-source.ts";
8
8
  type GitCache = Record<string, unknown>;
9
9
  /** One entry in a project's version history (a Git commit, abstracted). */
10
10
  export interface SnapshotEntry {
11
- /** Opaque revision id (a commit SHA for the local-git provider). */
11
+ /** Opaque version id (a commit SHA for the local-git provider). */
12
12
  id: string;
13
13
  /** Author-supplied or auto-generated snapshot message. */
14
14
  message: string;
@@ -102,6 +102,8 @@ export interface SourceProvider {
102
102
  listHistoryPage(projectDir: string, options?: ListHistoryOptions): Promise<HistoryPage>;
103
103
  restore(options: RestoreSnapshotOptions): Promise<void>;
104
104
  }
105
+ /** What every version operation says about a plain folder. */
106
+ export declare const NO_VERSION_HISTORY = "This book isn't keeping version history yet. Turn on version history first.";
105
107
  /**
106
108
  * Run `fn` exclusively per resolved project dir (FIFO promise chaining).
107
109
  * Exported for the remote-clone surface (#15) so clone/fetch operations share
@@ -250,13 +252,13 @@ export interface RestoreVersionResult {
250
252
  backupId?: string;
251
253
  }
252
254
  /** Message recorded on the automatic pre-restore safety snapshot. */
253
- export declare const RESTORE_BACKUP_MESSAGE = "Automatic backup before restoring an earlier version";
255
+ export declare const RESTORE_BACKUP_MESSAGE = "Automatic version before restoring";
254
256
  /**
255
257
  * Message recorded on every host-scheduled automatic snapshot. The desktop's
256
258
  * history UI groups consecutive entries carrying EXACTLY this message, so the
257
259
  * string is a contract — change it only with a matching UI update.
258
260
  */
259
- export declare const AUTO_SNAPSHOT_MESSAGE = "Automatic snapshot";
261
+ export declare const AUTO_SNAPSHOT_MESSAGE = "Automatic version";
260
262
  /**
261
263
  * Restore the working tree to a prior snapshot SAFELY (#13): if the current
262
264
  * state has unsaved-to-history changes, an automatic safety snapshot is
@@ -269,28 +271,30 @@ export declare const AUTO_SNAPSHOT_MESSAGE = "Automatic snapshot";
269
271
  * folder has no version history.
270
272
  */
271
273
  export declare function restoreVersionWithBackup(options: RestoreVersionOptions): Promise<RestoreVersionResult>;
272
- /** The project's copies (git branches) and which one is currently open. */
273
- export interface LocalBranches {
274
- /** Name of the branch HEAD points to, or `null` on a detached/unborn HEAD. */
274
+ /**
275
+ * One revision (git branch) of a book, as the author sees it (#448): where it
276
+ * is kept, and whether this computer has versions the online copy lacks.
277
+ */
278
+ export interface Revision {
279
+ name: string;
280
+ /** The revision open on this computer. */
281
+ current: boolean;
282
+ /** On this computer and in the online copy; only on this computer; only in the online copy. */
283
+ where: "online" | "this-computer" | "online-only";
284
+ /** `where === "online"` and this computer has versions the online copy lacks (refs only, no network). */
285
+ notBackedUp: boolean;
286
+ }
287
+ /** The book's revisions, sorted by name, and which one is open (`null` on a detached/unborn HEAD). */
288
+ export interface RevisionList {
275
289
  current: string | null;
276
- /**
277
- * Every copy the project can switch to, sorted: local branches
278
- * (`refs/heads/*`) plus copies that so far exist only on a remote.
279
- */
280
- branches: string[];
281
- /**
282
- * The subset of {@link branches} with no local ref yet. Switching to one of
283
- * these creates the local copy from the remote and tracks it; the UI uses
284
- * this only to say so before it happens.
285
- */
286
- remoteOnly: string[];
290
+ revisions: Revision[];
287
291
  }
288
292
  /** Inputs for {@link switchBranch}. */
289
293
  export interface SwitchBranchOptions {
290
294
  projectDir: string;
291
295
  /** Branch name to check out — local, or one that so far exists only on a remote. */
292
296
  branch: string;
293
- /** Identity recorded on the automatic pre-switch safety snapshot, if one is taken. */
297
+ /** Identity recorded on the automatic pre-switch safety version, if one is taken. */
294
298
  authorName?: string;
295
299
  authorEmail?: string;
296
300
  }
@@ -303,34 +307,75 @@ export interface SwitchBranchResult {
303
307
  * content of (a diff of the old HEAD's tree against the new branch's tree,
304
308
  * computed before the checkout runs). The host uses this to drop crash-
305
309
  * recovery drafts for these paths — see recovery.ts's header: a draft taken
306
- * on the copy just left behind must never be offered over a DIFFERENT copy's
307
- * version of the same file.
310
+ * on the revision just left behind must never be offered over a DIFFERENT
311
+ * revision's version of the same file.
308
312
  */
309
313
  changedFiles: string[];
310
314
  }
311
- /** Snapshot message for the safety snapshot {@link switchBranch} takes before checking out, when the working tree has changes. */
312
- export declare const SWITCH_BRANCH_SNAPSHOT_MESSAGE = "Saved before switching copy";
315
+ /** Version message for the safety version {@link switchBranch} and {@link createRevision} save when the working tree has unsaved work. */
316
+ export declare const SWITCH_BRANCH_SNAPSHOT_MESSAGE = "Saved before switching revision";
317
+ /** Where each revision of a book is, read from refs only (no network, no history walk). */
318
+ export interface RevisionRefs {
319
+ /** The revision HEAD points to, or `null` on a detached/unborn HEAD. */
320
+ current: string | null;
321
+ /** Revision name → tip, for `refs/heads/*`. */
322
+ local: Map<string, string>;
323
+ /** Revision name → the online copy's tip as this computer last saw it, for the sync remote's tracking refs. Empty without a remote. */
324
+ online: Map<string, string>;
325
+ }
326
+ export declare function readRevisionRefs(dir: string): Promise<RevisionRefs>;
327
+ /**
328
+ * True when every version of `tip` is also in `inTip` (it is `inTip`, or an
329
+ * earlier version of it). Tips are compared first; the walk is bounded (see the
330
+ * note in remote-auth/sync.ts on unbounded `isDescendent` walks), and a walk
331
+ * that runs out or meets a missing object answers false.
332
+ */
333
+ export declare function isContained(dir: string, tip: string, inTip: string, cache: GitCache): Promise<boolean>;
313
334
  /**
314
- * List the project's copies (git branches) and which one is open, for a
315
- * `local-git-folder` project. Returns `null` for any other source type —
316
- * there is nothing to switch between, and the caller (the Saving settings row)
317
- * hides the whole control on `null` rather than showing an error.
335
+ * The book's revisions and where each is kept, for a `local-git-folder`
336
+ * project; `null` for any other source (nothing to switch between — the caller
337
+ * hides the whole control rather than showing an error).
318
338
  *
319
- * Copies that exist only on a remote are included: they are as real to the
320
- * author as the local ones, and {@link switchBranch} creates the local branch
321
- * on the way in.
339
+ * Reads refs only: "online" is what this computer last heard from the online
340
+ * copy (the refresh fetch keeps it current), so this never touches the network.
322
341
  */
323
- export declare function listLocalBranches(dir: string): Promise<LocalBranches | null>;
342
+ export declare function listRevisions(dir: string): Promise<RevisionList | null>;
343
+ /** A revision name as the author typed it, made usable: trimmed, spaces become hyphens. */
344
+ export declare function revisionNameFrom(input: string): string;
345
+ /**
346
+ * Refuse, in plain words, a name a new revision can't have: empty, one git
347
+ * refuses, or one already used on this computer or in the online copy (letters
348
+ * compared without case, so two names never collide on a case-insensitive disk).
349
+ * `name` is already through {@link revisionNameFrom}.
350
+ */
351
+ export declare function assertFreeRevisionName(repoDir: string, name: string): Promise<void>;
352
+ /** Inputs for {@link createRevision}. */
353
+ export interface CreateRevisionOptions {
354
+ projectDir: string;
355
+ /** The name as typed; spaces become hyphens (see {@link revisionNameFrom}). */
356
+ name: string;
357
+ /** Identity recorded on the safety version, if one is taken. */
358
+ authorName?: string;
359
+ authorEmail?: string;
360
+ }
361
+ /**
362
+ * Start a new revision from what the book is now, and open it. Unsaved work is
363
+ * saved as a version first, so the new revision starts from it. The revision
364
+ * goes online with the next backup, which sends the open revision.
365
+ */
366
+ export declare function createRevision(options: CreateRevisionOptions): Promise<{
367
+ current: string;
368
+ }>;
324
369
  /**
325
- * Switch the project's working tree to another local copy (git branch).
370
+ * Switch the project's working tree to another revision (git branch).
326
371
  *
327
372
  * Safety, in order (see the issue's "what the switch has to take care of"):
328
- * 1. If the working tree has uncommitted changes, snapshot them first (so
329
- * nothing the author typed is lost) and tolerate the expected
330
- * "no changes" rejection when it doesn't.
373
+ * 1. If the working tree has unsaved work, save a version of it first (so
374
+ * nothing the author typed is lost); the expected "nothing new" rejection
375
+ * is tolerated.
331
376
  * 2. Check out the target branch WITHOUT `force` — isomorphic-git then
332
377
  * refuses (CheckoutConflictError) rather than silently overwriting a
333
- * working-tree file that moved after the snapshot above, which is
378
+ * working-tree file that moved after the version above, which is
334
379
  * reported as a friendly error instead of a forced checkout.
335
380
  * 3. Report every path the checkout touched so the host can drop stale
336
381
  * crash-recovery drafts for them (see {@link SwitchBranchResult}).
@@ -3,10 +3,10 @@ import {
3
3
  EXTENSION_KINDS,
4
4
  scaffoldExtension,
5
5
  scaffoldProject
6
- } from "./cli-pth362d8.js";
6
+ } from "./cli-3cvq3n1c.js";
7
7
  import {
8
8
  resolveGhostscript
9
- } from "./cli-nk0efg2x.js";
9
+ } from "./cli-mmgtqnmr.js";
10
10
  import"./cli-ht1bcqdd.js";
11
11
  import"./cli-58fsk6d7.js";
12
12
  import"./cli-5crpmz42.js";
@@ -14,7 +14,7 @@ import"./cli-eyyggect.js";
14
14
  import {
15
15
  isToolAvailable
16
16
  } from "./cli-asap4t1z.js";
17
- import"./cli-a35w7wzg.js";
17
+ import"./cli-31anr0r9.js";
18
18
  import"./cli-v5mp7a6q.js";
19
19
  import {
20
20
  PRESET_IDS,
@@ -22,15 +22,15 @@ import {
22
22
  TARGET_IDS,
23
23
  loadManifest,
24
24
  resolveConfig
25
- } from "./cli-w97xcpag.js";
26
- import"./cli-de8ydmm7.js";
27
- import"./cli-2t3krcfy.js";
25
+ } from "./cli-6pv84kf3.js";
26
+ import"./cli-wyg7qstd.js";
27
+ import"./cli-eatdqx3z.js";
28
28
  import {
29
29
  UsageError,
30
30
  rejectExtraPositionals,
31
31
  rejectUnknownFlags
32
32
  } from "./cli-d8xjns66.js";
33
- import"./cli-yxfznmsq.js";
33
+ import"./cli-5ba6bm6z.js";
34
34
  import {
35
35
  EXIT_CODES
36
36
  } from "./cli-46ycxe6r.js";
@@ -92,7 +92,7 @@ var newArgs = {
92
92
  },
93
93
  git: {
94
94
  type: "boolean",
95
- description: "Initialise local version history (default: true; use --no-git to skip)",
95
+ description: "Keep version history on this computer (default: true; use --no-git to skip)",
96
96
  default: true
97
97
  }
98
98
  };
@@ -262,9 +262,9 @@ var new_default = defineCommand({
262
262
  console.log(` publish targets: ${written.targets.length > 0 ? written.targets.join(", ") : "none"}`);
263
263
  console.log(` start writing in: ${result.openFile}`);
264
264
  if (result.versionHistory === "local-git") {
265
- console.log(" version history: enabled (local snapshots)");
265
+ console.log(" version history: on (kept on this computer)");
266
266
  } else if (result.versionHistoryError) {
267
- console.log(` version history: not enabled (${result.versionHistoryError})`);
267
+ console.log(` version history: not on (${result.versionHistoryError})`);
268
268
  }
269
269
  const neededTools = [
270
270
  ...new Set(written.targets.flatMap((id) => TARGETS[id]?.requiredTools ?? []))
@@ -8,7 +8,7 @@ import {
8
8
  loadPlugins,
9
9
  loadPluginsWithCss,
10
10
  loadPublishFunction
11
- } from "./index-9ye22m7r.js";
11
+ } from "./index-fp7xwvpr.js";
12
12
  import"./index-5x42amh8.js";
13
13
  import"./index-37x76zdn.js";
14
14
  export {
@@ -8,9 +8,9 @@ import {
8
8
  loadPlugins,
9
9
  loadPluginsWithCss,
10
10
  loadPublishFunction
11
- } from "./cli-de8ydmm7.js";
12
- import"./cli-2t3krcfy.js";
13
- import"./cli-yxfznmsq.js";
11
+ } from "./cli-wyg7qstd.js";
12
+ import"./cli-eatdqx3z.js";
13
+ import"./cli-5ba6bm6z.js";
14
14
  import"./cli-y28j019d.js";
15
15
  import"./cli-37x76zdn.js";
16
16
  export {
@@ -1,28 +1,28 @@
1
1
  import {
2
2
  executeValidation,
3
3
  reportMissingTools
4
- } from "./cli-pth362d8.js";
5
- import"./cli-nk0efg2x.js";
4
+ } from "./cli-3cvq3n1c.js";
5
+ import"./cli-mmgtqnmr.js";
6
6
  import"./cli-ht1bcqdd.js";
7
7
  import"./cli-58fsk6d7.js";
8
8
  import"./cli-5crpmz42.js";
9
9
  import"./cli-eyyggect.js";
10
10
  import"./cli-asap4t1z.js";
11
- import"./cli-a35w7wzg.js";
11
+ import"./cli-31anr0r9.js";
12
12
  import"./cli-v5mp7a6q.js";
13
13
  import {
14
14
  publishTargetFor
15
- } from "./cli-w97xcpag.js";
16
- import"./cli-de8ydmm7.js";
15
+ } from "./cli-6pv84kf3.js";
16
+ import"./cli-wyg7qstd.js";
17
17
  import {
18
18
  log
19
- } from "./cli-2t3krcfy.js";
19
+ } from "./cli-eatdqx3z.js";
20
20
  import {
21
21
  UsageError,
22
22
  rejectExtraPositionals,
23
23
  rejectUnknownFlags
24
24
  } from "./cli-d8xjns66.js";
25
- import"./cli-yxfznmsq.js";
25
+ import"./cli-5ba6bm6z.js";
26
26
  import {
27
27
  BuildError,
28
28
  EXIT_CODES