@minca/core 0.1.17 → 0.1.18

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 (86) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +2 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
@@ -0,0 +1,142 @@
1
+ # Permissions
2
+
3
+ Every space decides who may do what in it, and every device enforces it.
4
+ There's no server to ask and no admin panel to trust: a change that breaks
5
+ the space's rules is refused by everyone, wherever it was written.
6
+
7
+ ## Roles
8
+
9
+ Who may write lives in the space, not in your code or in a definition. A
10
+ role holds grants, and each grant is a command with a policy over its
11
+ arguments. "Hosts may delete any poll" is:
12
+
13
+ ```typescript
14
+ import { RECORD_DELETE } from '@minca/core';
15
+
16
+ await node.spaces.defineRole(space.id, {
17
+ name: 'host',
18
+ title: 'Host',
19
+ grants: [{ cmd: RECORD_DELETE, pol: [['==', '.collection', 'app.poll']] }],
20
+ nests: ['member'], // a host holds what a member holds too
21
+ });
22
+ await node.spaces.assign(space.id, did, 'host');
23
+ ```
24
+
25
+ - `/record/write` and `/record/delete` see `collection` and `byCreator`, and
26
+ a write also sees `body`. `byCreator` is whether the writer's account made
27
+ the record's first version, and is true for a new record. So
28
+ `['==', '.byCreator', true]` means "only your own".
29
+ - `/collection/define` adds or changes collections. It also needs a note that
30
+ grants `/collection/define`, and an agent's note doesn't.
31
+ - You can't grant what you don't hold.
32
+ - The space's founders, if it has any, hold every command.
33
+
34
+ To ask before acting, `node.spaces.may(space.id, cmd, args)` says whether
35
+ this account may do something now, and `node.records.can(space, action, target)`
36
+ asks it for a record. Assigning, removing and roles that define roles are
37
+ covered in [spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
38
+
39
+ ## Presets
40
+
41
+ A preset is a starting constitution: who sits at the top, the roles the space
42
+ is founded with and what each may do, and the roles you start with. Spread
43
+ one into `spaces.create`, change it, or write your own. Nothing checks a
44
+ preset's name.
45
+
46
+ | Preset | `top` | Roles |
47
+ | ----------- | ---------- | ------------------------------------------ |
48
+ | `solo` | `founders` | none: the founder alone |
49
+ | `team` | `founders` | editor |
50
+ | `community` | `founders` | admin, moderator, member |
51
+ | `coop` | `none` | steward (yours), member; no founder at all |
52
+
53
+ What each role may do:
54
+
55
+ | Role | Grants |
56
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
57
+ | `team` editor | `/record`, `/collection/define`, `/role/assign` with `.role == "editor"` |
58
+ | `community` admin | `/record`, `/collection/define`, `/role/assign`, `/role/define` for every role but admin, `/role/unassign` and `/member/remove` of anyone not an admin, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers` |
59
+ | `community` moderator | `/record`, `/role/assign` with `.role == "member"`, `/std.automation/instruct` |
60
+ | `community` member | `/record/write` and `/record/delete` where `.byCreator` is true, outside `STAFF_COLLECTIONS` |
61
+ | `coop` steward | `/record`, `/collection/define`, `/role/define` for member, `/role/assign` and `/role/unassign` of member or steward, `/member/remove` of anyone, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers` |
62
+ | `coop` member | as `community` member, and `/space/succeed` |
63
+
64
+ ### Founders or no top
65
+
66
+ Under `top: founders` you are the founder, and hold every command whatever
67
+ the roles say. So no `founders` preset needs a role for you. Name others who
68
+ found it with you in `cofounders`.
69
+
70
+ Under `top: none`, as in `coop`, there is no founder. You hold only your
71
+ `creatorRoles`, here `steward`, and another steward can remove you.
72
+
73
+ ### Changing each other's records
74
+
75
+ Every preset says whether members may change each other's records. A grant
76
+ of `/record/write` with no policy on `.byCreator` lets them. In `community`
77
+ and `coop`, members change only what they made, and moderators or stewards
78
+ change anything.
79
+
80
+ `STAFF_COLLECTIONS` are the standard collections only moderators start in a
81
+ community: announcements, badges, awards, pins, labels, channels, hosts and
82
+ the space's own profile (`std.space-profile`).
83
+
84
+ ### What "anyone not an admin" protects
85
+
86
+ The policy on removing "anyone not an admin" reads the target's roles as the
87
+ remover sees them. It stops an admin who has seen another's promotion. It
88
+ doesn't stop one who acts on an older view, or at the same moment. So
89
+ `community` admins can still remove or demote each other that way. Where that
90
+ matters, give removal to fewer people, or to the founders alone.
91
+
92
+ See [spec 03 §2.3 and §3.2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
93
+
94
+ ### Who defines a role
95
+
96
+ A role that may define itself can get stuck. If two of its holders rewrite
97
+ it differently, it keeps only what both versions share. If that drops
98
+ `/role/define`, nobody in the role can settle it.
99
+
100
+ So a preset gives `/role/define` for a role to another role, or to the
101
+ founders alone. In `community` the founders define admin, and admins define
102
+ the rest. In `coop` stewards define member, and nobody defines steward:
103
+ changing it takes a successor.
104
+
105
+ ### `solo` never changes
106
+
107
+ The account's own derived spaces, the registry and the contacts space, use
108
+ `solo`'s roles byte for byte, and their ids depend on it. So `solo` must not
109
+ change. See
110
+ [spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
111
+
112
+ ## The top and founders
113
+
114
+ `spaces.access(id)` says who is at the top: `top` (`founders` or `none`),
115
+ `founder` on each member, and `founder` for this account.
116
+
117
+ Nobody removes or demotes a founder but the founder itself. So show no
118
+ remove button on a founder, and a "Step down" button on your own row when you
119
+ are one.
120
+
121
+ ### Stepping down
122
+
123
+ ```ts
124
+ await node.spaces.stepDown(space.id, { keep: 'admin' });
125
+ ```
126
+
127
+ You stay, with the roles you hold, and are a founder no more. `keep` assigns
128
+ you that role first. With no role at all you would not be a member, so the
129
+ library refuses. To go altogether, `leave`.
130
+
131
+ Stepping down undoes whatever this account did elsewhere that hadn't seen it,
132
+ as leaving does. So step down from a device that has synced.
133
+
134
+ ### Headless spaces
135
+
136
+ `access.headless` is true when no founder is left and no member may define
137
+ or assign any role. Members keep what their roles allow, but nobody can
138
+ change roles, and nothing in the constitution can change.
139
+
140
+ Say so plainly ("No one can change roles here any more"), and offer the way
141
+ on: naming a successor. Any member may do that once no member holds
142
+ `/space/succeed`.
@@ -1,12 +1,17 @@
1
1
  # Proposing collections
2
2
 
3
- A space can grow new collections without anyone deploying anything. Someone
4
- proposes them as a **blueprint**, and someone who may define collections
5
- applies it. An agent works this way, and so does a person whose role doesn't
6
- let them define collections.
3
+ A space can grow new collections without anyone deploying anything. Anyone
4
+ in the space can propose them, and someone who may define collections
5
+ applies the proposal. This is how agents add new things, and people whose
6
+ role doesn't let them define collections.
7
+
8
+ ## Proposing
9
+
10
+ A proposal is a **blueprint**: one `std.blueprint` record listing the
11
+ collections. Nothing is defined yet, so it can't break anything.
7
12
 
8
13
  ```typescript
9
- import { proposeCollections, reviewBlueprint, applyBlueprint } from '@minca/core/schemas';
14
+ import { proposeCollections } from '@minca/core/schemas';
10
15
 
11
16
  const proposal = await proposeCollections(node, space.id, {
12
17
  title: 'Chores',
@@ -24,38 +29,47 @@ const proposal = await proposeCollections(node, space.id, {
24
29
  },
25
30
  ],
26
31
  });
32
+ ```
33
+
34
+ Through the `collections_propose` tool, a standard collection can be given by
35
+ name alone, like `"std.task"`. `standardCollections` puts the library's
36
+ definition in its place.
27
37
 
28
- // Someone who may define collections reads what it would do, then applies it
29
- const review = reviewBlueprint(proposal.body!, await node.collections.list(space.id));
30
- await applyBlueprint(node, space.id, proposal.key);
38
+ ## Reviewing and applying
39
+
40
+ Before applying a blueprint, show the person what it would do.
41
+ `reviewBlueprint` says, for each collection, whether it is new, a change, or
42
+ the same, with a summary in sentences worked out from its rules:
43
+
44
+ ```typescript
45
+ import type { NodeRecord } from '@minca/core';
46
+ import { reviewBlueprint, applyBlueprint, type Blueprint } from '@minca/core/schemas';
47
+
48
+ async function apply(proposal: NodeRecord<Blueprint>) {
49
+ const review = reviewBlueprint(proposal.body!, await node.collections.list(space.id));
50
+ // Show the review to the person, and apply only if they agree
51
+ await applyBlueprint(node, space.id, proposal.key);
52
+ }
31
53
  ```
32
54
 
33
- - A blueprint is one `std.blueprint` record. Nothing is defined yet, so it
34
- can't break anything.
35
- - `reviewBlueprint` says, per collection, whether it is new, a change, or the
36
- same, with a summary in sentences worked out from its rules. Show that to
37
- the person before they apply it.
38
- - `applyBlueprint` defines each collection, signed by whoever applies it.
39
- They need a grant of `/collection/define` in the space, and a note that
40
- grants it.
41
- - To change it, propose a new one with `updates: <its key>`.
55
+ `applyBlueprint` defines each collection, signed by whoever applies it. They
56
+ need a grant of `/collection/define` in the space, and a note that grants it.
42
57
 
43
- Through `collections_propose`, a standard collection may be given by name
44
- (`"std.task"`): `standardCollections` puts the library's definition in its
45
- place.
58
+ ## Updating a proposal
59
+
60
+ To change a blueprint, propose a new one with `updates: <its key>`.
46
61
 
47
62
  ## Trying a contract before proposing it
48
63
 
49
- Anyone in a space can write records directly, not only through the app that
50
- proposed a collection, so an app's own checks stop nobody. What records must
51
- keep to for the app to mean anything (whose turn it is, a legal move, a
52
- balance) belongs in the collection's [contract](collections.md#contracts),
53
- which every reader judges.
64
+ Anyone in a space can write records directly, not only through your app. So
65
+ your app's own checks stop nobody. What records must keep to for your app to
66
+ mean anything, like whose turn it is or a legal move, belongs in the
67
+ collection's [contract](collections.md#contracts), which every reader checks.
54
68
 
55
- A contract written wrong refuses fair moves, or lets a cheat count, and
69
+ A contract written wrong refuses fair moves or lets a cheat count, and
56
70
  nothing shows it until someone plays. So `collections_propose` takes
57
- `examples`: versions it runs through their collection's schema and contract
58
- before writing anything, so the proposer sees a mistake first.
71
+ `examples`. It runs each one through its collection's schema and contract
72
+ before writing anything:
59
73
 
60
74
  ```json
61
75
  "examples": [
@@ -66,30 +80,37 @@ before writing anything, so the proposer sees a mistake first.
66
80
  ]
67
81
  ```
68
82
 
69
- - `author` is an account DID, the proposer's when left out. `prev` is the
70
- version before, `{ body, author?, links? }`, for a contract that reads
71
- `prev`; its author is this one's unless it names another, so turn-taking
72
- is tried by naming both. `creator`, who wrote the first version, is the
73
- version before's author, or this one's, unless given. Without `prev` the
74
- example is a first version.
75
- - An example that should count must fit its collection's schema too.
76
- - If any example comes out other than expected, nothing is proposed, and the
77
- error says which and why.
78
- - A collection with a contract that no example names is still proposed, with
79
- a warning saying so. The warning goes to the proposer only: the person
80
- applying the blueprint sees the contract's conditions, not whether anyone
81
- tried them.
82
- - What examples don't try: rules (`onePer`, `fixed`, `final`), who may write,
83
- and a contract's `line`. `member(did)` asks the space as it is now, not as
84
- of what the version saw. A cited version can't be given, so an example
85
- whose contract cites one never counts as `pass`.
86
-
87
- _Source: `packages/core/src/schemas/blueprints.ts` (`tryContracts`), `packages/core/src/node/actions.ts` (`collections_propose`). Tests: `packages/core/tests/contracts.test.ts` ("checks: tried before they are proposed")._
83
+ If any example comes out other than expected, nothing is proposed, and the
84
+ error says which one and why.
85
+
86
+ ### What an example can say
87
+
88
+ | Field | Meaning |
89
+ | --------- | ---------------------------------------------------------------------------------- |
90
+ | `author` | The account DID that writes it. The proposer's when left out. |
91
+ | `prev` | The version before: `{ body, author?, links? }`. Leave it out for a first version. |
92
+ | `creator` | Who wrote the first version. Defaults to `prev`'s author, or this one's. |
93
+ | `expect` | `"pass"` or `"fail"`. |
94
+
95
+ `prev`'s author is this example's unless it names another, so to try
96
+ turn-taking, name both. An example expected to pass must fit its
97
+ collection's schema too.
98
+
99
+ ### What examples don't try
100
+
101
+ - Rules (`onePer`, `fixed`, `final`), who may write, and a contract's `line`.
102
+ - `member(did)` asks about the space as it is now, not as the version saw it.
103
+ - A cited version can't be given, so an example whose contract cites one
104
+ never passes.
105
+
106
+ A collection with a contract that no example names is still proposed, with a
107
+ warning. Only the proposer sees the warning. The person applying the
108
+ blueprint sees the contract's conditions, not whether anyone tried them.
88
109
 
89
110
  ## Saying how they are meant to be used
90
111
 
91
112
  A definition can't say "write one rota for each week, and say in it who does
92
- what". A guide can, and an agent finds it from `collections_list`:
113
+ what". A guide can, and an agent finds it through `collections_list`:
93
114
 
94
115
  ```typescript
95
116
  import { writeGuide } from '@minca/core/schemas';
@@ -102,14 +123,12 @@ await writeGuide(node, space.id, {
102
123
  });
103
124
  ```
104
125
 
105
- ## An app's own UI
126
+ ## An app's own screen
106
127
 
107
128
  Core runs no app's code. The example app lets a space add apps with a screen
108
129
  of their own: a `launcher.app` record that points at its blueprint and holds
109
- one HTML document, run in a sealed frame, as the person looking. It runs only
110
- once someone who may define collections has written the record, under a note
111
- that isn't records-only. The pieces
112
- are in the repository: `apps/example/src/components/apps/launcher.ts`,
113
- `screens.ts` and `ScreenFrame.tsx`, and `apps/example/public/screen.html`.
130
+ one HTML document. It runs in a sealed frame, as the person looking, and only
131
+ once someone who may define collections has written the record under a note
132
+ that isn't records-only.
114
133
 
115
- The details: [blueprints and guides](blueprints-and-guides.md).
134
+ The full details are in [Blueprints and guides](blueprints-and-guides.md).