@clickminded/coauthor-cli 0.0.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 ADDED
@@ -0,0 +1,280 @@
1
+ # CoAuthor CLI
2
+
3
+ `@clickminded/coauthor-cli` is the agent-facing command line for CoAuthor. It lets Codex, Claude Code, Cursor, and human operators work with CoAuthor projects through the versioned JSON API at `/api/agent/v1/*`, instead of using browser-only session routes or direct database access.
4
+
5
+ The package installs the `coauthor` binary.
6
+
7
+ ## Requirements
8
+
9
+ - Node.js 20 or newer.
10
+ - A running CoAuthor web app with the agent API enabled.
11
+ - The agent API database migration applied.
12
+ - `COAUTHOR_API_TOKEN_PEPPER` configured on the web app.
13
+ - A CoAuthor web account for browser-based device authorization.
14
+
15
+ For local development, the default API base URL is `http://localhost:3000`.
16
+
17
+ ## Local Development Install
18
+
19
+ From the monorepo root:
20
+
21
+ ```sh
22
+ pnpm install
23
+ pnpm --filter @clickminded/coauthor-cli build
24
+ node packages/cli/dist/index.js help
25
+ ```
26
+
27
+ For a shorter local command while developing:
28
+
29
+ ```sh
30
+ alias coauthor='node /Users/eduardoyi/Coding/CoAuthor/packages/cli/dist/index.js'
31
+ ```
32
+
33
+ Or run through pnpm:
34
+
35
+ ```sh
36
+ pnpm --filter @clickminded/coauthor-cli build
37
+ node packages/cli/dist/index.js auth status --base-url http://localhost:3000
38
+ ```
39
+
40
+ ## npm Install
41
+
42
+ The package is published as a public scoped npm package:
43
+
44
+ ```json
45
+ {
46
+ "name": "@clickminded/coauthor-cli",
47
+ "publishConfig": {
48
+ "access": "public"
49
+ }
50
+ }
51
+ ```
52
+
53
+ Install globally:
54
+
55
+ ```sh
56
+ npm install -g @clickminded/coauthor-cli
57
+ coauthor auth status
58
+ ```
59
+
60
+ Agents can also use an ephemeral install:
61
+
62
+ ```sh
63
+ npx @clickminded/coauthor-cli auth status
64
+ ```
65
+
66
+ The CLI is public, but project data is not. Every API call still requires a scoped CoAuthor token issued by browser/device login.
67
+
68
+ ## Authentication
69
+
70
+ Start browser/device login:
71
+
72
+ ```sh
73
+ coauthor auth login --base-url http://localhost:3000
74
+ ```
75
+
76
+ Request publish/export permission during login:
77
+
78
+ ```sh
79
+ coauthor auth login --base-url http://localhost:3000 --with-publish
80
+ ```
81
+
82
+ The CLI opens `/cli/authorize` in the browser. Approving there issues a scoped API token for the signed-in CoAuthor user.
83
+
84
+ Check the current token:
85
+
86
+ ```sh
87
+ coauthor auth status --json
88
+ ```
89
+
90
+ Log out and clear local credentials:
91
+
92
+ ```sh
93
+ coauthor auth logout
94
+ ```
95
+
96
+ Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600` permissions. Do not print, paste, or commit this file.
97
+
98
+ Environment variables override the config file:
99
+
100
+ ```sh
101
+ COAUTHOR_BASE_URL=http://localhost:3000
102
+ COAUTHOR_TOKEN=coauthor_xxx
103
+ ```
104
+
105
+ Global options are:
106
+
107
+ - `--json` for machine-readable output.
108
+ - `--base-url <url>` to target a specific CoAuthor app.
109
+ - `--token <token>` for non-persistent token injection.
110
+ - `--data '<json>'` to send command-specific JSON request bodies.
111
+
112
+ ## Agent Skills
113
+
114
+ Install agent instructions after installing the CLI:
115
+
116
+ ```sh
117
+ coauthor skills install all
118
+ ```
119
+
120
+ Install one target at a time:
121
+
122
+ ```sh
123
+ coauthor skills install codex
124
+ coauthor skills install claude
125
+ coauthor skills install cursor
126
+ ```
127
+
128
+ Default install paths are:
129
+
130
+ - Codex: `~/.codex/skills/coauthor/SKILL.md`
131
+ - Claude: `./.claude/skills/coauthor/SKILL.md`
132
+ - Cursor: `./.cursor/rules/coauthor-cli.mdc`
133
+
134
+ Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install Claude/Cursor skills into a specific project.
135
+
136
+ ## Commands
137
+
138
+ Projects:
139
+
140
+ ```sh
141
+ coauthor project create --topic "..."
142
+ coauthor project list --json
143
+ coauthor project show <project-id> --json
144
+ coauthor workspace show <project-id> --json
145
+ ```
146
+
147
+ Chat and workflow:
148
+
149
+ ```sh
150
+ coauthor chat <project-id> --message "..." --json
151
+ coauthor workflow status <project-id> --json
152
+ coauthor workflow advance <project-id> --stage contract --json
153
+ coauthor workflow run <project-id> --target draft --wait --json
154
+ coauthor workflow run <project-id> --target draft --briefing-mode auto --wait --json
155
+ coauthor workflow run <project-id> --target outline --briefing-mode strict --max-brief-questions 2 --json
156
+ coauthor workflow rewind <project-id> --stage outline --reason "..." --json
157
+ coauthor workflow approve <project-id> --stage research_plan --json
158
+ ```
159
+
160
+ `--briefing-mode` controls the bounded contract review before the CLI moves from brainstorming to outline:
161
+
162
+ - `auto` (default): enrich a thin brief and continue when the reviewer can make safe assumptions.
163
+ - `strict`: stop with structured clarification questions unless the brief is clearly strong enough.
164
+ - `off`: preserve the old direct approval behavior.
165
+
166
+ `--require-brief-review` is equivalent to strict mode. If the review needs input, the command returns `ok: true` with `data.status = "needs_clarification"` and a `clarification_questions` array instead of entering an open-ended brainstorm.
167
+
168
+ Artifacts:
169
+
170
+ ```sh
171
+ coauthor contract show <project-id> --json
172
+ coauthor contract save <project-id> --data '{"contract":{}}' --json
173
+ coauthor contract approve <project-id> --json
174
+
175
+ coauthor outline show <project-id> --json
176
+ coauthor outline generate <project-id> --json
177
+ coauthor outline save <project-id> --data '{"outline":{}}' --json
178
+ coauthor outline approve <project-id> --json
179
+
180
+ coauthor research-plan show <project-id> --json
181
+ coauthor research-plan generate <project-id> --json
182
+ coauthor research-plan save <project-id> --data '{"plan":{}}' --json
183
+ coauthor research-plan approve <project-id> --json
184
+ ```
185
+
186
+ Research and draft generation:
187
+
188
+ ```sh
189
+ coauthor research run <project-id> --wait --json
190
+ coauthor research status <project-id> --json
191
+ coauthor research structured <project-id> --json
192
+
193
+ coauthor draft generate <project-id> --wait --json
194
+ coauthor draft status <project-id> --json
195
+ coauthor draft get <project-id> --format json --json
196
+ coauthor draft get <project-id> --format markdown --json
197
+ coauthor draft save <project-id> --data '{"document_id":"...","content":{},"expected_base_version":1}' --json
198
+ ```
199
+
200
+ Images and threads:
201
+
202
+ ```sh
203
+ coauthor image list <project-id> --json
204
+ coauthor image status <project-id> --json
205
+ coauthor image show <project-id> <image-id> --json
206
+ coauthor image generate <project-id> --prompt "..." --json
207
+
208
+ coauthor thread list <project-id> --json
209
+ coauthor thread show <project-id> --json
210
+ coauthor thread generate <project-id> --json
211
+ coauthor thread save <project-id> --data '{"posts":[]}' --json
212
+ ```
213
+
214
+ Live publish/export actions:
215
+
216
+ ```sh
217
+ coauthor publish thread <project-id> --yes --json
218
+ coauthor export blog <project-id> --yes --slug "post-slug" --json
219
+ coauthor export clickminded <project-id> --yes --json
220
+ coauthor operation status <operation-key> --json
221
+ ```
222
+
223
+ Live actions require both token scope and `--yes`.
224
+
225
+ ## Agent Usage Rules
226
+
227
+ Agents should:
228
+
229
+ - Prefer `coauthor` over browser automation, `curl` to session APIs, or direct database access.
230
+ - Use `--json` on every command they need to parse.
231
+ - Use `--wait` when starting long-running research or draft jobs and the user expects completion.
232
+ - Avoid retrying publish/export after uncertain network failures.
233
+ - Use `coauthor operation status <operation-key>` after uncertainty.
234
+ - Never print tokens, cookies, service-role keys, or authorization headers.
235
+
236
+ ## Public API Stability
237
+
238
+ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
239
+
240
+ - Existing commands should keep stable JSON envelopes.
241
+ - New behavior should be additive when possible.
242
+ - Errors should stay structured and machine-readable with `--json`.
243
+ - Server-side auth, ownership checks, scopes, and rate limits remain mandatory.
244
+
245
+ ## Release Checklist
246
+
247
+ Before publishing:
248
+
249
+ ```sh
250
+ pnpm --filter @clickminded/coauthor-cli test
251
+ pnpm --filter @clickminded/coauthor-cli build
252
+ cd packages/cli
253
+ npm pack --dry-run
254
+ ```
255
+
256
+ Release by bumping `packages/cli/package.json`, committing, and pushing a tag:
257
+
258
+ ```sh
259
+ git tag @clickminded/coauthor-cli@0.0.2
260
+ git push origin @clickminded/coauthor-cli@0.0.2
261
+ ```
262
+
263
+ The `Publish CLI` GitHub Action publishes to npm through Trusted Publishing. After release:
264
+
265
+ ```sh
266
+ npx @clickminded/coauthor-cli help
267
+ npx @clickminded/coauthor-cli auth status
268
+ ```
269
+
270
+ ## Troubleshooting
271
+
272
+ `No token configured` means the CLI has no credential for the selected base URL. Run `coauthor auth login --base-url <url>`.
273
+
274
+ `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
275
+
276
+ `authorization_pending` during login is normal while the browser approval page is still waiting.
277
+
278
+ If local commands can authenticate but workflow jobs never finish, confirm both the web app and worker are running.
279
+
280
+ If database migration via direct Postgres DNS fails locally, apply the migration through the Supabase SQL editor or another network path that can reach the database.
@@ -0,0 +1,27 @@
1
+ export type JsonValue = string | number | boolean | null | JsonValue[] | {
2
+ [key: string]: JsonValue;
3
+ };
4
+ export type AgentClientOptions = {
5
+ baseUrl: string;
6
+ token?: string;
7
+ fetchImpl?: typeof fetch;
8
+ };
9
+ export type RequestOptions = {
10
+ method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
11
+ path: string;
12
+ body?: JsonValue;
13
+ idempotencyKey?: string;
14
+ };
15
+ export declare class AgentHttpError extends Error {
16
+ readonly status: number;
17
+ readonly responseBody: unknown;
18
+ constructor(status: number, responseBody: unknown);
19
+ }
20
+ export declare class AgentClient {
21
+ private readonly baseUrl;
22
+ private readonly token;
23
+ private readonly fetchImpl;
24
+ constructor(options: AgentClientOptions);
25
+ request(options: RequestOptions): Promise<JsonValue>;
26
+ }
27
+ export declare function isLiveAction(method: string): boolean;
package/dist/client.js ADDED
@@ -0,0 +1,82 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { z } from 'zod';
3
+ const jsonValueSchema = z.lazy(() => z.union([
4
+ z.string(),
5
+ z.number(),
6
+ z.boolean(),
7
+ z.null(),
8
+ z.array(jsonValueSchema),
9
+ z.record(z.string(), jsonValueSchema),
10
+ ]));
11
+ export class AgentHttpError extends Error {
12
+ status;
13
+ responseBody;
14
+ constructor(status, responseBody) {
15
+ super(`Request failed with HTTP ${status}`);
16
+ this.name = 'AgentHttpError';
17
+ this.status = status;
18
+ this.responseBody = responseBody;
19
+ }
20
+ }
21
+ export class AgentClient {
22
+ baseUrl;
23
+ token;
24
+ fetchImpl;
25
+ constructor(options) {
26
+ this.baseUrl = new URL('/api/agent/v1/', normalizeBaseUrl(options.baseUrl));
27
+ this.token = options.token ?? '';
28
+ this.fetchImpl = options.fetchImpl ?? fetch;
29
+ }
30
+ async request(options) {
31
+ const method = options.method ?? 'GET';
32
+ const url = new URL(trimLeadingSlash(options.path), this.baseUrl);
33
+ const headers = new Headers({
34
+ Accept: 'application/json',
35
+ });
36
+ if (this.token)
37
+ headers.set('Authorization', `Bearer ${this.token}`);
38
+ if (options.body !== undefined)
39
+ headers.set('Content-Type', 'application/json');
40
+ if (isLiveAction(method))
41
+ headers.set('Idempotency-Key', options.idempotencyKey ?? randomUUID());
42
+ const response = await this.fetchImpl(url, {
43
+ method,
44
+ headers,
45
+ body: options.body === undefined ? undefined : JSON.stringify(jsonValueSchema.parse(options.body)),
46
+ });
47
+ const responseBody = await readResponseBody(response);
48
+ if (!response.ok)
49
+ throw new AgentHttpError(response.status, responseBody);
50
+ const parsedBody = jsonValueSchema.parse(responseBody ?? null);
51
+ if (parsedBody
52
+ && typeof parsedBody === 'object'
53
+ && !Array.isArray(parsedBody)
54
+ && parsedBody.ok === true
55
+ && 'data' in parsedBody) {
56
+ return jsonValueSchema.parse(parsedBody.data);
57
+ }
58
+ return parsedBody;
59
+ }
60
+ }
61
+ export function isLiveAction(method) {
62
+ return !['GET', 'HEAD', 'OPTIONS'].includes(method.toUpperCase());
63
+ }
64
+ async function readResponseBody(response) {
65
+ if (response.status === 204)
66
+ return null;
67
+ const text = await response.text();
68
+ if (!text)
69
+ return null;
70
+ try {
71
+ return JSON.parse(text);
72
+ }
73
+ catch {
74
+ return text;
75
+ }
76
+ }
77
+ function normalizeBaseUrl(baseUrl) {
78
+ return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
79
+ }
80
+ function trimLeadingSlash(path) {
81
+ return path.replace(/^\/+/, '');
82
+ }
@@ -0,0 +1,11 @@
1
+ import { AgentClient } from './client.js';
2
+ import { type ConfigPaths } from './config.js';
3
+ import type { CommandResult } from './output.js';
4
+ import { type ParsedCommand } from './parser.js';
5
+ export type CommandContext = {
6
+ client: AgentClient;
7
+ paths?: ConfigPaths;
8
+ baseUrl: string;
9
+ token: string;
10
+ };
11
+ export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;