@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 +280 -0
- package/dist/client.d.ts +27 -0
- package/dist/client.js +82 -0
- package/dist/commands.d.ts +11 -0
- package/dist/commands.js +677 -0
- package/dist/config.d.ts +21 -0
- package/dist/config.js +64 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +51 -0
- package/dist/output.d.ts +8 -0
- package/dist/output.js +15 -0
- package/dist/parser.d.ts +28 -0
- package/dist/parser.js +114 -0
- package/package.json +43 -0
- package/skills/claude/SKILL.md +31 -0
- package/skills/codex/SKILL.md +31 -0
- package/skills/cursor/coauthor-cli.mdc +17 -0
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.
|
package/dist/client.d.ts
ADDED
|
@@ -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>;
|