@clickminded/coauthor-cli 0.0.35 → 0.0.37
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/dist/commands.d.ts
CHANGED
|
@@ -10,6 +10,7 @@ export type CommandContext = {
|
|
|
10
10
|
token: string;
|
|
11
11
|
};
|
|
12
12
|
export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
|
|
13
|
+
export declare function describeImageOperation(operation: JsonValue | undefined): string | null;
|
|
13
14
|
export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?: (line: string) => void): void;
|
|
14
15
|
/**
|
|
15
16
|
* `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
|
package/dist/commands.js
CHANGED
|
@@ -782,6 +782,9 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
782
782
|
if (getString(input.values, 'prompt') !== undefined) {
|
|
783
783
|
throw new Error('--prompt steers one image: use it with --placeholder-id <id>, not --all.');
|
|
784
784
|
}
|
|
785
|
+
if (getString(input.values, 'idempotency-key') !== undefined) {
|
|
786
|
+
throw new Error('--idempotency-key names one image job: use it with --placeholder-id <id>, not --all (each image gets its own key in data.operations).');
|
|
787
|
+
}
|
|
785
788
|
return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
|
|
786
789
|
}
|
|
787
790
|
if (resource === 'images' && resolvedAction === 'metadata') {
|
|
@@ -830,9 +833,39 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
830
833
|
'edit-prompt',
|
|
831
834
|
]);
|
|
832
835
|
const path = resolvedAction === 'create' && resource !== 'threads' ? basePath : `${basePath}/${resolvedAction}`;
|
|
836
|
+
if (resource === 'images' && (resolvedAction === 'generate' || resolvedAction === 'edit')) {
|
|
837
|
+
return imageOperationRequest(client, input, projectId, path, body, resolvedAction);
|
|
838
|
+
}
|
|
833
839
|
const data = await client.request({ method: 'POST', path, body });
|
|
834
840
|
return { ok: true, data };
|
|
835
841
|
}
|
|
842
|
+
// Image generate/edit is recorded as an image.generate/image.edit operation
|
|
843
|
+
// under its Idempotency-Key: print the key so the caller can follow the job
|
|
844
|
+
// to the finished image (`operation status`) or retry it safely.
|
|
845
|
+
async function imageOperationRequest(client, input, projectId, path, body, action) {
|
|
846
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
847
|
+
const data = await client.request({ method: 'POST', path, body, idempotencyKey });
|
|
848
|
+
const operation = getResponseValue(data, 'operation');
|
|
849
|
+
// A server without image operations returns only the job.
|
|
850
|
+
if (!operation || typeof operation !== 'object' || Array.isArray(operation))
|
|
851
|
+
return { ok: true, data };
|
|
852
|
+
const lookup = `Operation key: ${idempotencyKey} (coauthor operation status ${idempotencyKey} --json).`;
|
|
853
|
+
if (getResponseValue(data, 'replayed') === true) {
|
|
854
|
+
const status = typeof operation.status === 'string' ? operation.status : 'unknown';
|
|
855
|
+
return {
|
|
856
|
+
ok: true,
|
|
857
|
+
message: `Replayed recorded image ${action} operation (${status}); no new job was queued. ${lookup}`,
|
|
858
|
+
idempotency_key: idempotencyKey,
|
|
859
|
+
data,
|
|
860
|
+
};
|
|
861
|
+
}
|
|
862
|
+
return {
|
|
863
|
+
ok: true,
|
|
864
|
+
message: `Image ${action === 'edit' ? 'edit' : 'generation'} queued. ${lookup} Or poll coauthor image status ${projectId} --json.`,
|
|
865
|
+
idempotency_key: idempotencyKey,
|
|
866
|
+
data,
|
|
867
|
+
};
|
|
868
|
+
}
|
|
836
869
|
// Publish and export run as recorded operations keyed by the Idempotency-Key.
|
|
837
870
|
// Print the key so the caller can look the outcome up (`operation status`) or
|
|
838
871
|
// replay the same request safely with --idempotency-key.
|
|
@@ -888,15 +921,37 @@ function exportRequestBody(action, input) {
|
|
|
888
921
|
async function runOperationCommand(action, input, client) {
|
|
889
922
|
const key = getString(input.values, 'id') ?? input.positionals[0];
|
|
890
923
|
if (!action || action === 'list') {
|
|
891
|
-
|
|
924
|
+
const projectId = getString(input.values, 'project');
|
|
925
|
+
const path = projectId ? `operations?project_id=${encodeURIComponent(projectId)}` : 'operations';
|
|
926
|
+
return { ok: true, data: await client.request({ path }) };
|
|
892
927
|
}
|
|
893
928
|
if (action === 'show' || action === 'status') {
|
|
894
929
|
if (!key)
|
|
895
930
|
throw new Error('Usage: coauthor operation status <operationKey>');
|
|
896
|
-
|
|
931
|
+
const data = await client.request({ path: `operations/${encodeURIComponent(key)}` });
|
|
932
|
+
const message = describeImageOperation(getResponseValue(data, 'operation'));
|
|
933
|
+
return message ? { ok: true, message, data } : { ok: true, data };
|
|
897
934
|
}
|
|
898
935
|
throw new Error('Usage: coauthor operation <list|show|status>');
|
|
899
936
|
}
|
|
937
|
+
// One line for an image.generate/image.edit operation, e.g.
|
|
938
|
+
// "image.generate succeeded: https://...". Other operations print as before.
|
|
939
|
+
export function describeImageOperation(operation) {
|
|
940
|
+
if (!operation || typeof operation !== 'object' || Array.isArray(operation))
|
|
941
|
+
return null;
|
|
942
|
+
const action = typeof operation.action === 'string' ? operation.action : '';
|
|
943
|
+
if (action !== 'image.generate' && action !== 'image.edit')
|
|
944
|
+
return null;
|
|
945
|
+
const status = typeof operation.status === 'string' ? operation.status : 'unknown';
|
|
946
|
+
const result = operation.result && typeof operation.result === 'object' && !Array.isArray(operation.result) ? operation.result : {};
|
|
947
|
+
const error = typeof operation.error_message === 'string' ? operation.error_message : null;
|
|
948
|
+
if (status === 'succeeded') {
|
|
949
|
+
return typeof result.final_image_url === 'string' ? `${action} succeeded: ${result.final_image_url}` : `${action} succeeded.`;
|
|
950
|
+
}
|
|
951
|
+
if (status === 'running' || status === 'pending')
|
|
952
|
+
return `${action} running: the image is still generating. Check again shortly.`;
|
|
953
|
+
return error ? `${action} ${status}: ${error}` : `${action} ${status}.`;
|
|
954
|
+
}
|
|
900
955
|
const SKILL_NAMES = ['claude', 'codex', 'agents', 'cursor'];
|
|
901
956
|
const AGENT_LABELS = {
|
|
902
957
|
claude: 'Claude Code',
|
|
@@ -2125,11 +2180,15 @@ async function generateAllImages(client, projectId, wait) {
|
|
|
2125
2180
|
const before = imageStatusRows(await client.request({ path: statusPath }));
|
|
2126
2181
|
const toGenerate = before.filter((row) => row.status !== 'done' && row.status !== 'generating');
|
|
2127
2182
|
const started = [];
|
|
2183
|
+
const operations = [];
|
|
2128
2184
|
const failedToStart = [];
|
|
2129
2185
|
for (const row of toGenerate) {
|
|
2186
|
+
// Each image is its own recorded operation (coauthor operation status <key>).
|
|
2187
|
+
const idempotencyKey = randomUUID();
|
|
2130
2188
|
try {
|
|
2131
|
-
await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id } });
|
|
2189
|
+
await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id }, idempotencyKey });
|
|
2132
2190
|
started.push(row.id);
|
|
2191
|
+
operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
|
|
2133
2192
|
}
|
|
2134
2193
|
catch (error) {
|
|
2135
2194
|
failedToStart.push({ id: row.id, error: error instanceof Error ? error.message : String(error) });
|
|
@@ -2154,6 +2213,7 @@ async function generateAllImages(client, projectId, wait) {
|
|
|
2154
2213
|
failed: wait ? count('failed') : null,
|
|
2155
2214
|
generating,
|
|
2156
2215
|
failed_to_start: failedToStart,
|
|
2216
|
+
operations,
|
|
2157
2217
|
};
|
|
2158
2218
|
return {
|
|
2159
2219
|
ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
|
|
@@ -2372,7 +2432,7 @@ export function helpResult(command = []) {
|
|
|
2372
2432
|
' slideshow show|save',
|
|
2373
2433
|
' publish thread (supports --idempotency-key)',
|
|
2374
2434
|
' export list|wordpress (supports --idempotency-key)',
|
|
2375
|
-
' operation list|show|status',
|
|
2435
|
+
' operation list|show|status (publish, export and image generate/edit)',
|
|
2376
2436
|
' credits',
|
|
2377
2437
|
' share <project-id>',
|
|
2378
2438
|
' models list|preferences show|preferences set',
|
|
@@ -2599,17 +2659,28 @@ function commandHelp(command) {
|
|
|
2599
2659
|
'show: status and the proposed groups. apply: keep every group, or only --accept / all but --reject. discard: drop the revision (cancels it if still running).',
|
|
2600
2660
|
].join('\n'),
|
|
2601
2661
|
'image generate': [
|
|
2602
|
-
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
|
|
2662
|
+
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
|
|
2603
2663
|
'',
|
|
2604
2664
|
'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
|
|
2605
|
-
'Images are drawn from the planned brief. --prompt replaces the
|
|
2665
|
+
'Images are drawn from the planned brief. --prompt replaces what the image shows (the planned scene, its required elements and, on photo + doodle images, the planned doodles)',
|
|
2666
|
+
'and is saved, so later regenerations keep it;',
|
|
2606
2667
|
'the profile\'s visual style still applies. Comparison and technical-diagram images have no scene to replace: generate them, then use image edit --edit-prompt.',
|
|
2607
2668
|
'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
|
|
2669
|
+
'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
|
|
2670
|
+
'--idempotency-key <key> replays an earlier request with that key instead of queueing a second job. With --all, each image gets its own key (data.operations).',
|
|
2608
2671
|
].join('\n'),
|
|
2609
2672
|
'image edit': [
|
|
2610
|
-
'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--json]',
|
|
2673
|
+
'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
|
|
2611
2674
|
'',
|
|
2612
2675
|
'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
|
|
2676
|
+
'Prints an operation key: coauthor operation status <key> reports the edited image url or the error; --idempotency-key <key> replays instead of editing twice.',
|
|
2677
|
+
].join('\n'),
|
|
2678
|
+
operation: [
|
|
2679
|
+
'Usage: coauthor operation list [--project <project-id>] [--json]',
|
|
2680
|
+
' coauthor operation status <key> [--json] (show is the same)',
|
|
2681
|
+
'',
|
|
2682
|
+
'Recorded publish, export and image generate/edit requests, looked up by the operation key the command printed.',
|
|
2683
|
+
'Image operations report succeeded (with data.operation.result.final_image_url), running, failed (with error_message), or unknown (superseded or cleared before it finished).',
|
|
2613
2684
|
].join('\n'),
|
|
2614
2685
|
'contract save': [
|
|
2615
2686
|
'Usage: coauthor contract save <project-id> --data @contract.json [--json]',
|
package/package.json
CHANGED
|
@@ -7,7 +7,8 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
7
7
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
8
8
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
9
9
|
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
10
|
-
- To steer what it shows, add `--prompt "..."`: it replaces the planned scene
|
|
10
|
+
- To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
|
|
11
|
+
- Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
|
|
11
12
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
12
13
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
13
14
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -32,7 +32,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
32
32
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
33
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
34
34
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
35
|
-
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and
|
|
35
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
36
36
|
|
|
37
37
|
## Sign-in
|
|
38
38
|
|
|
@@ -336,7 +336,8 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
336
336
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
337
337
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
338
338
|
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
339
|
-
- To steer what it shows, add `--prompt "..."`: it replaces the planned scene
|
|
339
|
+
- To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
|
|
340
|
+
- Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
|
|
340
341
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
341
342
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
342
343
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -511,7 +512,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
511
512
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
512
513
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
513
514
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
514
|
-
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and
|
|
515
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
515
516
|
|
|
516
517
|
### Sign-in
|
|
517
518
|
|