sumibako 0.1.0 → 0.2.1
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 +170 -147
- package/SKILL.md +235 -150
- package/index.mjs +911 -613
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,147 +1,170 @@
|
|
|
1
|
-
# sumibako
|
|
2
|
-
|
|
3
|
-
File the plans, specs and notes your coding agent writes into your
|
|
4
|
-
[Sumibako](https://sumibako.com) vault, and get a link you can send to someone.
|
|
5
|
-
|
|
6
|
-
```bash
|
|
7
|
-
npx sumibako login
|
|
8
|
-
npx sumibako publish docs/plans/auth-rewrite.md --public
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
Created Auth rewrite plan
|
|
13
|
-
https://sumibako.com/vault/Auth-rewrite-plan-jd76...
|
|
14
|
-
|
|
15
|
-
Share this: https://sumibako.com/p/Auth-rewrite-plan-jd76...
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
## Why
|
|
19
|
-
|
|
20
|
-
Coding agents write a lot of prose that is worth keeping: implementation plans,
|
|
21
|
-
specs, architecture decisions, migration checklists, handoff notes. It ends up
|
|
22
|
-
as untracked Markdown in a working directory, or pasted into a chat, and then
|
|
23
|
-
somebody asks "can you send me that plan" and there is nothing to send.
|
|
24
|
-
|
|
25
|
-
Each agent has its own answer to this, and each answer only covers that agent's
|
|
26
|
-
own output and lives on that vendor's domain. This is one place for all of them,
|
|
27
|
-
in a vault you already own, where the document is a page you can keep editing.
|
|
28
|
-
|
|
29
|
-
## Setup
|
|
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
|
-
|
|
1
|
+
# sumibako
|
|
2
|
+
|
|
3
|
+
File the plans, specs and notes your coding agent writes into your
|
|
4
|
+
[Sumibako](https://sumibako.com) vault, and get a link you can send to someone.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
npx sumibako login
|
|
8
|
+
npx sumibako publish docs/plans/auth-rewrite.md --public
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
Created Auth rewrite plan
|
|
13
|
+
https://sumibako.com/vault/Auth-rewrite-plan-jd76...
|
|
14
|
+
|
|
15
|
+
Share this: https://sumibako.com/p/Auth-rewrite-plan-jd76...
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
Coding agents write a lot of prose that is worth keeping: implementation plans,
|
|
21
|
+
specs, architecture decisions, migration checklists, handoff notes. It ends up
|
|
22
|
+
as untracked Markdown in a working directory, or pasted into a chat, and then
|
|
23
|
+
somebody asks "can you send me that plan" and there is nothing to send.
|
|
24
|
+
|
|
25
|
+
Each agent has its own answer to this, and each answer only covers that agent's
|
|
26
|
+
own output and lives on that vendor's domain. This is one place for all of them,
|
|
27
|
+
in a vault you already own, where the document is a page you can keep editing.
|
|
28
|
+
|
|
29
|
+
## Setup
|
|
30
|
+
|
|
31
|
+
There isn't one. Run a command, and if this machine is not connected it prints
|
|
32
|
+
a link instead of doing the work:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npx sumibako publish docs/plans/auth-rewrite.md --public
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
Connect this machine to Sumibako:
|
|
40
|
+
https://sumibako.com/connect?code=WXYZ-4821
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Open it, check the code matches, approve. Then run the same command again and
|
|
44
|
+
it carries on. `npx sumibako login` does the same thing and waits, if you would
|
|
45
|
+
rather connect first.
|
|
46
|
+
|
|
47
|
+
Nothing is typed and nothing blocks, which is what lets a coding agent do this
|
|
48
|
+
on your behalf: it relays the link, you click, it runs the command again. The
|
|
49
|
+
token is stored in `~/.sumibako/config.json` with owner-only permissions.
|
|
50
|
+
|
|
51
|
+
Two ways round it when a browser is not in the picture. `--token <token>` takes
|
|
52
|
+
one you minted yourself under **Settings, Coding agents**, and `SUMIBAKO_TOKEN`
|
|
53
|
+
in the environment overrides everything, which is what CI should use.
|
|
54
|
+
|
|
55
|
+
### Exit codes
|
|
56
|
+
|
|
57
|
+
| Code | Meaning |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `0` | It worked |
|
|
60
|
+
| `3` | Not connected yet; a link was printed |
|
|
61
|
+
| `1` | Anything else |
|
|
62
|
+
|
|
63
|
+
## Commands
|
|
64
|
+
|
|
65
|
+
| Command | What it does |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `sumibako login` | Connect this machine, waiting for you to approve it |
|
|
68
|
+
| `sumibako publish <file.md>` | File a Markdown file as a page |
|
|
69
|
+
| `sumibako publish <file.md> --public` | And put it on the web, printing the link |
|
|
70
|
+
| `sumibako unpublish <file.md>` | Take the page off the web |
|
|
71
|
+
| `sumibako append <file.md> "text"` | Add to the end of a page |
|
|
72
|
+
| `sumibako edit <file.md> --find ... --replace ...` | Replace one exact piece of text |
|
|
73
|
+
| `sumibako open <file.md>` | Print the links for a page (`--markdown` for the page) |
|
|
74
|
+
| `sumibako search [words]` | Search your vault, or list it with no words |
|
|
75
|
+
| `sumibako whoami` | Check the token, plan and usage |
|
|
76
|
+
| `sumibako logout` | Forget the token on this machine |
|
|
77
|
+
|
|
78
|
+
### Options for `publish`
|
|
79
|
+
|
|
80
|
+
| Option | Meaning |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `--public` | Publish it and print a shareable link |
|
|
83
|
+
| `--title <title>` | Override the title, which otherwise comes from the first heading |
|
|
84
|
+
| `--key <key>` | Set the artifact's identity yourself |
|
|
85
|
+
| `--new` | File a new page even if this file was filed before |
|
|
86
|
+
| `--parent <page-id>` | Nest it under an existing page |
|
|
87
|
+
|
|
88
|
+
### Options for `append` and `edit`
|
|
89
|
+
|
|
90
|
+
| Option | Meaning |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| `--prepend` | Add to the start of the page instead of the end |
|
|
93
|
+
| `--find <text>` | The exact text to replace, as `open --markdown` prints it |
|
|
94
|
+
| `--replace <text>` | What to put there; an empty string deletes the matched text |
|
|
95
|
+
| `--title <title>` | Rename the page |
|
|
96
|
+
| `--key <key>` | Name the page by its key rather than by a path or an id |
|
|
97
|
+
|
|
98
|
+
## Changing a page without re-sending it
|
|
99
|
+
|
|
100
|
+
`publish` replaces the whole page. When you only want to add a line, or fix a
|
|
101
|
+
sentence in a page you no longer have on disk, read it and change that part:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
sumibako open docs/plans/auth.md --markdown
|
|
105
|
+
sumibako append docs/decisions.md "- chose Postgres over Dynamo"
|
|
106
|
+
sumibako edit docs/plans/auth.md --find "ship in Q3" --replace "ship in Q4"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`--find` matches against the Markdown `open --markdown` prints, and has to
|
|
110
|
+
match exactly once. If it appears twice the command refuses rather than picking
|
|
111
|
+
one, because picking one is how the wrong paragraph gets rewritten and nobody
|
|
112
|
+
finds out. Quote more of the surrounding lines.
|
|
113
|
+
|
|
114
|
+
The page's previous version is kept for fourteen days either way, and **Version
|
|
115
|
+
history** in the document menu puts it back.
|
|
116
|
+
|
|
117
|
+
## Publishing the same file twice
|
|
118
|
+
|
|
119
|
+
A file is filed under its path in the repository, so running `publish` again
|
|
120
|
+
updates the same page rather than making another one. That is the behaviour you
|
|
121
|
+
want when an agent revises a plan five times in a session: one page, one link,
|
|
122
|
+
always current.
|
|
123
|
+
|
|
124
|
+
Pass `--new` when you really do want a second page, or `--key` to choose the
|
|
125
|
+
identity yourself (useful when the file moves but the artifact does not).
|
|
126
|
+
|
|
127
|
+
## What survives the conversion
|
|
128
|
+
|
|
129
|
+
Headings, paragraphs, bold, italic, strikethrough, inline code, links, bullet
|
|
130
|
+
lists, numbered lists, task lists, nested lists, blockquotes, GitHub alerts
|
|
131
|
+
(`> [!NOTE]`), tables, fenced code with syntax highlighting, images on their own
|
|
132
|
+
line, and horizontal rules.
|
|
133
|
+
|
|
134
|
+
Two things degrade, and the command says so when they do:
|
|
135
|
+
|
|
136
|
+
- **Mermaid** renders as a plain code block. There is no diagram renderer.
|
|
137
|
+
- **Raw HTML** is kept as text.
|
|
138
|
+
|
|
139
|
+
## Privacy
|
|
140
|
+
|
|
141
|
+
Pages are private until you pass `--public`. A published page has a link anyone
|
|
142
|
+
can open, and carries `noindex` so search engines do not list it. Making a page
|
|
143
|
+
findable in search is a separate opt-in that only you can give, per page, in the
|
|
144
|
+
app - a token cannot do it.
|
|
145
|
+
|
|
146
|
+
## For agents
|
|
147
|
+
|
|
148
|
+
`SKILL.md` in this package is written for a coding agent to read. Point Claude
|
|
149
|
+
Code, Codex or Cursor at it and they will use the CLI correctly, including the
|
|
150
|
+
part about not creating duplicates.
|
|
151
|
+
|
|
152
|
+
## If your agent has no shell
|
|
153
|
+
|
|
154
|
+
Claude.ai and ChatGPT cannot run this. They can reach an MCP server, so there is
|
|
155
|
+
one at `https://sumibako.com/api/mcp` offering the same things as tools:
|
|
156
|
+
`write_page`, `read_page`, `edit_page`, `search_pages`, `publish_page` and
|
|
157
|
+
`get_account`. Add it as an MCP server and send the same token as an
|
|
158
|
+
`Authorization: Bearer` header.
|
|
159
|
+
|
|
160
|
+
Prefer the CLI where a shell exists. An MCP tool call carries the whole document
|
|
161
|
+
through the model's context to get there, so a 30KB plan costs 30KB of tokens;
|
|
162
|
+
this reads the file off disk and the model never holds it.
|
|
163
|
+
|
|
164
|
+
## Environment
|
|
165
|
+
|
|
166
|
+
| Variable | Meaning |
|
|
167
|
+
| --- | --- |
|
|
168
|
+
| `SUMIBAKO_TOKEN` | Use this token instead of the saved one |
|
|
169
|
+
| `SUMIBAKO_API` | Point at a different deployment |
|
|
170
|
+
| `NO_COLOR` | Turn off colour |
|