@future-unknown/known 0.1.0 → 0.2.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/README.md CHANGED
@@ -241,13 +241,23 @@ known globex wiki leave acme-research
241
241
 
242
242
  `known acme wiki wikis` says what each wiki is for and who reads it, so a
243
243
  person or an agent can choose where something belongs (`--json` for
244
- everything). Any member creates a wiki and is its admin; an org owner
245
- administers every wiki already, so one who creates a wiki gets no grant
246
- (unless it is restricted and they name nobody, when it is theirs). Say
244
+ everything). Being in an organization gives nobody a wiki: a person holds
245
+ what a wiki's grants give them, their own or a team's. Every member is on
246
+ the built-in team `everyone`, so a wiki is open to the organization when
247
+ that team is granted it and restricted when it is not; a new wiki starts
248
+ granted to everyone unless `--grant` says who starts with it. Any member
249
+ creates a wiki and is its admin; an org owner administers every wiki
250
+ already, so one who creates a wiki gets no grant they did not name. Say
247
251
  what a wiki is for with `wiki update labs --description "…"` (or `wiki create
248
252
  labs --description "…"`); its admins and org owners change who reads it with
249
- `wiki grant labs team:platform:write`, `wiki revoke labs user:user_456`, and
250
- `wiki update labs --restricted` / `--open`. Levels are read, write and admin.
253
+ `wiki grant labs team:platform:write` and `wiki revoke labs user:user_456`;
254
+ `wiki grant labs team:everyone:read` opens it to every member at that level,
255
+ and `wiki revoke labs team:everyone` restricts it to its other grants (a
256
+ wiki keeps at least one). Levels are read, write and admin.
257
+ An org owner invites someone who is not in the organization yet with
258
+ `wiki invite labs dana@example.com:read`: they are invited to the
259
+ organization and the wiki is theirs when they join (`wiki uninvite` takes
260
+ it back; `wiki access` lists who is still invited).
251
261
  A person in a grant is a user id, an `@handle` or an email address
252
262
  (`user:@ada:write`); the last two must match exactly one member. A path that
253
263
  names no wiki is refused with the same list.
@@ -519,8 +529,7 @@ join from one of the org's verified domains; `approve` lets one in at a role
519
529
  - `--ts <iso>` — backfill when a log entry happened, for `wiki set`.
520
530
  - `--latest` / `--since <iso>` / `--until <iso>` / `--reverse` / `--at <iso>` —
521
531
  select `wiki records`.
522
- - `--description <text>` / `--title <text>` / `--restricted` / `--open` — what
523
- `wiki update` changes.
532
+ - `--description <text>` / `--title <text>` — what `wiki update` changes.
524
533
  - `--confirm <name>` — confirm `wiki delete` and `teams delete` by name, for
525
534
  scripts; at a terminal the name is asked for.
526
535
  - `--level read|write` — how far `wiki share` lets another organization reach.
@@ -73,7 +73,6 @@ function list(argv, ref) {
73
73
  const session = sessionFor(argv, ref)
74
74
  const teams = unwrap(await getClient(argv, { session }).team.list({}))
75
75
  if (output.isJson()) return output.data(teams)
76
- if (!teams.length) return output.empty("no teams yet — `known " + (ref ? ref + " " : "") + "teams create <name>`")
77
76
  const me = session.account && session.account.id
78
77
  output.table(teams.map((team) => {
79
78
  const seat = (team.members || []).find((member) => member.userId === me)
package/lib/cmds/_wiki.js CHANGED
@@ -50,9 +50,14 @@ const { getClient, sessionFor, confirm, confirmByName, confirmStated, run, unwra
50
50
  * known globex wiki invitations
51
51
  * known globex wiki accept acme/research --as acme-research
52
52
  *
53
- * Any member creates a wiki and is its admin; an org owner administers every
54
- * wiki already, so one who creates a wiki gets no grant — unless it is
55
- * restricted and they name nobody, when it is theirs. A wiki's admins and
53
+ * Being in an organization gives nobody a wiki: what a person holds is
54
+ * what a wiki's grants give them, their own or a team's. Every member is on
55
+ * the built-in team `everyone`, so a wiki is open to the organization when
56
+ * that team is granted it (`wiki grant labs team:everyone:read`) and
57
+ * restricted when it is not (`wiki revoke labs team:everyone`); a new wiki
58
+ * starts granted to everyone unless --grant says who. Any member creates a
59
+ * wiki and is its admin; an org owner administers every wiki already, so one
60
+ * who creates a wiki gets no grant they did not name. A wiki's admins and
56
61
  * the org's owners rename it, delete it (nothing is destroyed: `restore`
57
62
  * brings it back whole) and share it with another organization, whose owners
58
63
  * accept it under a name of their own. Levels are read, write and admin.
@@ -75,7 +80,11 @@ const { getClient, sessionFor, confirm, confirmByName, confirmStated, run, unwra
75
80
  */
76
81
  const STDIN_MAX = 100000
77
82
 
78
- const verbs = { read, write, edit, move, rm, tree, search, links, check, meta, records, get, set, del, history, diff, changes, notes, note, resolve, wikis, create, update, grant, revoke, access, rename, delete: destroy, deleted, restore, shares, share, unshare, invitations, accept, decline, leave }
83
+ // An address someone is invited by, and the levels an invitation takes.
84
+ const EMAIL = /^[^\s@:]+@[^\s@:]+\.[^\s@:]+$/
85
+ const INVITE_LEVELS = ["read", "write", "admin"]
86
+
87
+ const verbs = { read, write, edit, move, rm, tree, search, links, check, meta, records, get, set, del, history, diff, changes, notes, note, resolve, wikis, create, update, grant, revoke, invite, uninvite, access, rename, delete: destroy, deleted, restore, shares, share, unshare, invitations, accept, decline, leave }
79
88
 
80
89
  module.exports = function (argv, ref, rest) {
81
90
  const verb = rest && rest[0]
@@ -127,10 +136,12 @@ function showMenu(ref) {
127
136
  ]],
128
137
  ["wikis", [
129
138
  [org + "wiki wikis", "the org's wikis — what each is for, who reads it, what changed since you looked, your level (--json: everything)"],
130
- [org + "wiki create <name>", "create a wiki (--description, --title, --restricted, --grant <kind>:<id>[:<level>], --member <person>; any member, who is its admin)"],
131
- [org + "wiki update <wiki>", "say what it is for and retitle it (--description, --title); --restricted or --open (its admins and org owners)"],
132
- [org + "wiki grant <wiki> <kind>:<id>[:<level>]", "grant a person (user:@handle, user:<email>, user:<id>) or a team (team:<slug>) a level: read, write, admin; again to change it"],
133
- [org + "wiki revoke <wiki> <kind>:<id>", "take a grant away"],
139
+ [org + "wiki create <name>", "create a wiki (--description, --title; --grant <kind>:<id>[:<level>] and --member <person> say who starts with it, everyone when unsaid; any member, who is its admin)"],
140
+ [org + "wiki update <wiki>", "say what it is for and retitle it (--description, --title)"],
141
+ [org + "wiki grant <wiki> <kind>:<id>[:<level>]", "grant a person (user:@handle, user:<email>, user:<id>) or a team (team:<slug>; team:everyone is every member) a level: read, write, admin; again to change it"],
142
+ [org + "wiki revoke <wiki> <kind>:<id>", "take a grant away (team:everyone restricts the wiki to its other grants)"],
143
+ [org + "wiki invite <wiki> <email>[:<level>]", "invite someone not yet in the organization, with the wiki waiting for them at a level (org owners); a member's address is granted"],
144
+ [org + "wiki uninvite <wiki> <email>", "take an invited address off the wiki"],
134
145
  [org + "wiki access <wiki>", "who has access, at what level, and why (the org, a direct grant, a team, owning the org)"],
135
146
  [org + "wiki rename <wiki> <new-name>", "rename it (its admins and org owners; --yes); sites must be republished, agents use the new name"],
136
147
  [org + "wiki delete <wiki>", "delete it — type its name, or --confirm <name>; it can be restored"],
@@ -832,7 +843,8 @@ function siteHost(site) {
832
843
 
833
844
  // Any member creates a wiki and is its admin: the grant is theirs whatever
834
845
  // else was asked. An org owner administers every wiki already, and gets no
835
- // grant by creating one. A restricted wiki starts from its grants:
846
+ // grant by creating one. A wiki starts granted to everyone unless it says
847
+ // who starts with it, and then holds exactly those:
836
848
  // --grant <kind>:<id>[:<level>] (repeatable; kind is user or team, level is
837
849
  // read, write, or admin, write when unsaid) and --member <person>
838
850
  // (repeatable; a person with write). A person is a user id, an @handle, or
@@ -876,6 +888,7 @@ function create(argv, ref, rest) {
876
888
  if (!WIKI_NAME.test(String(name))) {
877
889
  throw friendly("wiki names are lowercase letters, digits, and hyphens — got “" + name + "”")
878
890
  }
891
+ refuseVisibility(argv, String(name))
879
892
  const grants = grantsOf(argv)
880
893
  const session = sessionFor(argv, ref)
881
894
  const client = getClient(argv, { session })
@@ -888,7 +901,6 @@ function create(argv, ref, rest) {
888
901
  name: String(name),
889
902
  ...(argv.title ? { title: argv.title } : {}),
890
903
  ...(argv.description ? { description: String(argv.description) } : {}),
891
- ...(argv.restricted ? { visibility: "restricted" } : {}),
892
904
  ...(grants ? { grants: named } : {})
893
905
  }))
894
906
  if (output.isJson()) return output.data(entry)
@@ -900,29 +912,25 @@ function create(argv, ref, rest) {
900
912
  })
901
913
  }
902
914
 
903
- // A wiki's own words about itself, and who sees it: --description and
904
- // --title are its root page's (any writer of the wiki), --restricted and
905
- // --open its visibility (its admins and org owners). A wiki restricted
906
- // keeps the grants it has; grant someone first.
915
+ // A wiki's own words about itself: --description and --title are its root
916
+ // page's (any writer of the wiki). Who holds it is its grants (grant,
917
+ // revoke): nothing here opens or restricts it.
907
918
  function update(argv, ref, rest) {
908
919
  return run(async () => {
909
920
  const name = rest[0]
910
921
  if (!name || !WIKI_NAME.test(String(name))) throw friendly("name the wiki — `known <org> wiki update <wiki> --description \"…\"`")
911
- if (argv.restricted && argv.open) throw friendly("pass --restricted or --open, not both")
922
+ refuseVisibility(argv, String(name))
912
923
  const changes = {
913
924
  ...(argv.title !== undefined ? { title: String(argv.title) } : {}),
914
- ...(argv.description !== undefined ? { description: String(argv.description) } : {}),
915
- ...(argv.restricted ? { visibility: "restricted" } : {}),
916
- ...(argv.open ? { visibility: "org" } : {})
925
+ ...(argv.description !== undefined ? { description: String(argv.description) } : {})
917
926
  }
918
- if (!Object.keys(changes).length) throw friendly("nothing to change — pass --description, --title, --restricted, or --open")
927
+ if (!Object.keys(changes).length) throw friendly("nothing to change — pass --description or --title")
919
928
  const session = sessionFor(argv, ref)
920
929
  const entry = unwrap(await getClient(argv, { session }).wiki.update({ wiki: String(name), ...changes }))
921
930
  if (output.isJson()) return output.data(entry)
922
931
  const said = [
923
932
  changes.description !== undefined ? "says what it is for" : null,
924
- changes.title !== undefined ? "is titled " + entry.title : null,
925
- changes.visibility ? (entry.visibility === "restricted" ? "is restricted to its grants" : "is open to every member") : null
933
+ changes.title !== undefined ? "is titled " + entry.title : null
926
934
  ].filter(Boolean)
927
935
  output.status("updated", entry.name, said.join(", "))
928
936
  })
@@ -961,8 +969,50 @@ function revoke(argv, ref, rest) {
961
969
  })
962
970
  }
963
971
 
972
+ // Invite someone by email onto a wiki: they are invited to the
973
+ // organization, and the wiki is theirs at the level named when they join.
974
+ // An address that is already a member's is granted at once. Organization
975
+ // owners may.
976
+ function invite(argv, ref, rest) {
977
+ return run(async () => {
978
+ const [name, who] = rest
979
+ if (!name || !who) throw friendly("name the wiki and the address — `known <org> wiki invite <wiki> <email>[:<level>]`")
980
+ if (!WIKI_NAME.test(String(name))) throw friendly("wiki names are lowercase letters, digits, and hyphens — got “" + name + "”")
981
+ const [email, level, ...extra] = String(who).split(":")
982
+ if (!EMAIL.test(email) || extra.length) throw friendly("invite takes <email>[:<level>] — got “" + who + "”")
983
+ if (level !== undefined && !INVITE_LEVELS.includes(level)) throw friendly("level is one of " + INVITE_LEVELS.join(", ") + " — got “" + level + "”")
984
+ const session = sessionFor(argv, ref)
985
+ const res = unwrap(await getClient(argv, { session }).wiki.invite({ wiki: String(name), email: email.toLowerCase(), ...(level ? { level } : {}) }))
986
+ if (output.isJson()) return output.data(res)
987
+ if (res.granted) return output.status("granted", String(name), "user " + res.granted.id + " · " + res.granted.level + " — already a member")
988
+ output.status("invited", String(name), res.invited.email + " · " + res.invited.level + " — theirs when they join")
989
+ })
990
+ }
991
+
992
+ function uninvite(argv, ref, rest) {
993
+ return run(async () => {
994
+ const [name, email] = rest
995
+ if (!name || !email) throw friendly("name the wiki and the address — `known <org> wiki uninvite <wiki> <email>`")
996
+ if (!WIKI_NAME.test(String(name))) throw friendly("wiki names are lowercase letters, digits, and hyphens — got “" + name + "”")
997
+ const session = sessionFor(argv, ref)
998
+ const res = unwrap(await getClient(argv, { session }).wiki.uninvite({ wiki: String(name), email: String(email).toLowerCase() }))
999
+ if (output.isJson()) return output.data(res)
1000
+ output.status("uninvited", String(name), res.email + (res.withdrawn ? " — their invitation to the organization was withdrawn too" : ""), "muted")
1001
+ })
1002
+ }
1003
+
964
1004
  // ---- access, renaming, deleting --------------------------------------------
965
1005
 
1006
+ // A wiki is not opened or restricted by a flag: it is open to the
1007
+ // organization when the team everyone is granted it. Whoever asks the old
1008
+ // way is told the new one.
1009
+ function refuseVisibility(argv, name) {
1010
+ if (!argv.restricted && !argv.open) return
1011
+ throw friendly(argv.open
1012
+ ? "open it by granting everyone — `known <org> wiki grant " + name + " team:everyone:write` (or read)"
1013
+ : "restrict it by taking everyone off — `known <org> wiki revoke " + name + " team:everyone` (grant whoever keeps it first), or create it with --grant naming who starts with it")
1014
+ }
1015
+
966
1016
  // A wiki named on its own, as these verbs take it (no path).
967
1017
  function wikiArg(value, usage) {
968
1018
  if (value === undefined || value === true || !WIKI_NAME.test(String(value))) {
@@ -988,15 +1038,11 @@ function access(argv, ref, rest) {
988
1038
  return (team && (team.slug || team.title)) || id
989
1039
  }
990
1040
  const rows = [
991
- ...(res.everyone ? [{
992
- who: "every member" + (res.members != null ? " (" + res.members + ")" : ""),
993
- level: res.everyoneLevel || "—".grey,
994
- why: "open to the organization".grey
995
- }] : []),
1041
+ // everyone first: the team every member is on, which is what makes a wiki open to the organization
996
1042
  ...res.teams.map((team) => ({
997
- who: "team " + (team.slug || team.title || team.id),
1043
+ who: team.builtin ? "everyone" : "team " + (team.slug || team.title || team.id),
998
1044
  level: team.level,
999
- why: ("granted to the team · " + team.members + (team.members === 1 ? " person" : " people")).grey
1045
+ why: ((team.builtin ? "every member of the organization · " : "granted to the team · ") + team.members + (team.members === 1 ? " person" : " people")).grey
1000
1046
  })),
1001
1047
  ...res.people.map((entry) => ({
1002
1048
  who: by({ id: entry.id }),
@@ -1004,6 +1050,12 @@ function access(argv, ref, rest) {
1004
1050
  // they manage who has access, and read nothing
1005
1051
  level: entry.level || "—".grey,
1006
1052
  why: (accessReasons(entry.via, teamName).join(", ") + (entry.level ? "" : " — manages access only")).grey
1053
+ })),
1054
+ // invited by email and not joined yet (listed to those who change access)
1055
+ ...(res.invited || []).map((entry) => ({
1056
+ who: entry.email,
1057
+ level: entry.level,
1058
+ why: "invited — theirs when they join".grey
1007
1059
  }))
1008
1060
  ]
1009
1061
  if (!rows.length) return output.empty("nobody has access to " + res.name)
package/lib/helpers.js CHANGED
@@ -340,9 +340,9 @@ async function person(client, value, where = PERSON_WHERE) {
340
340
  // answers carry (`via`). `teamName` names a team by its id.
341
341
  function accessReasons(via, teamName) {
342
342
  return (via || []).map((reason) => {
343
- if (reason.kind === "org") return "every member"
344
343
  if (reason.kind === "owner") return "org owner"
345
344
  if (reason.kind === "user") return "direct grant" + (reason.level ? " (" + reason.level + ")" : "")
345
+ if (reason.kind === "team" && reason.id === "everyone") return "everyone" + (reason.level ? " (" + reason.level + ")" : "")
346
346
  if (reason.kind === "team") return "team " + (teamName ? teamName(reason.id) : reason.id) + (reason.level ? " (" + reason.level + ")" : "")
347
347
  return reason.kind
348
348
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@future-unknown/known",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Known — the command-line interface to the Known platform",
5
5
  "bin": {
6
6
  "known": "bin/known"