@scalableweb/companion 0.1.0 → 0.3.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 +141 -19
- package/dist/companion.js +3511 -2367
- package/dist/release.json +5 -3
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -1,41 +1,163 @@
|
|
|
1
1
|
# Scalable Web learning companion
|
|
2
2
|
|
|
3
|
-
A private local notebook and optional
|
|
4
|
-
|
|
3
|
+
A private local notebook and optional teaching assistant for [scalableweb.dev](https://scalableweb.dev).
|
|
4
|
+
Choose Codex, a direct API key or a local model; notebook-only use needs no model account.
|
|
5
|
+
Use Node.js 24 or 26.
|
|
6
|
+
|
|
7
|
+
## Install and start
|
|
8
|
+
|
|
9
|
+
Registry installation uses the pinned version:
|
|
5
10
|
|
|
6
11
|
```sh
|
|
7
|
-
npx @scalableweb/companion@0.
|
|
8
|
-
npx @scalableweb/companion@0.
|
|
12
|
+
npx --yes @scalableweb/companion@0.3.0 setup
|
|
13
|
+
npx --yes @scalableweb/companion@0.3.0 start
|
|
9
14
|
```
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
16
|
+
Version 0.2.0 uses the previous pairing contract and cannot connect to the updated website.
|
|
17
|
+
|
|
18
|
+
### Run from source
|
|
19
|
+
|
|
20
|
+
Alternatively, install and run the checkout:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
git clone https://github.com/bebraw/scalability_book.git
|
|
24
|
+
cd scalability_book
|
|
25
|
+
npm ci
|
|
26
|
+
npm run companion -- setup
|
|
27
|
+
npm run companion -- start
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The examples below use the registry package; from the checkout, replace `npx --yes @scalableweb/companion@0.3.0` with `npm run companion --`.
|
|
31
|
+
|
|
32
|
+
Guided setup offers notebook-only use, Codex with ChatGPT sign-in, Codex with an OpenAI API key, direct API keys, and a local model in LM Studio.
|
|
33
|
+
It guides authentication and model selection, saves your origin/port preferences and prints the exact start command.
|
|
34
|
+
API keys are entered at a hidden terminal prompt, never in the website.
|
|
35
|
+
Saved keys use the OS credential store; locked or unavailable storage causes an actionable error, with no plaintext fallback.
|
|
36
|
+
Setup and `doctor` do not generate a paid reply; the first message you deliberately send checks generation access and may incur your provider's charges.
|
|
14
37
|
|
|
15
|
-
|
|
38
|
+
Keep the companion running and choose **Notebook → Connect → Connect companion** in the book.
|
|
39
|
+
Enter the printed address if you chose a different port.
|
|
40
|
+
No pairing code is needed.
|
|
41
|
+
The website also offers copyable setup and start commands that preserve its exact origin and any connected notebook's directory/port.
|
|
42
|
+
|
|
43
|
+
Before setup, the only trusted website is `https://scalableweb.dev`.
|
|
44
|
+
Use `setup --origin http://127.0.0.1:3000` for local development; repeat `--origin` to trust multiple exact websites.
|
|
45
|
+
Starting the companion authorizes those websites to create browser sessions and access the local notebook.
|
|
46
|
+
The checkout uses `.local/learning-companion/`; the standalone package uses a stable per-user application directory independently of your working folder and npm's cache.
|
|
47
|
+
Use `--directory` to keep an existing notebook at another location.
|
|
48
|
+
Ctrl+C stops the companion without removing your work.
|
|
49
|
+
|
|
50
|
+
## Choose a provider
|
|
51
|
+
|
|
52
|
+
**Direct API keys** need no Codex installation or ChatGPT subscription.
|
|
53
|
+
Choose OpenAI, Anthropic (Claude), Gemini, OpenRouter or a compatible HTTPS service in guided setup, enter the provider's key, and select a text model by number or exact identifier.
|
|
54
|
+
Setup lists the first twenty catalog entries; an exact identifier can select another listed model.
|
|
55
|
+
Custom services must support an OpenAI-compatible model list and Chat Completions API.
|
|
56
|
+
For Anthropic, use a workspace-scoped key; Companion has no custom workspace-header setting.
|
|
57
|
+
Public catalogs can be read without a valid key, so successful listing alone does not establish authenticated generation access.
|
|
58
|
+
|
|
59
|
+
For scripts, use a key already supplied through your environment:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
npx --yes @scalableweb/companion@0.3.0 setup --api --api-provider openai --model '<exact-model-id>' --api-key-env OPENAI_API_KEY
|
|
63
|
+
npx --yes @scalableweb/companion@0.3.0 start
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The named `--api-provider` choices are `openai`, `anthropic`, `gemini` and `openrouter`.
|
|
67
|
+
Use `--api-provider compatible --api-url https://your-provider.example/v1` for another service.
|
|
68
|
+
Replace example model/URL values with your provider's values.
|
|
69
|
+
The environment variable must remain available when starting or diagnosing the companion; only its name enters settings.
|
|
70
|
+
Alternatively, pipe the key into `setup --api --with-api-key` with the provider/model options, or into `login --with-api-key` after setup, to save it in the OS credential store.
|
|
71
|
+
When using a saved key, interactive API `login` offers a hidden replacement-key prompt.
|
|
72
|
+
An environment-backed setup keeps reading its configured variable; piping a key into `login --with-api-key` explicitly switches to a saved key for later starts.
|
|
73
|
+
Saved API keys are bound to the configured endpoint and a stable notebook credential identity; only the nonsecret `credential-identity.json` is kept beside your records.
|
|
74
|
+
Keys never appear in browser status, diagnostic reports, settings or portable notebook archives.
|
|
75
|
+
The pinned `@napi-rs/keyring` dependency provides native credential storage; Linux saved API keys require a Secret Service session.
|
|
76
|
+
For a headless terminal or unavailable keychain, explicitly choose `--api-key-env`; there is no plaintext or transient-keyring fallback.
|
|
77
|
+
|
|
78
|
+
API mode defaults to discussion-only, a 16,384-token context budget and a 4,096-token output allowance.
|
|
79
|
+
Adjust these with `--api-context` and `--api-output` within your model's limits; reasoning models may need more output room to produce visible text.
|
|
80
|
+
`--api-tools native` is an explicit choice for a model/provider whose function calling you have verified.
|
|
81
|
+
Transport and conversation checks use synthetic responses; real replies and native-tool reliability across these providers are not yet verified for this release.
|
|
82
|
+
|
|
83
|
+
**Codex** requires the separately installed [Codex CLI](https://learn.chatgpt.com/docs/developer-commands?surface=cli), verified at version 0.154.0:
|
|
16
84
|
|
|
17
85
|
```sh
|
|
18
86
|
npm install -g @openai/codex@0.154.0
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
87
|
+
codex --version
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The version command should print `codex-cli 0.154.0`.
|
|
91
|
+
Run guided setup and select ChatGPT sign-in or an OpenAI API key; it authenticates Companion's dedicated profile using Codex's OS keyring store.
|
|
92
|
+
For explicit ChatGPT setup, use `setup --codex`, then `login`.
|
|
93
|
+
For explicit API key setup, use `setup --codex`, then pipe the key:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
printenv OPENAI_API_KEY | npx --yes @scalableweb/companion@0.3.0 login --with-api-key
|
|
22
97
|
```
|
|
23
98
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
`--directory`, `--port`, repeated `--origin`, `--codex-home` and `--model` allow explicit overrides.
|
|
27
|
-
`start --notebook` uses your notes without starting a model.
|
|
99
|
+
Setting that variable alone does not authenticate the dedicated profile.
|
|
100
|
+
See [OpenAI's authentication guide](https://learn.chatgpt.com/docs/auth) for the sign-in methods and API billing.
|
|
28
101
|
|
|
29
|
-
|
|
102
|
+
**Local models** need no Codex installation or sign-in.
|
|
103
|
+
Start LM Studio's server, load a model, then choose local setup or run:
|
|
30
104
|
|
|
31
105
|
```sh
|
|
32
|
-
npx @scalableweb/companion@0.
|
|
106
|
+
npx --yes @scalableweb/companion@0.3.0 setup --local --local-url http://127.0.0.1:1234/v1 --model google/gemma-4-12b-qat
|
|
107
|
+
npx --yes @scalableweb/companion@0.3.0 start
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Replace the verified Gemma example with your loaded model's exact identifier.
|
|
111
|
+
Local mode defaults to discussion-only; use a saved demo result or Chapter guide for actual observations.
|
|
112
|
+
`--local-context <tokens>` supplies the loaded context when the runner cannot report it.
|
|
113
|
+
`--local-tools native` requires a separately verified function-calling setup; the exposed Gemma configuration is verified for discussion only.
|
|
114
|
+
LM Studio is the first verified runner; Ollama, llama.cpp and Windows remain unverified.
|
|
115
|
+
|
|
116
|
+
## Check and retain your work
|
|
117
|
+
|
|
118
|
+
Stop the companion and run `npx --yes @scalableweb/companion@0.3.0 doctor` for checks, or add `--json` for a diagnostic report you choose whether to share.
|
|
119
|
+
The report identifies the saved provider choice, storage, origin/port and prerequisite results without credentials, notes, conversations, remote provider diagnostics or connection tokens.
|
|
120
|
+
Codex is optional in notebook-only, direct API and local-model modes.
|
|
121
|
+
Use `doctor --codex` to require its installation and dedicated-profile sign-in; diagnostics do not change the saved provider choice.
|
|
122
|
+
`start --notebook` lets you keep writing without a model.
|
|
123
|
+
|
|
124
|
+
API and local conversations retain selected context across restarts in separate schema-1 `api-provider.sqlite` and `local-provider.sqlite` files.
|
|
125
|
+
Changing provider/endpoint/model/tool mode requires a new conversation; omission notices and rejected selections retain visible work.
|
|
126
|
+
Portable notebook archives exclude credentials and raw conversations.
|
|
127
|
+
To retain conversation continuity, stop the companion and privately back up its full directory and any separate Codex profile.
|
|
128
|
+
The backup includes credential identifiers and learning records; OS keychain entries remain on the computer.
|
|
129
|
+
Restore your records and sign in again on another computer; a relocated Codex profile also needs fresh login because its keyring identity depends on its path.
|
|
130
|
+
|
|
131
|
+
To migrate a notebook, stop its companion/provider and select a new empty destination:
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
npx --yes @scalableweb/companion@0.3.0 migrate --from /absolute/path/to/old-notebook --directory /absolute/path/to/new-notebook --confirm-stopped
|
|
33
135
|
```
|
|
34
136
|
|
|
35
137
|
Migration retains the source and rejects a nonempty destination.
|
|
36
|
-
|
|
138
|
+
It copies private records, API credential identity and profile threads, but excludes externally created Codex `auth.json` files at every depth.
|
|
139
|
+
Setup preferences are left for explicit setup in the destination.
|
|
140
|
+
Choose the original provider/endpoint/model/tool mode to resume conversations, restore any key environment variable, and run `doctor` with the destination directory.
|
|
37
141
|
An unsupported newer database schema is rejected without rewriting it.
|
|
38
142
|
|
|
143
|
+
`npx --yes @scalableweb/companion@0.3.0 logout` removes the selected API endpoint's OS entry or uses Codex's keyring logout; it retains notebook and conversation records.
|
|
144
|
+
Same-machine API notebook copies with the same credential identity share that keychain entry.
|
|
145
|
+
Environment-backed API logout explains how to unset or revoke the external key without changing the parent environment.
|
|
146
|
+
|
|
39
147
|
See [student setup and recovery](https://scalableweb.dev/notebook/setup/) for the full workflow.
|
|
148
|
+
Model providers process messages and context you explicitly send; course membership gives teachers and peers no access to your private notebook.
|
|
149
|
+
|
|
150
|
+
## Version 0.3.0
|
|
151
|
+
|
|
152
|
+
Connection uses an automatically issued, origin-bound session token with browser protocol 2.
|
|
153
|
+
Reconnect after disconnect, expiry or restart by choosing **Connect companion** again.
|
|
154
|
+
Exact website-origin and literal loopback-host checks precede every route, and private routes require a session.
|
|
155
|
+
Sessions expire after twelve hours; Disconnect revokes them.
|
|
156
|
+
This browser trust boundary does not isolate the service from other native processes on your computer.
|
|
157
|
+
|
|
158
|
+
The teaching assistant retains shared study policy version 1 and recorded source/help/note/provider context.
|
|
159
|
+
Notebook, archive and conversation schemas remain version 1; local and API histories each have schema 1.
|
|
160
|
+
Codex CLI 0.154.0 remains the verified adapter version.
|
|
40
161
|
Release metadata in `dist/release.json` identifies the source revision, package, protocol and storage schemas.
|
|
41
|
-
|
|
162
|
+
Existing setup preferences, notes and profiles remain available when you keep their directories.
|
|
163
|
+
A website update alone does not update an installed companion.
|