@carrieros/cli 0.1.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.
Files changed (53) hide show
  1. package/README.md +305 -0
  2. package/dist/commands/chat.js +93 -0
  3. package/dist/commands/doctor.js +54 -0
  4. package/dist/commands/files.js +33 -0
  5. package/dist/commands/help.js +35 -0
  6. package/dist/commands/history.js +47 -0
  7. package/dist/commands/login.js +59 -0
  8. package/dist/commands/logout.js +15 -0
  9. package/dist/commands/mode-model.js +28 -0
  10. package/dist/commands/models.js +28 -0
  11. package/dist/commands/modes.js +27 -0
  12. package/dist/commands/sessions.js +123 -0
  13. package/dist/commands/upload.js +50 -0
  14. package/dist/commands/usage.js +31 -0
  15. package/dist/commands/version.js +28 -0
  16. package/dist/commands/whoami.js +40 -0
  17. package/dist/main.js +94 -0
  18. package/dist/services/api.js +115 -0
  19. package/dist/services/config.js +72 -0
  20. package/dist/services/context.js +42 -0
  21. package/dist/services/login-flow.js +15 -0
  22. package/dist/services/meta.js +13 -0
  23. package/dist/services/output.js +54 -0
  24. package/dist/services/spinner.js +18 -0
  25. package/dist/shell/shell-chat.js +280 -0
  26. package/dist/shell/shell-commands.js +168 -0
  27. package/dist/shell/shell-prompt.js +48 -0
  28. package/dist/shell/shell-renderer.js +70 -0
  29. package/dist/shell/shell-router.js +21 -0
  30. package/dist/shell/shell.js +139 -0
  31. package/dist/types/index.js +4 -0
  32. package/dist/ui/activity.js +77 -0
  33. package/dist/ui/banner.js +70 -0
  34. package/dist/ui/chat-renderer.js +269 -0
  35. package/dist/ui/code-block.js +52 -0
  36. package/dist/ui/color-picker.js +79 -0
  37. package/dist/ui/colors.js +47 -0
  38. package/dist/ui/command-filter.js +57 -0
  39. package/dist/ui/command-item.js +6 -0
  40. package/dist/ui/command-palette.js +306 -0
  41. package/dist/ui/command-registry.js +47 -0
  42. package/dist/ui/command-renderer.js +55 -0
  43. package/dist/ui/composer-layout.js +27 -0
  44. package/dist/ui/live.js +124 -0
  45. package/dist/ui/logo.js +58 -0
  46. package/dist/ui/markdown.js +151 -0
  47. package/dist/ui/message.js +38 -0
  48. package/dist/ui/select.js +114 -0
  49. package/dist/ui/spinner.js +23 -0
  50. package/dist/ui/sticky-stream.js +64 -0
  51. package/dist/ui/theme.js +63 -0
  52. package/dist/ui/ui.js +75 -0
  53. package/package.json +64 -0
package/README.md ADDED
@@ -0,0 +1,305 @@
1
+ # Carrier OS CLI
2
+
3
+ A Windows-first command-line client for the Carrier OS **public `/v1` API**. It
4
+ proves the full developer workflow end-to-end:
5
+
6
+ ```
7
+ Developer Portal → Generate API Key → Install CLI → Configure Key
8
+ → Chat → Sessions → Files → Usage
9
+ ```
10
+
11
+ This is a **Proof of Concept**. It consumes the existing public API exactly like
12
+ any third-party developer would — **no backend logic is duplicated**. Every
13
+ command is a thin, typed wrapper over an endpoint that already exists.
14
+
15
+ ---
16
+
17
+ ## Installation
18
+
19
+ The CLI installs globally via npm — **no repository cloning required for end
20
+ users** — and exposes two identical launch commands:
21
+
22
+ ```bash
23
+ cos # primary — opens the interactive Carrier OS shell
24
+ carrieros # full-name alias (identical)
25
+ ```
26
+
27
+ ### Beta (current) — install from the tarball
28
+
29
+ Until the package is published, distribute the packed tarball. Build it, then
30
+ install it globally exactly as a published package would install:
31
+
32
+ ```bash
33
+ npm run build
34
+ npm pack # → carrieros-cli-0.1.0.tgz
35
+ npm install -g carrieros-cli-0.1.0.tgz
36
+
37
+ carrieros # or: cos
38
+ ```
39
+
40
+ ### Public release (future)
41
+
42
+ Once `@carrieros/cli` is published, developers install it the same way as Claude
43
+ Code / Vercel CLI:
44
+
45
+ ```bash
46
+ npm install -g @carrieros/cli
47
+
48
+ carrieros # or: cos
49
+ ```
50
+
51
+ Publishing is a **single command** — no refactoring needed:
52
+
53
+ ```bash
54
+ npm publish --access public
55
+ ```
56
+
57
+ ### Update
58
+
59
+ Upgrade to the latest published version at any time:
60
+
61
+ ```bash
62
+ npm install -g @carrieros/cli@latest
63
+ ```
64
+
65
+ Check what you're running with `cos version` — it prints the CLI version
66
+ alongside the API version it's talking to.
67
+
68
+ ### Uninstall
69
+
70
+ Removes both `carrieros` and `cos` from PATH:
71
+
72
+ ```bash
73
+ npm uninstall -g @carrieros/cli
74
+ ```
75
+
76
+ ### For developers — run from source
77
+
78
+ Iterate without reinstalling on every change:
79
+
80
+ ```bash
81
+ git clone <repo-url> carrieros-cli
82
+ cd carrieros-cli
83
+ npm install
84
+ npm run build
85
+ npm link # links `cos` + `carrieros` to your working copy
86
+
87
+ # or run directly, no global install:
88
+ npm run dev -- <command> # tsx, no build step
89
+ node dist/main.js <command>
90
+ ```
91
+
92
+ > `npm link` creates a live junction — rebuilds reflect immediately. Avoid
93
+ > `npm install -g <tarball>` during development: it installs a **frozen copy**
94
+ > that shadows the link. The branded logo is pure Unicode/ANSI (no image
95
+ > assets); Windows `.exe` installers are intentionally **not** part of this POC.
96
+
97
+ ---
98
+
99
+ ## How to use Carrier OS CLI
100
+
101
+ **Prerequisites:** [Node.js](https://nodejs.org) **18+** (`node -v`) and a Carrier
102
+ OS **API secret key** (`carrier_sk_…`) from the Developer Portal
103
+ (**Projects → API keys**).
104
+
105
+ ### 1. Sign in (one-time setup)
106
+
107
+ Authenticate once — your key is stored on your machine
108
+ (`%APPDATA%/CarrierOS/config.json`, or `~/.carrieros/config.json`), never a JWT:
109
+
110
+ ```bash
111
+ cos login # paste carrier_sk_… when prompted
112
+ ```
113
+
114
+ Pointing at a local / self-hosted API instead of production
115
+ (`https://api.carrieros.ai/v1`)? Pass `--url` once:
116
+
117
+ ```bash
118
+ cos login --url http://localhost:5000/v1
119
+ ```
120
+
121
+ Confirm the setup:
122
+
123
+ ```bash
124
+ cos doctor # config, connectivity, key checks
125
+ cos whoami # workspace / project / account
126
+ ```
127
+
128
+ ### 2. Open the interactive shell
129
+
130
+ Run `cos` with **no command** to drop into the interactive shell — the default
131
+ experience. Type a message to chat, or type **`/`** to open the command palette:
132
+
133
+ ```bash
134
+ cos
135
+ ```
136
+
137
+ ```
138
+ ❯ how do I add auth to my Next.js app?
139
+ ● …answer streams in word-by-word…
140
+ ☼ Computed in 3s
141
+
142
+ ❯ /model # switch the AI model (arrow-key picker)
143
+ ❯ /mode # switch the Carrier mode (arrow-key picker)
144
+ ❯ /help # browse every command (arrow-navigable menu)
145
+ ```
146
+
147
+ **Slash commands** (type `/` to filter them live):
148
+
149
+ | Command | Does |
150
+ |---|---|
151
+ | `/model` · `/models` | switch / list provider models (GPT, Grok, Claude, …) |
152
+ | `/mode` · `/modes` | switch / list Carrier modes (general, code, research, …) |
153
+ | `/sessions` · `/session use [id]` · `/session delete <id>` | manage conversations |
154
+ | `/history [id]` · `/clear` | print a transcript · start a fresh session |
155
+ | `/upload <file>` · `/files` | add + list context files |
156
+ | `/whoami` · `/usage` · `/doctor` | account · usage · diagnostics |
157
+ | `/login` · `/logout` · `/version` · `/help` · `/exit` | account · info · quit |
158
+
159
+ **Keys:** `↑ ↓` history · `Tab` complete · `Enter` run · `Ctrl+C` twice to exit.
160
+
161
+ ### 3. Or run one-off commands (scripting / CI)
162
+
163
+ Every slash command is also a plain subcommand, so you can script the CLI without
164
+ the shell:
165
+
166
+ ```bash
167
+ cos chat --mode code # focused chat REPL
168
+ cos sessions # list conversations
169
+ cos history # transcript of the active session
170
+ cos upload ./report.pdf # upload + index a file
171
+ cos usage # requests, tokens, estimated cost
172
+ cos logout # remove the key from this machine
173
+ ```
174
+
175
+ ---
176
+
177
+ ## Commands
178
+
179
+ | Command | Endpoint(s) reused | Purpose |
180
+ |---|---|---|
181
+ | `login [key] [--url]` | `POST /v1/auth/verify` | Store the secret key (only after it verifies) |
182
+ | `logout` | — | Remove the stored key + session |
183
+ | `whoami` | `POST /v1/auth/verify` | Show workspace / project / account |
184
+ | `version` | `GET /v1/health` | CLI + API versions |
185
+ | `doctor` | `GET /v1/health`, `POST /v1/auth/verify` | Config, connectivity, key checks |
186
+ | *(no command)* | `POST /v1/chat` | **Default** — the interactive Carrier OS shell |
187
+ | `chat` | `POST /v1/chat` | Focused chat REPL with a persistent session |
188
+ | `models` | `GET /v1/models/chat` | List provider models (GPT, Grok, Claude, …) |
189
+ | `model [id]` | — | Set the provider model (or `auto`); picker if no id |
190
+ | `modes` | `GET /v1/models` | List Carrier modes (general, code, research, …) |
191
+ | `mode [id]` | — | Set the Carrier mode; picker if no id |
192
+ | `sessions` | `GET /v1/conversations` | List conversations |
193
+ | `session use [id]` | `GET /v1/sessions/:id` | Switch active session |
194
+ | `session delete <id>` | `DELETE /v1/sessions/:id` | Delete a session |
195
+ | `history [id]` | `GET /v1/sessions/:id/messages` | Print a transcript |
196
+ | `clear` | — | Start a fresh session (drops the local pointer) |
197
+ | `upload <file>` | `POST /v1/files` + `…/:id/process` | Upload and index a file |
198
+ | `files` | — (local) | List files uploaded from this machine |
199
+ | `usage` | `GET /v1/usage` | Requests, tokens, estimated cost |
200
+ | `guide` | — | Styled workflow overview |
201
+
202
+ In the interactive shell every command above is also a `/slash` command
203
+ (`/sessions`, `/upload`, `/usage`, …), plus `/model` · `/mode` · `/clear` ·
204
+ `/help` · `/exit`. See [How to use](#how-to-use-carrier-os-cli).
205
+
206
+ ---
207
+
208
+ ## Architecture
209
+
210
+ Layered and dependency-inverted — commands depend on **services**, services
211
+ depend on the **public API contract**, nothing depends on the other direction.
212
+
213
+ ```
214
+ src/
215
+ main.ts # Commander wiring + top-level error handling
216
+ types/index.ts # The /v1 contract, typed (no logic)
217
+ services/
218
+ config.ts # ConfigStore — the only thing that touches disk
219
+ api.ts # ApiClient — the only thing that speaks HTTP
220
+ context.ts # CommandContext — DI passed to every command
221
+ output.ts # chalk formatting + Markdown→ANSI renderer
222
+ spinner.ts # ora spinner helper
223
+ meta.ts # CLI version lookup
224
+ commands/ # one file per command; each `register(program, ctx)`
225
+ login · logout · whoami · version · doctor
226
+ chat · sessions · history (clear lives with sessions)
227
+ upload · files · usage · models · help
228
+ ```
229
+
230
+ **Key design decisions**
231
+
232
+ - **Single HTTP boundary.** `ApiClient` is the only module importing `axios`.
233
+ Each method maps 1:1 to a `/v1` endpoint and returns the already-unwrapped
234
+ `data`, or throws a typed `ApiError` carrying the server's `{code, message}`.
235
+ Adding an endpoint = adding one method.
236
+ - **Single disk boundary.** `ConfigStore` owns `%APPDATA%/CarrierOS/config.json`
237
+ (falls back to `~/.carrieros/config.json`). It stores **only** the secret key,
238
+ the active session id, a cached scope, and recent uploads — **never a JWT**.
239
+ - **Dependency injection.** Every command receives a `CommandContext`
240
+ (`config`, `client()`, `requireAuth()`), so commands are thin and don't reach
241
+ for globals. `requireAuth()` centralizes the "not logged in" guard.
242
+ - **No duplicated business logic.** Modes, cost, extraction, rate limits, semantic
243
+ token stripping — all already handled server-side. The CLI just renders JSON.
244
+ - **Strong typing.** `strict` TypeScript with `noUnusedLocals/Parameters`; the
245
+ entire `/v1` contract is typed in `types/index.ts`.
246
+ - **Windows-first, clean UX.** `chalk` colors, `ora` spinners, `@inquirer/prompts`
247
+ for the masked key prompt and session picker, and a small built-in
248
+ Markdown→ANSI renderer (no markdown dependency).
249
+
250
+ Streaming is **simulated**: the API returns the full response, which the CLI
251
+ then reveals **word-by-word** so it reads like live streaming. Real SSE token
252
+ streaming would require a backend change.
253
+
254
+ ---
255
+
256
+ ## Testing steps
257
+
258
+ Prerequisites: the API running locally (`npm run dev` in `api.carrieros.ai`,
259
+ default `http://localhost:5000`) and a `carrier_sk_` secret key from the
260
+ Developer Portal (Projects → API keys).
261
+
262
+ ```bash
263
+ cd carrieros-cli
264
+ npm install && npm run build
265
+
266
+ # Connectivity (no key needed)
267
+ node dist/main.js login --url http://localhost:5000/v1
268
+ node dist/main.js doctor # ✓ API reachable, ⚠ key not set
269
+ node dist/main.js version # CLI + API versions
270
+
271
+ # Auth
272
+ node dist/main.js login # paste carrier_sk_… → ✓ Logged in
273
+ node dist/main.js whoami # workspace / project / account
274
+ node dist/main.js doctor # now: ✓ Key valid
275
+
276
+ # Chat + sessions
277
+ node dist/main.js models # list Carrier modes
278
+ node dist/main.js chat # ask something; /new, /exit
279
+ node dist/main.js sessions # the session appears, marked ►
280
+ node dist/main.js history # transcript of the active session
281
+ node dist/main.js clear # next message starts fresh
282
+
283
+ # Files + usage
284
+ node dist/main.js upload ./somefile.pdf
285
+ node dist/main.js files
286
+ node dist/main.js usage
287
+
288
+ node dist/main.js logout # key removed from this machine
289
+ ```
290
+
291
+ **Negative checks**
292
+
293
+ ```bash
294
+ node dist/main.js usage # (logged out) → "Run `carrieros login` first."
295
+ node dist/main.js login carrier_sk_bad # → "Invalid API key. (INVALID_API_KEY)"
296
+ node dist/main.js login --url http://localhost:1/v1 && node dist/main.js doctor # → clean NETWORK_ERROR
297
+ ```
298
+
299
+ ---
300
+
301
+ ## Not in this POC
302
+
303
+ No browser OAuth · no billing · no marketplace · no plugins · no agents · no SDK ·
304
+ no IDE integration · no repo awareness · no multi-agent · no auto-updates · no
305
+ `.exe` installers.
@@ -0,0 +1,93 @@
1
+ import { input } from "@inquirer/prompts";
2
+ import chalk from "chalk";
3
+ import { info, line, printBanner } from "../services/output.js";
4
+ import { chatTurn, loadModels, modelLabelShort, pickMode, pickModel, setMode, setModel } from "../shell/shell-chat.js";
5
+ /**
6
+ * `cos chat` — a focused interactive REPL over POST /v1/chat. (The full
7
+ * shell — `cos` with no command — is a superset with every slash command.)
8
+ * All chat/mode/model logic is shared via shell-chat.ts; this is just the loop.
9
+ */
10
+ export function registerChat(program, ctx) {
11
+ program
12
+ .command("chat")
13
+ .description("Start a focused interactive chat session")
14
+ .option("-m, --mode <mode>", "Carrier mode (general, code, research, …)")
15
+ .option("--model <model>", "provider model override (e.g. gpt-5.5); 'auto' to clear")
16
+ .action(async (opts) => {
17
+ if (opts.mode)
18
+ ctx.config.set("mode", opts.mode);
19
+ if (opts.model !== undefined)
20
+ ctx.config.set("model", opts.model === "auto" ? "" : opts.model);
21
+ await runChat(ctx);
22
+ });
23
+ }
24
+ export async function runChat(ctx) {
25
+ const client = ctx.requireAuth();
26
+ // Preload models so the banner can show a friendly label (best-effort).
27
+ await loadModels(client).catch(() => []);
28
+ printBanner(ctx.config.get("scope"), ctx.mode, modelLabelShort(ctx));
29
+ for (;;) {
30
+ let message;
31
+ try {
32
+ message = (await input({ message: chalk.cyan(">") })).trim();
33
+ }
34
+ catch {
35
+ line();
36
+ info("Session ended.");
37
+ return;
38
+ }
39
+ if (!message)
40
+ continue;
41
+ // Parse by the first word so /models and /model aren't shadowed by /mode.
42
+ const cmdWord = message.split(/\s+/)[0].toLowerCase();
43
+ const argStr = message.slice(cmdWord.length).trim();
44
+ if (cmdWord === "/exit" || cmdWord === "/quit") {
45
+ info("Session ended.");
46
+ return;
47
+ }
48
+ if (cmdWord === "/help") {
49
+ printSlashHelp();
50
+ continue;
51
+ }
52
+ if (cmdWord === "/new" || cmdWord === "/clear") {
53
+ ctx.config.set("sessionId", undefined);
54
+ info("Started a new session.");
55
+ continue;
56
+ }
57
+ if (cmdWord === "/session") {
58
+ const sid = ctx.config.get("sessionId");
59
+ info(sid ? `Current session: ${sid}` : "No active session yet (a new one starts on your next message).");
60
+ continue;
61
+ }
62
+ if (cmdWord === "/modes") {
63
+ await pickMode(ctx, client);
64
+ continue;
65
+ }
66
+ if (cmdWord === "/mode") {
67
+ await setMode(ctx, client, argStr);
68
+ continue;
69
+ }
70
+ if (cmdWord === "/models") {
71
+ await pickModel(ctx, client);
72
+ continue;
73
+ }
74
+ if (cmdWord === "/model") {
75
+ await setModel(ctx, client, argStr);
76
+ continue;
77
+ }
78
+ await chatTurn(ctx, client, message);
79
+ }
80
+ }
81
+ function printSlashHelp() {
82
+ line();
83
+ line(chalk.dim(" In-chat commands:"));
84
+ line(` ${chalk.cyan("/modes")} list Carrier modes (behavior)`);
85
+ line(` ${chalk.cyan("/mode <id>")} switch Carrier mode (e.g. /mode code)`);
86
+ line(` ${chalk.cyan("/models")} list provider models (GPT, Grok, …)`);
87
+ line(` ${chalk.cyan("/model <id>")} set model override (e.g. gpt-5.5), or /model auto`);
88
+ line(` ${chalk.cyan("/new")} start a fresh session`);
89
+ line(` ${chalk.cyan("/session")} show the current session id`);
90
+ line(` ${chalk.cyan("/help")} show this help`);
91
+ line(` ${chalk.cyan("/exit")} leave the chat`);
92
+ line();
93
+ }
@@ -0,0 +1,54 @@
1
+ import { ApiError } from "../services/api.js";
2
+ import { cliVersion } from "../services/meta.js";
3
+ import { glyph, heading, line } from "../services/output.js";
4
+ import { withSpinner } from "../services/spinner.js";
5
+ function row(status, label, detail) {
6
+ const g = status === "ok" ? glyph.ok : status === "warn" ? glyph.warn : glyph.err;
7
+ line(` ${g} ${label.padEnd(20)} ${detail}`);
8
+ }
9
+ /**
10
+ * `cos doctor` — one-shot health check of the whole setup:
11
+ * configuration, network/API reachability, key presence and key validity.
12
+ */
13
+ export function registerDoctor(program, ctx) {
14
+ program
15
+ .command("doctor")
16
+ .description("Diagnose configuration, connectivity and authentication")
17
+ .action(async () => {
18
+ const client = ctx.client();
19
+ const apiUrl = ctx.config.get("apiUrl") ?? "—";
20
+ heading("Carrier OS — diagnostics");
21
+ // 1) Configuration
22
+ row("ok", "Configuration", `${ctx.config.file}`);
23
+ row("ok", "Endpoint", apiUrl);
24
+ // 2) Network / API reachability (health needs no key)
25
+ let apiVersion = "unknown";
26
+ try {
27
+ const health = await withSpinner("Pinging API…", () => client.health());
28
+ apiVersion = health.version;
29
+ row("ok", "API reachable", `${health.status} · ${health.version} · ${health.environment}`);
30
+ }
31
+ catch (err) {
32
+ row("err", "API reachable", err instanceof ApiError ? err.message : "unreachable");
33
+ }
34
+ // 3) API key present?
35
+ if (!ctx.config.isAuthenticated) {
36
+ row("warn", "API key", "not set — run `cos login`");
37
+ }
38
+ else {
39
+ row("ok", "API key", "present");
40
+ // 4) API key valid?
41
+ try {
42
+ const scope = await withSpinner("Verifying key…", () => client.verify());
43
+ row("ok", "Key valid", `${scope.workspace.name} / ${scope.project.name}`);
44
+ }
45
+ catch (err) {
46
+ row("err", "Key valid", err instanceof ApiError ? `${err.message} (${err.code})` : "failed");
47
+ }
48
+ }
49
+ // 5) Versions
50
+ row("ok", "CLI version", cliVersion());
51
+ row("ok", "API version", apiVersion);
52
+ line();
53
+ });
54
+ }
@@ -0,0 +1,33 @@
1
+ import { line, timeAgo } from "../services/output.js";
2
+ import { c } from "../ui/colors.js";
3
+ import { emptyState, sectionHeader, twoCol } from "../ui/ui.js";
4
+ /**
5
+ * `cos files` — list files uploaded from this machine.
6
+ *
7
+ * NOTE: the public API has no "list files" endpoint yet, so this reflects the
8
+ * CLI's own record of recent uploads (kept in config). It is purely a local
9
+ * convenience view and duplicates no server logic.
10
+ */
11
+ export function registerFiles(program, ctx) {
12
+ program
13
+ .command("files")
14
+ .description("List files you have uploaded from this machine")
15
+ .action(() => {
16
+ const uploads = ctx.config.get("uploads") ?? [];
17
+ if (uploads.length === 0) {
18
+ for (const l of emptyState("No uploaded files yet.", "Upload one with", "/upload <file>")) {
19
+ line(l);
20
+ }
21
+ return;
22
+ }
23
+ line();
24
+ line(sectionHeader(`Files (${uploads.length})`));
25
+ const rows = uploads.map((f) => [
26
+ f.filename,
27
+ `${f.file_type} · ${timeAgo(f.uploaded_at)} · ${f.file_id.slice(0, 8)}`
28
+ ]);
29
+ for (const l of twoCol(rows, c.value, c.dim))
30
+ line(l);
31
+ line();
32
+ });
33
+ }
@@ -0,0 +1,35 @@
1
+ import chalk from "chalk";
2
+ import { line } from "../services/output.js";
3
+ /**
4
+ * `cos help` — a styled overview of the workflow, complementing
5
+ * Commander's auto-generated `--help`.
6
+ */
7
+ export function registerHelp(program, _ctx) {
8
+ program
9
+ .command("help-overview")
10
+ .alias("guide")
11
+ .description("Show a guided overview of the CLI workflow")
12
+ .action(() => {
13
+ const item = (cmd, desc) => line(` ${chalk.cyan(cmd.padEnd(26))} ${chalk.dim(desc)}`);
14
+ line("\n" + chalk.bold.cyan(" Carrier OS CLI") + chalk.dim(" — developer workflow\n"));
15
+ line(chalk.bold(" Getting started"));
16
+ item("cos login", "store your carrier_sk_ key");
17
+ item("cos doctor", "verify configuration & connectivity");
18
+ item("cos whoami", "show workspace / project / account");
19
+ line("\n" + chalk.bold(" Chat"));
20
+ item("cos", "interactive shell (default)");
21
+ item("cos chat --mode code", "chat in a specific Carrier mode");
22
+ item("cos modes", "list Carrier modes (behavior)");
23
+ item("cos models", "list provider models (GPT, Grok, …)");
24
+ line("\n" + chalk.bold(" Sessions"));
25
+ item("cos sessions", "list conversations");
26
+ item("cos session use [id]", "switch active session");
27
+ item("cos history [id]", "print a transcript");
28
+ item("cos clear", "start a fresh session");
29
+ line("\n" + chalk.bold(" Files & usage"));
30
+ item("cos upload <file>", "upload + process a file");
31
+ item("cos files", "list your uploads");
32
+ item("cos usage", "requests, tokens, cost");
33
+ line("\n" + chalk.dim(" Run `cos <command> --help` for details on any command.\n"));
34
+ });
35
+ }
@@ -0,0 +1,47 @@
1
+ import { ApiError } from "../services/api.js";
2
+ import { errorLine, heading, info, line } from "../services/output.js";
3
+ import { withSpinner } from "../services/spinner.js";
4
+ import { c } from "../ui/colors.js";
5
+ import { renderMarkdown } from "../ui/markdown.js";
6
+ /**
7
+ * `cos history [session]` — print the full transcript of a session
8
+ * (defaults to the active one) via GET /v1/sessions/:id/messages.
9
+ */
10
+ export function registerHistory(program, ctx) {
11
+ program
12
+ .command("history")
13
+ .description("Show the transcript of a session")
14
+ .argument("[session]", "session id (defaults to the active session)")
15
+ .action(async (sessionArg) => {
16
+ const client = ctx.requireAuth();
17
+ const sessionId = sessionArg ?? ctx.config.get("sessionId");
18
+ if (!sessionId) {
19
+ info("No active session. Pass a session id, or start one with `cos chat`.");
20
+ return;
21
+ }
22
+ try {
23
+ const { messages } = await withSpinner("Loading transcript…", () => client.sessionMessages(sessionId));
24
+ if (messages.length === 0) {
25
+ info("This session has no messages yet.");
26
+ return;
27
+ }
28
+ heading(`Transcript · ${sessionId.slice(0, 8)}`);
29
+ for (const m of messages) {
30
+ const who = m.role === "user" ? c.title("You") : c.brand.bold("Carrier");
31
+ line("\n " + who + "\n");
32
+ if (m.role === "assistant") {
33
+ for (const l of renderMarkdown(m.content))
34
+ line(" " + l);
35
+ }
36
+ else {
37
+ line(" " + m.content);
38
+ }
39
+ }
40
+ line();
41
+ }
42
+ catch (err) {
43
+ errorLine(err instanceof ApiError ? `${err.message} (${err.code})` : err.message);
44
+ process.exitCode = 1;
45
+ }
46
+ });
47
+ }
@@ -0,0 +1,59 @@
1
+ import { password } from "@inquirer/prompts";
2
+ import { ApiError } from "../services/api.js";
3
+ import { DEFAULT_API_URL } from "../services/config.js";
4
+ import { verifyAndSaveKey } from "../services/login-flow.js";
5
+ import { errorLine, info, kv, line, success, warn } from "../services/output.js";
6
+ import { withSpinner } from "../services/spinner.js";
7
+ /**
8
+ * `cos login [key]` — API-key login (no browser OAuth in this POC).
9
+ * Validates the key via POST /v1/auth/verify and, on success, stores ONLY the
10
+ * secret key (never a JWT) plus a cached copy of its scope.
11
+ */
12
+ export function registerLogin(program, ctx) {
13
+ program
14
+ .command("login")
15
+ .description("Log in with a Carrier API secret key")
16
+ .argument("[key]", "carrier_sk_… secret key (prompted if omitted)")
17
+ .option("--url <url>", "override the API base URL (e.g. http://localhost:5000/v1)")
18
+ .action(async (keyArg, opts) => {
19
+ if (opts.url)
20
+ ctx.config.set("apiUrl", opts.url.replace(/\/+$/, ""));
21
+ const apiUrl = ctx.config.get("apiUrl") ?? DEFAULT_API_URL;
22
+ const key = keyArg?.trim() ||
23
+ (await password({
24
+ message: "Paste your Carrier API secret key:",
25
+ mask: "•",
26
+ validate: (v) => (v.trim().length > 0 ? true : "A key is required.")
27
+ })).trim();
28
+ if (!key.startsWith("carrier_sk_")) {
29
+ warn("That does not look like a secret key (expected a carrier_sk_… value).");
30
+ }
31
+ try {
32
+ const scope = await withSpinner("Verifying key…", () => verifyAndSaveKey(ctx, apiUrl, key));
33
+ success("Logged in.");
34
+ line();
35
+ kv("Workspace", scope.workspace.name);
36
+ kv("Project", scope.project.name);
37
+ kv("Key", `${scope.apiKey.name} (${scope.apiKey.type})`);
38
+ if (scope.user)
39
+ kv("Account", scope.user.email);
40
+ line();
41
+ info("Try `cos chat` to start talking, or `cos doctor` to check your setup.");
42
+ }
43
+ catch (err) {
44
+ if (err instanceof ApiError) {
45
+ errorLine(`Login failed: ${err.message} (${err.code})`);
46
+ // A 404 or connection error almost always means the endpoint is wrong
47
+ // (e.g. still pointed at production while the API runs locally).
48
+ if (err.code === "NETWORK_ERROR" || err.code.startsWith("HTTP_")) {
49
+ warn(`Endpoint: ${apiUrl}`);
50
+ info("For local development, run: cos login --url http://localhost:5000/v1");
51
+ }
52
+ }
53
+ else {
54
+ errorLine(`Login failed: ${err.message}`);
55
+ }
56
+ process.exitCode = 1;
57
+ }
58
+ });
59
+ }
@@ -0,0 +1,15 @@
1
+ import { info, success } from "../services/output.js";
2
+ /** `cos logout` — forget the stored key, session and cached scope. */
3
+ export function registerLogout(program, ctx) {
4
+ program
5
+ .command("logout")
6
+ .description("Remove the stored API key and session")
7
+ .action(() => {
8
+ if (!ctx.config.isAuthenticated) {
9
+ info("You are already logged out.");
10
+ return;
11
+ }
12
+ ctx.config.clearAuth();
13
+ success("Logged out. Your API key has been removed from this machine.");
14
+ });
15
+ }
@@ -0,0 +1,28 @@
1
+ import { setMode, setModel } from "../shell/shell-chat.js";
2
+ /**
3
+ * Standalone `mode`/`model` setters that mirror the shell's /mode and /model.
4
+ * They reuse the SAME shared helpers, so behavior is identical everywhere:
5
+ * cos mode → list Carrier modes (active marked)
6
+ * cos mode code → set the default mode
7
+ * cos model → list provider models
8
+ * cos model gpt-5.5 → set the model override
9
+ * cos model auto → clear the override (use the mode default)
10
+ */
11
+ export function registerModeModel(program, ctx) {
12
+ program
13
+ .command("mode")
14
+ .description("Show or set the default Carrier mode")
15
+ .argument("[id]", "mode id (e.g. code); omit to list")
16
+ .action(async (id) => {
17
+ const client = ctx.requireAuth();
18
+ await setMode(ctx, client, id ?? "");
19
+ });
20
+ program
21
+ .command("model")
22
+ .description("Show or set the provider model override")
23
+ .argument("[id]", "model id (e.g. gpt-5.5) or 'auto'; omit to list")
24
+ .action(async (id) => {
25
+ const client = ctx.requireAuth();
26
+ await setModel(ctx, client, id ?? "");
27
+ });
28
+ }