~otheb/kb

kb/README -rw-r--r-- 6.1 KiB View raw
b278ffebOlie Ayre Adding missing std.path import to WUI 2 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
                                   ### KB ###

`kb` is a simple knowledge base toolset built around a few key principles:

 - Creating entries sholud be fast and require minimal mental effort.
 - Entries sholud be short and explain small things whenever possible.
 - Entries should be editable and have viewable history.
 - Entries should be easily searchable.
 - The core API server should be incredibly simple to setup and work with,
   working simply with flat files and only requiring a small number of API
   functions to use.

# HOW IT WORKS

The data directory contains a collection of json files. Each file name is the
same as the entry's ID. Thus, if a file with a given number doesn't exist, then
that entry doesn't exist. The API is used to interact with the data in an
efficient matter programatically, which should be used as a base for creating
tools and clients for working with the data - of which there are 2 reference
clients.

A user can create new entries quickly and with little effort to send them
straight into storage, and can search for entries to try and find required
information. Modifications can be made to entries to keep them relevant, and
more helpful entries can be boosted to make it easier for others to find
information. There isn't really any more to it.

`kb` is targeted mainly at small groups, such as those in an office that wish to
easily share information between them. As a result, it does not come with any
access control or accounts systems. It is however very feasible to write an
authentication proxy to sit in front of the API and use a customised client to
properly handle authentication. That is beyond the scope of the project though.

# API

You need but 7 simple requests to use `kb`:

GET /
	List all entry IDs. Returns 'application/json':
	{ ids : [ 0 , 1 , 7 ] }

GET /$n
	Get the content of an entry. Returns 'application/json':
	{
		id : 123 , // unique numeric id of the entry
		title : "The title" , // entry title
		time : 12345678 , // unix timestamp for the entry
		old : false , // boolean deprecation flag
		tags : [ "some" , "helpful" , "tags" ] , // tags for searching
		content : "large string body" ,
		history : [
			{
				time : 12345678 ,
				content : "old content"
			}
		]
	}
	If the entry doesn't exist, a 404 is returned.

DELETE /$n
	Delete an entry. Here, the entire file is simply deleted. Returns 200 if
	successful or 404 if the entry doesn't or no longer exists, making the
	request idempotent.

POST /$n
POST /
	Sends new entry content and tags. If just sent to `/api/e`, a new entry is
	created and returns the ID of the newly created entry or a 500 if creating
	the entry fails for whatever reason. If an entry ID is provided, the content
	is sent as a modification to the given ID. `kb` keeps up to 16 items of
	history (not including current version), so if that limit is reached, then
	the oldest item of history is dropped. If the given entry ID does not exist,
	then that entry is created and that same ID is returned on a success. The
	payload of these requests should be 'application/json' and look like this:
	{
		title : "The title" , // property is updated
		old : false , // property is updated
		tags : [] , // property is updated
		content : "blah" // used as new body
	}
	Only the body is required. Any other properties that are omitted are left
	unchanged. If the new content is identical to the existing content (e.g. as
	a result of a duplicate request), then no change is made and a 304 is
	returned.

PATCH /$n
	Modifies an existing entry. Intended to be used to apply small fixes such as
	spelling corrections rather than providing any substantial new content. As a
	result, this does not push the current content into history, but instead
	overwrites it. The payload is of exactly the same format as the equivalent
	POST request.

POST /s
	Searches for entries given a string search term in the payload. Payload
	should be 'application/json':
	{ search : "my search term" }
	Returns 'application/json':
	{ results : [
		{
			id : 123 , // id of the result
			relevance : 8 // calculated relevance (heuristic)
		}
	] }
	The relevance is a heuristic value created by combining weighted values of
	number of tag matches, content matches, and popularity. Higher is considered
	better.

# CLI

A handful of commands make the CLI easy:

$ kb ls [-r]
	Generates a formatted listing of all entries and opens them in $PAGER
	(defaults to `less`). Sorts by ID, or `-r` can be provided to sort by
	timestamp, with more recently created/modified entries at the top.

$ kb view ID
	Opens a formatted view of the entry #ID in $PAGER.

$ kb new
	Opens a formatted template in $EDITOR (defaults to `vim`) to fill in
	information, then uses the resulting buffer to generate a new entry.

$ kb edit ID
	Opens a formatted template in $EDITOR pre-populated with the content in
	entry #ID for editing. An additional flag is present that allows specifying
	whether this is a new version or just a patch/fixup.

$ kb rm ID
	Deletes entry #ID

$ kb search TERMS...
	Completes a search for entries based on the provided terms and displays
	results in the same manner as `kb ls`.

The very first argument to `kb` should be the hostname/IP and port of the API
server. Users should create a shell alias to include this information
automatically. `kb` itself does not have a config file.

# WUI

The web UI is a SSR website frontend to the API server. It contains no
JavaScript at all. It can be configured to use a light or dark theme. The UI is
fairly self-explanatory.

### USAGE

Each project can be built by running `dub build` in the directories of each
project. Note that an internet connection is required for the build to succeed.

From there, you may simply put the resulting binaries somewhere in your system's
`$PATH`, optionally populate config files, and then just run them. The only
exception being the WUI which also requires copying the 3 CSS files to a
reasonable location (configurable in the WUI's options).

Note that the default data path for the API server is `./data`, which is
relative to the directory you are running the server from. Also, the default
static path for the WUI is `./static`, which is also relative. These should be
properly configured before using the programs.