@estiva-app/interop 0.46.0 → 0.48.0

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.46.0",
3
+ "version": "0.48.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/folders.ts CHANGED
@@ -1,13 +1,21 @@
1
1
  /**
2
- * Folder writes, planned — RFC 0.4 §4, FOL-4.
2
+ * Folder writes, planned — SPEC §3.3. Every app gets exactly these operations,
3
+ * and these planners are the reference implementation: an app that does not
4
+ * call them MUST produce the same events in the same order.
3
5
  *
4
- * Every change to a Folder is one or more events published in order, and which
5
- * events depends on one fact the relay will not check for you: **whether the
6
- * Folder has a `kind:30890` yet.** `handle_folder_command` computes the next
7
- * state from the existing one, and a Folder with no state has none — so any
8
- * `kind:1852` against it emits state listing only what that command named, and
9
- * everything filed in the Folder by `h` stops being listed on every surface
10
- * (peek#192). Nothing fails; the Folder just looks emptied.
6
+ * Every change to a Folder is one or more events published in order. Where a
7
+ * planner lists a file, it depends on one fact the relay will not check for
8
+ * you: **whether the Folder has a `kind:30890` yet.** `handle_folder_command`
9
+ * computes the next state from the existing one, and a group with no state has
10
+ * none — so any `kind:1852` against it emits state listing only what that
11
+ * command named, and everything filed there by `h` stops being listed on every
12
+ * surface (peek#192). Nothing fails; the group just looks emptied.
13
+ *
14
+ * A group with no state is not a Folder (SPEC §3), and §3.3's operations are
15
+ * not run on one. The `hasState: false` branches below are kept for §7.3's
16
+ * `listed` rule, which still applies to an object filed in such a group: a
17
+ * file placed or unlisted there is reached by containment and needs no
18
+ * command.
11
19
  *
12
20
  * That is why these are here rather than in each app. Peek learned it once per
13
21
  * writer — rename, start a topic, delete a file — and its move never learned it
@@ -27,31 +35,49 @@
27
35
  * assumes the earlier ones were accepted. What a refusal part-way through
28
36
  * *means* — "created but not listed", "added but still in the old one" — is
29
37
  * each app's to say, and the index of the refused event is enough to say it.
38
+ *
39
+ * ## A command never carries a name
40
+ *
41
+ * A Folder's title is the `name` of its `kind:39000` and only that (§3.2). The
42
+ * relay lets only the channel's owners and admins change that, while any
43
+ * member may send a `kind:1852` — so a name on a command would let anyone
44
+ * retitle the Folder for every reader that believed it.
30
45
  */
31
46
  import {
32
47
  buildCreateChannel,
48
+ buildDeleteChannel,
33
49
  buildEditChannelMetadata,
34
50
  buildFolderCommand,
35
51
  type ChannelVisibility,
36
52
  type UnsignedEvent,
37
53
  } from '@estiva-app/protocol'
38
54
 
39
- /** A Folder as a write needs it: which one, and whether the relay holds state for it. */
55
+ /** A Folder as a write needs it: which one, and what a read said about it. */
40
56
  export interface FolderRef {
41
57
  id: string
42
58
  /** `FolderSummary.hasState` / `FolderContents.hasState`, from a read — never a guess. */
43
59
  hasState: boolean
60
+ /**
61
+ * `FolderSummary.private`: the Folder's relay-signed `kind:39000` carries
62
+ * `["private"]`. Only a move *into* the Folder reads it.
63
+ */
64
+ private?: boolean
44
65
  }
45
66
 
46
67
  /**
47
- * Create a Folder: `[kind:9007, kind:1852 add + name]`.
68
+ * Create a Folder: `[kind:9007 + name, kind:1852 add]`.
48
69
  *
49
- * The channel first, because a Folder *is* one (RFC 0.4 §4.1). Then a command
50
- * naming it and listing nothing, so the Folder **has state from birth** — a
51
- * listing that shows only Folders with state would otherwise never show it,
52
- * and a stateless Folder is indistinguishable from a bare channel. Safe here
70
+ * The channel first, because a Folder *is* one (§3). Then a command listing
71
+ * nothing, so the Folder **has state from birth** — a group without a
72
+ * `kind:30890` is not a Folder, and a listing would never show it. Safe here
53
73
  * and nowhere else without `hasState`: the channel was created by the first
54
- * event, so nothing is filed in it to hide.
74
+ * event, so nothing is filed in it to hide. The relay emits state for an `add`
75
+ * with no addresses and no name.
76
+ *
77
+ * `folder` MUST be a uuid nobody has used. The relay answers a `kind:9007` for
78
+ * an existing channel with `duplicate:`, which the bridge reports as accepted,
79
+ * so a reused id would send the `add` to a group that may hold files and no
80
+ * state — and empty it on every surface.
55
81
  */
56
82
  export function planCreateFolder(
57
83
  pubkey: string,
@@ -64,37 +90,52 @@ export function planCreateFolder(
64
90
  name: args.name,
65
91
  ...(args.visibility ? { visibility: args.visibility } : {}),
66
92
  }),
67
- buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name }),
93
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add' }),
68
94
  ]
69
95
  }
70
96
 
71
97
  /**
72
- * Rename a Folder: `[kind:9002, kind:1852 add + name if it has state]`.
98
+ * Rename a Folder: `[kind:9002]`, and nothing else.
73
99
  *
74
- * **A Folder's name has two homes** and the state's shadows the channel's, so
75
- * writing only the channel leaves the old name wherever the state is read. The
76
- * command is `add` with no addresses — the contents are kept and only the name
77
- * changes; `set` would empty it and there is no `rename` op. With no state
78
- * there is only the channel to rename, and a command would empty the Folder.
100
+ * The title is the channel's name (§3.2), so the channel is the only home to
101
+ * write. The relay refuses it to anybody but the channel's owners and admins.
102
+ * A name left on an older state by a command is never shown.
79
103
  */
80
104
  export function planRenameFolder(
81
105
  pubkey: string,
82
106
  createdAtMs: number,
83
- args: { folder: string; name: string; hasState: boolean },
107
+ args: { folder: string; name: string },
84
108
  ): UnsignedEvent[] {
85
- const rename = buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name })
86
- if (!args.hasState) return [rename]
87
- return [rename, buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name })]
109
+ return [buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name })]
110
+ }
111
+
112
+ /**
113
+ * Delete a Folder: `[kind:9008]`.
114
+ *
115
+ * **For an empty Folder.** The relay refuses while the Folder holds a file —
116
+ * a `30840`, `30850` or `30851` under its `h`, or any address its listing
117
+ * names — with a reason naming the count ("folder holds N file(s) … remove
118
+ * them first"), and a consumer shows that reason. A file moved out keeps its
119
+ * `h`, so a Folder whose listing looks empty can still refuse.
120
+ *
121
+ * An accepted delete hides **every** event under the `h`, its conversation
122
+ * included, for good. Archive ({@link planArchiveFolder}) is the reversible way
123
+ * to put a Folder away. Folders never nest, so there is no container to unlist
124
+ * it from.
125
+ */
126
+ export function planDeleteFolder(pubkey: string, createdAtMs: number, args: { folder: string }): UnsignedEvent[] {
127
+ if (!args.folder) throw new Error('a Folder delete names the Folder')
128
+ return [buildDeleteChannel(pubkey, createdAtMs, { channelUuid: args.folder })]
88
129
  }
89
130
 
90
131
  /**
91
132
  * List a file that was just published into a Folder: `[kind:1852 add]` if the
92
133
  * Folder has state, otherwise nothing.
93
134
  *
94
- * A Folder read by containment lists the file the moment its `h` is stored. A
95
- * Folder with state lists only what its state names, so it needs the `add`.
96
- * Publish the file first: a refused `add` then leaves a file that exists and
97
- * is reachable, rather than a listing that points at nothing.
135
+ * A Folder with state lists only what its state names, so it needs the `add`.
136
+ * A group with no state lists the file by containment the moment its `h` is
137
+ * stored (§7.3). Publish the file first: a refused `add` then leaves a file
138
+ * that exists and is reachable, rather than a listing that points at nothing.
98
139
  */
99
140
  export function planPlaceFile(
100
141
  pubkey: string,
@@ -110,7 +151,7 @@ export function planPlaceFile(
110
151
  * the Folder has state, otherwise nothing.
111
152
  *
112
153
  * {@link planPlaceFile} in reverse. A Folder with state lists what it names,
113
- * deleted or not, so the row would stay pointing at nothing; a Folder read by
154
+ * deleted or not, so the row would stay pointing at nothing; a group read by
114
155
  * containment stops listing the file once the relay hides it. Delete first: a
115
156
  * refused `remove` then leaves a stale row, where the other order would unlist
116
157
  * a file the relay kept.
@@ -125,47 +166,19 @@ export function planUnlistFile(
125
166
  }
126
167
 
127
168
  /**
128
- * Why a move was refused. The source is checked first: no choice of target
129
- * fixes it, so a consumer can stop offering Move for that file at all.
130
- */
131
- export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state'
132
-
133
- export type MovePlan = { ok: true; events: UnsignedEvent[] } | { ok: false; reason: MoveRefusal }
134
-
135
- /**
136
- * Move a file between Folders: `[kind:1852 add to target, kind:1852 remove from source]`.
137
- *
138
- * **Add first.** There is no atomic move — state is per Folder — so something
139
- * can fail between the two. After the add, a failure leaves the file in both
140
- * Folders: visible, obviously wrong, fixed by moving again. Removing first and
141
- * failing would leave it in neither, which looks like a file that never was.
142
- *
143
- * **Refused unless both Folders have state.** An `add` to a Folder with none
144
- * emits state listing only the moved file, and everything already filed in it
145
- * disappears; a `remove` from one emits state listing nothing, and the whole
146
- * source disappears. Writing a complete state first is not offered here: what
147
- * a stateless Folder holds is whatever its `h` implies to *this* reader, and a
148
- * planner that enumerated it would be deciding on everyone's behalf.
149
- *
150
- * A move to the same Folder plans nothing.
151
- */
152
- /**
153
- * Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46.
169
+ * Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46, SPEC §3.3.
154
170
  *
155
171
  * **Not a Folder command.** A Folder is archived the way any file is: a change
156
172
  * setting `archived` on its address — its channel's, `FolderSummary.channel` —
157
173
  * to `'true'`, or to an empty value to restore it. Its state, its contents and
158
174
  * its channel are untouched, which is what makes it reversible: a `kind:9008`
159
- * hides everything under the Folder's `h` for good (FOL-9), and a `kind:1852`
160
- * would unlist the Folder from somewhere a person would have to remember.
175
+ * hides everything under the Folder's `h` for good, and a `kind:1852` would
176
+ * unlist a file from somewhere a person would have to remember.
161
177
  *
162
- * **Where it is published decides who reads it**, because a change is read by
163
- * the members of the channel it is in. `into` is the Folder that lists this
164
- * one (`FolderSummary.listedIn`), when there is one: everyone reading that
165
- * Folder then reads the archive, and a private sub-Folder is hidden from its
166
- * team for the team's members too, not only for its own. A top-level Folder has
167
- * no container, so it defaults to the Folder itself — anyone who may write
168
- * there, a member and not only an admin, may archive it.
178
+ * **Always in the Folder's own `h`**, and readers count it only from an owner
179
+ * or admin on the Folder's `kind:39001` (§3.2) — the people who may rename it.
180
+ * So offer Archive only to them (`FolderSummary.admins`): from anybody else the
181
+ * relay accepts the event and every reader ignores it.
169
182
  *
170
183
  * `resolution` is what the person archiving said about it, carried as the
171
184
  * change's `content`; readers show it first when the archived Folder is
@@ -174,7 +187,7 @@ export type MovePlan = { ok: true; events: UnsignedEvent[] } | { ok: false; reas
174
187
  export function planArchiveFolder(
175
188
  pubkey: string,
176
189
  createdAtMs: number,
177
- args: { folder: string; channel: string; archived: boolean; resolution?: string; into?: string },
190
+ args: { folder: string; channel: string; archived: boolean; resolution?: string },
178
191
  ): UnsignedEvent[] {
179
192
  return [
180
193
  {
@@ -187,7 +200,7 @@ export function planArchiveFolder(
187
200
  ['a', args.channel],
188
201
  ['field', 'archived'],
189
202
  ['value', args.archived ? 'true' : ''],
190
- ['h', args.into ?? args.folder],
203
+ ['h', args.folder],
191
204
  ['ts', String(createdAtMs)],
192
205
  ],
193
206
  content: args.archived ? (args.resolution ?? '') : '',
@@ -195,19 +208,131 @@ export function planArchiveFolder(
195
208
  ]
196
209
  }
197
210
 
211
+ /**
212
+ * A file as a move needs it. A `ForeignObject` from `resolveFolderContents` is
213
+ * one: `ref` is its identity, `parentRef` the file it is drawn beneath, and
214
+ * `folder` the `h` of its root — absent for a root placed by `buzz-channel`.
215
+ */
216
+ export interface MovableFile {
217
+ ref: string
218
+ address?: string
219
+ parentRef?: string
220
+ folder?: string
221
+ }
222
+
223
+ /**
224
+ * Why a move was refused. The source is checked first: no choice of target
225
+ * fixes it, so a consumer can stop offering Move for that file at all.
226
+ *
227
+ * `target-is-private`: the target's `kind:39000` is private and a moved file's
228
+ * `h` names any other channel, or none. A listing never changes who can read a
229
+ * file (§3.1), so the file would look private in the target and not be.
230
+ */
231
+ export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state' | 'target-is-private'
232
+
233
+ export type MovePlan =
234
+ | {
235
+ ok: true
236
+ events: UnsignedEvent[]
237
+ /** The addresses the plan moves — the file, when the source lists it, and every file listed beneath it. */
238
+ moved: string[]
239
+ }
240
+ | { ok: false; reason: MoveRefusal }
241
+
242
+ /**
243
+ * The files `listing` draws beneath `file`, at any depth, in listing order.
244
+ *
245
+ * Walked by `parentRef` — the bare file's folded `parent` (§6.7) and every
246
+ * other kind's declared children (§7.2) alike. A file on a cycle is drawn at
247
+ * the top (§6.7), so nothing is beneath it through the cycle: two files each
248
+ * moved under the other are neither's sub-file.
249
+ */
250
+ export function listedBeneath<T extends MovableFile>(listing: readonly T[], file: Pick<MovableFile, 'ref' | 'parentRef'>): T[] {
251
+ const byRef = new Map(listing.map((candidate) => [candidate.ref, candidate]))
252
+ const cycles = new Map<string, boolean>()
253
+ const onCycle = (ref: string) => {
254
+ let found = cycles.get(ref)
255
+ if (found !== undefined) return found
256
+ found = false
257
+ const seen = new Set<string>()
258
+ for (let at = byRef.get(ref)?.parentRef; at && !seen.has(at); at = byRef.get(at)?.parentRef) {
259
+ if (at === ref) {
260
+ found = true
261
+ break
262
+ }
263
+ seen.add(at)
264
+ }
265
+ cycles.set(ref, found)
266
+ return found
267
+ }
268
+ // Up from `candidate` until `file`; a file on a cycle is at the top, so the walk ends there.
269
+ const isBeneath = (candidate: MovableFile) => {
270
+ if (onCycle(candidate.ref)) return false
271
+ const seen = new Set<string>()
272
+ for (let at = candidate.parentRef; at && !seen.has(at); at = byRef.get(at)?.parentRef) {
273
+ if (at === file.ref) return true
274
+ if (onCycle(at)) return false
275
+ seen.add(at)
276
+ }
277
+ return false
278
+ }
279
+ return listing.filter((candidate) => candidate.ref !== file.ref && isBeneath(candidate))
280
+ }
281
+
282
+ /**
283
+ * Move a file to another Folder, with everything listed beneath it:
284
+ * `[kind:1852 add to target, kind:1852 remove from source]` — SPEC §3.3.
285
+ *
286
+ * **One command each way, naming the whole set.** `listing` is the source
287
+ * Folder's files (`FolderContents.files`); the file moves with every file
288
+ * listed beneath it ({@link listedBeneath}), so a subtree moves whole. The
289
+ * relay applies every address on a command in one state write, so a failure
290
+ * can never split the subtree between the two Folders. The file itself is
291
+ * moved only when the source lists it — a Ship issue is listed by no Folder,
292
+ * its project is. The file's `h` does not change.
293
+ *
294
+ * `listing` is required, and `null` says "nothing can be listed beneath this
295
+ * file", making the file the whole set. A move that silently left its
296
+ * sub-files behind is the bug this planner exists to end, so omitting the
297
+ * listing is a type error rather than a quiet single-file move.
298
+ *
299
+ * **Add first.** There is no atomic move — state is per Folder — so something
300
+ * can fail between the two. After the add, a failure leaves the set in both
301
+ * Folders: visible, obviously wrong, fixed by moving again. Removing first and
302
+ * failing would leave it in neither, which looks like files that never were.
303
+ *
304
+ * **Refused unless both Folders have state.** An `add` to a Folder with none
305
+ * emits state listing only the moved files, and everything already filed in
306
+ * it disappears; a `remove` from one emits state listing nothing, and the
307
+ * whole source disappears.
308
+ *
309
+ * **Refused into a private Folder** when any moved file's `h` is another
310
+ * channel or absent (`target-is-private`, §3.1).
311
+ *
312
+ * A move to the same Folder, or of a set the source does not list, plans nothing.
313
+ */
198
314
  export function planMoveFile(
199
315
  pubkey: string,
200
316
  createdAtMs: number,
201
- args: { address: string; from: FolderRef; to: FolderRef },
317
+ args: { file: MovableFile; from: FolderRef; to: FolderRef; listing: readonly MovableFile[] | null },
202
318
  ): MovePlan {
203
- if (args.from.id === args.to.id) return { ok: true, events: [] }
319
+ if (args.from.id === args.to.id) return { ok: true, events: [], moved: [] }
204
320
  if (!args.from.hasState) return { ok: false, reason: 'source-has-no-state' }
205
321
  if (!args.to.hasState) return { ok: false, reason: 'target-has-no-state' }
322
+ const { file, listing } = args
323
+ // The listing's own entry when it has one, so the walk goes by the refs the listing's children name.
324
+ const listed = listing?.find((candidate) => candidate.ref === file.ref || (!!file.address && candidate.address === file.address))
325
+ const set = listing ? [...(listed ? [listed] : []), ...listedBeneath(listing, listed ?? file)] : [file]
326
+ const moving = set.filter((candidate) => candidate.address)
327
+ if (args.to.private && moving.some((candidate) => candidate.folder !== args.to.id)) return { ok: false, reason: 'target-is-private' }
328
+ const moved = [...new Set(moving.map((candidate) => candidate.address!))]
329
+ if (!moved.length) return { ok: true, events: [], moved }
206
330
  return {
207
331
  ok: true,
208
332
  events: [
209
- buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: [args.address] }),
210
- buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: [args.address] }),
333
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: moved }),
334
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: moved }),
211
335
  ],
336
+ moved,
212
337
  }
213
338
  }
package/src/index.ts CHANGED
@@ -100,7 +100,7 @@ export {
100
100
  } from './projection.js'
101
101
 
102
102
  /**
103
- * SPEC §6.7's nesting, drawn from one team listing: roots, children,
103
+ * SPEC §6.7's nesting, drawn from one Folder listing: roots, children,
104
104
  * breadcrumbs and move targets, with cycles cut. No requests.
105
105
  */
106
106
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
@@ -118,18 +118,22 @@ export {
118
118
  } from './references.js'
119
119
 
120
120
  /**
121
- * Folder writes as unsigned events in publish order — create, rename, place,
122
- * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
123
- * against a Folder with no state empties it. No signing, no requests.
121
+ * SPEC §3.3's Folder operations as unsigned events in publish order — create,
122
+ * rename, archive, delete, place, unlist, move. Where a `kind:1852` is sent,
123
+ * `hasState` comes from the caller, because one against a group with no state
124
+ * empties it. No signing, no requests.
124
125
  */
125
126
  export {
126
127
  planCreateFolder,
127
128
  planRenameFolder,
129
+ planDeleteFolder,
128
130
  planPlaceFile,
129
131
  planUnlistFile,
130
132
  planMoveFile,
131
133
  planArchiveFolder,
134
+ listedBeneath,
132
135
  type FolderRef,
136
+ type MovableFile,
133
137
  type MovePlan,
134
138
  type MoveRefusal,
135
139
  } from './folders.js'