@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 +16 -7
- package/lib/cmds/_teams.js +0 -1
- package/lib/cmds/_wiki.js +80 -28
- package/lib/helpers.js +1 -1
- package/package.json +1 -1
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).
|
|
245
|
-
|
|
246
|
-
|
|
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
|
|
250
|
-
`wiki
|
|
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>`
|
|
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.
|
package/lib/cmds/_teams.js
CHANGED
|
@@ -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
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
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
|
-
|
|
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
|
|
131
|
-
[org + "wiki update <wiki>", "say what it is for and retitle it (--description, --title)
|
|
132
|
-
[org + "wiki grant <wiki> <kind>:<id>[:<level>]", "grant a person (user:@handle, user:<email>, user:<id>) or a team (team:<slug
|
|
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
|
|
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
|
|
904
|
-
//
|
|
905
|
-
//
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
})
|