@clickminded/coauthor-cli 0.0.80 → 0.0.81
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.js +120 -17
- package/dist/index.js +9 -2
- package/package.json +1 -1
- package/skills/coauthor/references/brief-and-contract.md +2 -0
- package/skills/coauthor/references/images-and-social.md +1 -1
- package/skills/coauthor/references/publishing-and-export.md +1 -1
- package/skills/cursor/coauthor-cli.mdc +4 -2
package/dist/commands.js
CHANGED
|
@@ -430,10 +430,29 @@ async function runWorkflowCommand(action, input, context) {
|
|
|
430
430
|
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
|
|
431
431
|
}
|
|
432
432
|
const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
433
|
+
// A draft that already finished (e.g. after `workflow run --wait` timed out while it kept going) is reported
|
|
434
|
+
// as done. Dispatching again only returned the worker's dedupe ("draft_running", already_running: true).
|
|
435
|
+
if (isDraftComplete(draftStatus)) {
|
|
436
|
+
return {
|
|
437
|
+
ok: true,
|
|
438
|
+
status: 'draft_generated',
|
|
439
|
+
message: draftCompletionMessage('Draft already complete; nothing was started', draftStatus),
|
|
440
|
+
data: { status: 'draft_generated', draft_status: draftStatus },
|
|
441
|
+
};
|
|
442
|
+
}
|
|
433
443
|
if (['paused_requires_key', 'paused_credits_exhausted'].includes(getResponseString(draftStatus, 'phase') ?? '')) {
|
|
434
444
|
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
|
|
435
445
|
return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
436
446
|
}
|
|
447
|
+
// Research still running or being structured: attach and wait instead of starting anything (item 46).
|
|
448
|
+
const researchRun = extractNestedString(researchStatus, ['run', 'status']);
|
|
449
|
+
const researchState = getResponseString(researchStatus, 'project_state') ?? getResponseString(draftStatus, 'project_state');
|
|
450
|
+
if (researchRun === 'running' || researchState === 'research_running' || researchState === 'research_complete') {
|
|
451
|
+
const attached = { target: 'draft', status: 'research_running', attached: true };
|
|
452
|
+
return getBoolean(input.values, 'wait')
|
|
453
|
+
? waitForWorkflowDraft(client, projectId, attached, context.baseUrl, modelOverrides)
|
|
454
|
+
: { ok: true, status: 'research_running', message: `Research is still running or being structured; nothing was restarted. Wait with: coauthor workflow resume ${projectId} --target draft --wait --json`, data: { ...attached, research_status: researchStatus } };
|
|
455
|
+
}
|
|
437
456
|
const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target, ...modelOverrides } });
|
|
438
457
|
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
|
|
439
458
|
}
|
|
@@ -593,7 +612,15 @@ async function runArtifactCommand(artifact, action, input, client) {
|
|
|
593
612
|
]);
|
|
594
613
|
const path = action === 'save' ? basePath : `${basePath}/${action}`;
|
|
595
614
|
const data = await client.request({ method: 'POST', path, body });
|
|
596
|
-
return
|
|
615
|
+
// These calls finish before they return (no --wait needed). Say what state the artifact is in: a bare
|
|
616
|
+
// payload read as `state: None` to agents (dogfood Nov 2026, item 56).
|
|
617
|
+
const status = action === 'approve' ? 'approved' : action === 'generate' ? 'generated' : 'saved';
|
|
618
|
+
const sections = getResponseValue(data, 'sections');
|
|
619
|
+
const tasks = getResponseValue(data, 'research_tasks');
|
|
620
|
+
const count = Array.isArray(sections) ? ` (${sections.length} sections)` : Array.isArray(tasks) ? ` (${tasks.length} research tasks)` : '';
|
|
621
|
+
const name = artifact === 'research-plan' ? 'Research plan' : artifact === 'outline' ? 'Outline' : 'Contract';
|
|
622
|
+
const next = action === 'approve' ? '' : artifact === 'contract' ? '' : ` Not approved yet: coauthor ${artifact} approve <project-id>.`;
|
|
623
|
+
return { ok: true, status, message: `${name} ${status}${count}.${next}`, data };
|
|
597
624
|
}
|
|
598
625
|
throw new Error(`Usage: coauthor ${artifact} <${artifact === 'contract' ? 'show|save|approve' : 'show|generate|save|approve'}> <projectId>`);
|
|
599
626
|
}
|
|
@@ -1142,6 +1169,8 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
|
|
|
1142
1169
|
data,
|
|
1143
1170
|
};
|
|
1144
1171
|
}
|
|
1172
|
+
if (getBoolean(input.values, 'wait'))
|
|
1173
|
+
return waitForImageOperation(client, idempotencyKey, action, data);
|
|
1145
1174
|
return {
|
|
1146
1175
|
ok: true,
|
|
1147
1176
|
message: `Image ${action === 'edit' ? 'edit' : 'generation'} queued. ${lookup} Or poll coauthor image status ${projectId} --json.`,
|
|
@@ -1149,6 +1178,39 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
|
|
|
1149
1178
|
data,
|
|
1150
1179
|
};
|
|
1151
1180
|
}
|
|
1181
|
+
const IMAGE_OPERATION_DONE = new Set(['succeeded', 'failed', 'unknown']);
|
|
1182
|
+
/** `image generate|edit --wait`: follows the recorded operation until the image is finished or failed (up to 9 minutes). */
|
|
1183
|
+
async function waitForImageOperation(client, idempotencyKey, action, queued) {
|
|
1184
|
+
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
1185
|
+
const pollMs = Math.max(waitPollMs(), 0);
|
|
1186
|
+
let latest = queued;
|
|
1187
|
+
let status = 'queued';
|
|
1188
|
+
while (Date.now() < deadline) {
|
|
1189
|
+
await sleep(Math.min(pollMs, 15_000));
|
|
1190
|
+
latest = await client.request({ path: `operations/${encodeURIComponent(idempotencyKey)}` });
|
|
1191
|
+
const operation = getResponseValue(latest, 'operation');
|
|
1192
|
+
status = operation && typeof operation === 'object' && !Array.isArray(operation) && typeof operation.status === 'string' ? operation.status : 'unknown';
|
|
1193
|
+
if (IMAGE_OPERATION_DONE.has(status)) {
|
|
1194
|
+
const message = describeImageOperation(operation) ?? `image.${action} ${status}.`;
|
|
1195
|
+
return {
|
|
1196
|
+
ok: status === 'succeeded',
|
|
1197
|
+
status: status === 'succeeded' ? undefined : status === 'failed' ? 'failed' : 'unknown',
|
|
1198
|
+
exitCode: status === 'succeeded' ? undefined : 1,
|
|
1199
|
+
message,
|
|
1200
|
+
idempotency_key: idempotencyKey,
|
|
1201
|
+
data: latest,
|
|
1202
|
+
};
|
|
1203
|
+
}
|
|
1204
|
+
}
|
|
1205
|
+
return {
|
|
1206
|
+
ok: true,
|
|
1207
|
+
status: 'still_running',
|
|
1208
|
+
exitCode: 2,
|
|
1209
|
+
message: `Image ${action} is still running. Keep waiting with: coauthor operation status ${idempotencyKey} --json`,
|
|
1210
|
+
idempotency_key: idempotencyKey,
|
|
1211
|
+
data: latest,
|
|
1212
|
+
};
|
|
1213
|
+
}
|
|
1152
1214
|
const IMAGE_ARTIFACTS = ['article', 'slideshow', 'video'];
|
|
1153
1215
|
// `--artifact article|slideshow|video` narrows image list/status (and
|
|
1154
1216
|
// generate --all) to one artifact's placeholders. Without it, every image.
|
|
@@ -1294,8 +1356,11 @@ async function runOperationCommand(action, input, client) {
|
|
|
1294
1356
|
if (!key)
|
|
1295
1357
|
throw new Error('Usage: coauthor operation status <operationKey>');
|
|
1296
1358
|
const data = await client.request({ path: `operations/${encodeURIComponent(key)}` });
|
|
1297
|
-
const
|
|
1298
|
-
|
|
1359
|
+
const operation = getResponseValue(data, 'operation');
|
|
1360
|
+
const message = describeImageOperation(operation);
|
|
1361
|
+
// Mirror the operation's status at the top level: agents polling `status` read None (item 83).
|
|
1362
|
+
const status = operation && typeof operation === 'object' && !Array.isArray(operation) && typeof operation.status === 'string' ? operation.status : undefined;
|
|
1363
|
+
return { ok: true, ...(status ? { status } : {}), ...(message ? { message } : {}), data };
|
|
1299
1364
|
}
|
|
1300
1365
|
throw new Error('Usage: coauthor operation <list|show|status>');
|
|
1301
1366
|
}
|
|
@@ -1703,7 +1768,16 @@ export function draftCompletionMessage(base, status) {
|
|
|
1703
1768
|
const record = check;
|
|
1704
1769
|
const open = Array.isArray(record.unresolved) ? record.unresolved.length : 0;
|
|
1705
1770
|
if (record.status === 'needs_review' && open > 0) {
|
|
1706
|
-
|
|
1771
|
+
// Name each item: "may miss part of the brief" alone did not say which part (dogfood Nov 2026, ca17ad34).
|
|
1772
|
+
const lines = record.unresolved.slice(0, 8).map((item) => {
|
|
1773
|
+
const issue = item && typeof item === 'object' && !Array.isArray(item) ? item : {};
|
|
1774
|
+
const where = typeof issue.section_heading === 'string' && issue.section_heading ? ` [${issue.section_heading}]` : '';
|
|
1775
|
+
const detail = typeof issue.detail === 'string' ? issue.detail : String(issue.kind ?? 'issue');
|
|
1776
|
+
const requirement = typeof issue.requirement === 'string' && issue.requirement ? ` Brief item: "${issue.requirement}".` : '';
|
|
1777
|
+
return `- ${String(issue.kind ?? 'issue')}${where}: ${detail}${requirement}`;
|
|
1778
|
+
});
|
|
1779
|
+
const more = open > lines.length ? `\n- …and ${open - lines.length} more in quality_check.unresolved` : '';
|
|
1780
|
+
return `${base}, with ${open} draft check ${open === 1 ? 'item' : 'items'} to review (quality_check.unresolved):\n${lines.join('\n')}${more}`;
|
|
1707
1781
|
}
|
|
1708
1782
|
if (record.status === 'failed')
|
|
1709
1783
|
return `${base}; the draft check could not run, so check it against the brief yourself.`;
|
|
@@ -1716,10 +1790,9 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
|
|
|
1716
1790
|
while (Date.now() < deadline) {
|
|
1717
1791
|
await sleep(pollMs);
|
|
1718
1792
|
latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
1719
|
-
const state = getResponseString(latest, 'project_state');
|
|
1720
1793
|
const phase = getResponseString(latest, 'phase');
|
|
1721
|
-
if (
|
|
1722
|
-
return { ok: true, message: draftCompletionMessage('Draft completed', latest), data: latest };
|
|
1794
|
+
if (isDraftComplete(latest)) {
|
|
1795
|
+
return { ok: true, status: 'draft_generated', message: draftCompletionMessage('Draft completed', latest), data: latest };
|
|
1723
1796
|
}
|
|
1724
1797
|
if (phase === 'paused_requires_key')
|
|
1725
1798
|
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
|
|
@@ -1730,6 +1803,17 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
|
|
|
1730
1803
|
}
|
|
1731
1804
|
return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
|
|
1732
1805
|
}
|
|
1806
|
+
/**
|
|
1807
|
+
* The draft is done only when the project says so. The status row keeps the previous draft's "complete" phase
|
|
1808
|
+
* until the worker picks up a new job, so `phase: complete` while the project is still research_structured is
|
|
1809
|
+
* stale: resume used to report "Workflow target draft completed" a minute before the draft finished (item 46).
|
|
1810
|
+
*/
|
|
1811
|
+
function isDraftComplete(draftStatus) {
|
|
1812
|
+
const state = getResponseString(draftStatus, 'project_state');
|
|
1813
|
+
if (state === 'draft_generated' || state === 'editing')
|
|
1814
|
+
return true;
|
|
1815
|
+
return state === undefined && getResponseString(draftStatus, 'phase') === 'complete';
|
|
1816
|
+
}
|
|
1733
1817
|
async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, modelOverrides = {}) {
|
|
1734
1818
|
const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
|
|
1735
1819
|
const pollMs = waitPollMs();
|
|
@@ -1743,11 +1827,15 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
|
|
|
1743
1827
|
latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
1744
1828
|
const draftState = getResponseString(latestDraft, 'project_state');
|
|
1745
1829
|
const draftPhase = getResponseString(latestDraft, 'phase');
|
|
1746
|
-
if (
|
|
1830
|
+
if (isDraftComplete(latestDraft)) {
|
|
1831
|
+
// `status` is the final state. `workflow` is the start request's reply, whose own status
|
|
1832
|
+
// ("draft_running") describes the moment the wait began, not now.
|
|
1747
1833
|
return {
|
|
1748
1834
|
ok: true,
|
|
1835
|
+
status: 'draft_generated',
|
|
1749
1836
|
message: draftCompletionMessage('Workflow target draft completed', latestDraft),
|
|
1750
1837
|
data: {
|
|
1838
|
+
status: 'draft_generated',
|
|
1751
1839
|
workflow: initialData,
|
|
1752
1840
|
research_status: latestResearch,
|
|
1753
1841
|
draft_generate: draftGenerate,
|
|
@@ -3317,6 +3405,17 @@ function imageStatusRows(data) {
|
|
|
3317
3405
|
// Generates every planned image that isn't already done or generating, then
|
|
3318
3406
|
// optionally waits (under the 10-minute agent shell limit) until none are
|
|
3319
3407
|
// still generating.
|
|
3408
|
+
/** The server's own error message when there is one ("Worker responded with 502."), else the error text. */
|
|
3409
|
+
function requestErrorText(error) {
|
|
3410
|
+
const body = error && typeof error === 'object' && 'responseBody' in error ? error.responseBody : null;
|
|
3411
|
+
const envelope = body && typeof body === 'object' && !Array.isArray(body) ? body.error : null;
|
|
3412
|
+
if (envelope && typeof envelope === 'object' && !Array.isArray(envelope)) {
|
|
3413
|
+
const { code, message } = envelope;
|
|
3414
|
+
if (typeof message === 'string' && message)
|
|
3415
|
+
return typeof code === 'string' && code ? `${message} (${code})` : message;
|
|
3416
|
+
}
|
|
3417
|
+
return error instanceof Error ? error.message : String(error);
|
|
3418
|
+
}
|
|
3320
3419
|
async function generateAllImages(client, projectId, wait, artifactQuery = '') {
|
|
3321
3420
|
const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
|
|
3322
3421
|
const before = imageStatusRows(await client.request({ path: statusPath }));
|
|
@@ -3333,7 +3432,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
|
|
|
3333
3432
|
operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
|
|
3334
3433
|
}
|
|
3335
3434
|
catch (error) {
|
|
3336
|
-
failedToStart.push({ id: row.id, error:
|
|
3435
|
+
failedToStart.push({ id: row.id, error: requestErrorText(error) });
|
|
3337
3436
|
}
|
|
3338
3437
|
}
|
|
3339
3438
|
let rows = before;
|
|
@@ -3352,7 +3451,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
|
|
|
3352
3451
|
started: started.length,
|
|
3353
3452
|
already_done: before.filter((row) => row.status === 'done').length,
|
|
3354
3453
|
done: wait ? count('done') : null,
|
|
3355
|
-
failed: wait ? count('failed') : null,
|
|
3454
|
+
failed: wait ? count('failed') + failedToStart.length : failedToStart.length || null,
|
|
3356
3455
|
generating,
|
|
3357
3456
|
failed_to_start: failedToStart,
|
|
3358
3457
|
operations,
|
|
@@ -3361,9 +3460,11 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
|
|
|
3361
3460
|
ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
|
|
3362
3461
|
status: wait && generating > 0 ? 'still_running' : undefined,
|
|
3363
3462
|
exitCode: wait && generating > 0 ? 2 : undefined,
|
|
3364
|
-
|
|
3365
|
-
|
|
3366
|
-
|
|
3463
|
+
// Placeholders the worker refused to start count as failed, with the first error: a worker outage read
|
|
3464
|
+
// as "0 done, 0 failed" (item 62).
|
|
3465
|
+
message: `${wait
|
|
3466
|
+
? `Images: ${count('done')} done, ${count('failed') + failedToStart.length} failed${failedToStart.length ? ` (${failedToStart.length} could not start)` : ''}, ${generating} still generating.${generating > 0 ? ` Check again with: coauthor image status ${projectId} --json` : ''}`
|
|
3467
|
+
: `Started ${started.length} image${started.length === 1 ? '' : 's'}${failedToStart.length ? `; ${failedToStart.length} could not start` : ''}. Check progress with: coauthor image status ${projectId} --json`}${failedToStart.length ? ` First error: ${failedToStart[0].error}` : ''}`,
|
|
3367
3468
|
data: summary,
|
|
3368
3469
|
};
|
|
3369
3470
|
}
|
|
@@ -3614,6 +3715,7 @@ function commandHelp(command) {
|
|
|
3614
3715
|
'',
|
|
3615
3716
|
'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
|
|
3616
3717
|
'--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
|
|
3718
|
+
'Field limits (longer text is rejected with contract_field_too_long, never cut): each must_include, must_avoid, non_negotiables, structure_preferences, evidence_expectations and citation_expectations item up to 600 characters (40 items; 20 for structure_preferences, 30 for evidence/citation); liked/rejected examples 500; topic, angle, target_audience, core_promise and constraints 2,000; additional_editorial_guidance 10,000. Split a long point into several items.',
|
|
3617
3719
|
'--keyword (SEO mode) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
|
|
3618
3720
|
'--seo (SEO mode) sets how the post uses search: optimize (the outline covers what ranks and keeps your angle), my-way (written as planned; the keyword goes only in the SEO title, meta description and slug) or off. Without it, the profile\'s Search optimization setting applies, and "Ask each time" optimizes.',
|
|
3619
3721
|
].join('\n'),
|
|
@@ -3626,6 +3728,7 @@ function commandHelp(command) {
|
|
|
3626
3728
|
'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
|
|
3627
3729
|
'',
|
|
3628
3730
|
'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
|
|
3731
|
+
'If the draft already finished, it reports status draft_generated and starts nothing. With --wait, the top-level status is the final state; data.workflow is the start request\'s reply.',
|
|
3629
3732
|
].join('\n'),
|
|
3630
3733
|
'draft generate': [
|
|
3631
3734
|
'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
|
|
@@ -3890,13 +3993,13 @@ function commandHelp(command) {
|
|
|
3890
3993
|
'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).',
|
|
3891
3994
|
].join('\n'),
|
|
3892
3995
|
'image generate': [
|
|
3893
|
-
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
|
|
3996
|
+
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--wait] [--json]',
|
|
3894
3997
|
'',
|
|
3895
3998
|
'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
|
|
3896
3999
|
'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)',
|
|
3897
4000
|
'and is saved, so later regenerations keep it;',
|
|
3898
4001
|
'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.',
|
|
3899
|
-
'Generation is asynchronous: poll coauthor image status <project-id> --json
|
|
4002
|
+
'Generation is asynchronous: --wait waits for the image (up to 9 minutes; exit code 2 if it is still running), or poll coauthor image status <project-id> --json.',
|
|
3900
4003
|
'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
|
|
3901
4004
|
'--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).',
|
|
3902
4005
|
].join('\n'),
|
|
@@ -3909,9 +4012,9 @@ function commandHelp(command) {
|
|
|
3909
4012
|
'and restyling panels skips it. Article and featured images cannot be replaced here.',
|
|
3910
4013
|
].join('\n'),
|
|
3911
4014
|
'image edit': [
|
|
3912
|
-
'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
|
|
4015
|
+
'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--wait] [--json]',
|
|
3913
4016
|
'',
|
|
3914
|
-
'Edits the current image for a placeholder.
|
|
4017
|
+
'Edits the current image for a placeholder. --wait waits for the edited image (up to 9 minutes; exit code 2 if it is still running); without it, poll coauthor image status <project-id> --json.',
|
|
3915
4018
|
'Prints an operation key: coauthor operation status <key> reports the edited image url or the error; --idempotency-key <key> replays instead of editing twice.',
|
|
3916
4019
|
].join('\n'),
|
|
3917
4020
|
operation: [
|
package/dist/index.js
CHANGED
|
@@ -63,7 +63,7 @@ export function formatCliError(error, baseUrl, argv = [], context = {}) {
|
|
|
63
63
|
...(envelope?.details !== undefined ? { details: envelope.details } : {}),
|
|
64
64
|
...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
|
|
65
65
|
};
|
|
66
|
-
const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey);
|
|
66
|
+
const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey, error.status);
|
|
67
67
|
const entitlement = formatEntitlementResult(error.responseBody);
|
|
68
68
|
if (entitlement)
|
|
69
69
|
return { error: new Error(entitlement.message), result: { ...entitlement, ...errorFields }, exitCode: 2 };
|
|
@@ -123,11 +123,18 @@ function isUsageMessage(message) {
|
|
|
123
123
|
// Live actions (publish, export) are recorded as operations under the
|
|
124
124
|
// Idempotency-Key the CLI sent. Point at it so a caller can check the outcome
|
|
125
125
|
// instead of retrying blind.
|
|
126
|
-
function operationLookupHint(details, idempotencyKey) {
|
|
126
|
+
function operationLookupHint(details, idempotencyKey, httpStatus) {
|
|
127
127
|
if (!idempotencyKey)
|
|
128
128
|
return null;
|
|
129
129
|
if (!details || typeof details !== 'object' || Array.isArray(details) || !('operation' in details))
|
|
130
130
|
return null;
|
|
131
|
+
const operation = details.operation;
|
|
132
|
+
const status = operation && typeof operation === 'object' && !Array.isArray(operation) ? operation.status : undefined;
|
|
133
|
+
// A recorded failure replays as the same failure ("no new job was queued"), so after a server or worker error
|
|
134
|
+
// the useful retry is a fresh request without the key (item 58).
|
|
135
|
+
if (status === 'failed' || (httpStatus !== undefined && httpStatus >= 500)) {
|
|
136
|
+
return `Operation key: ${idempotencyKey} (recorded as failed; replaying this key returns the same failure). Check it with \`coauthor operation status ${idempotencyKey} --json\`; to try again, rerun without --idempotency-key once the service is back.`;
|
|
137
|
+
}
|
|
131
138
|
return `Operation key: ${idempotencyKey} (check it with \`coauthor operation status ${idempotencyKey} --json\`; retry with --idempotency-key ${idempotencyKey} to replay safely).`;
|
|
132
139
|
}
|
|
133
140
|
function formatEntitlementResult(body) {
|
package/package.json
CHANGED
|
@@ -134,6 +134,8 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
|
|
|
134
134
|
- `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
|
|
135
135
|
- `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
|
|
136
136
|
|
|
137
|
+
**Field limits.** Text over a limit is rejected with `contract_field_too_long` (the error names the field and item), never silently cut. List items: `must_include`, `must_avoid`, `non_negotiables`, `structure_preferences`, `evidence_expectations` and `citation_expectations` items up to 600 characters each (40 items; 20 for `structure_preferences`, 30 for evidence and citation); `liked_examples` / `rejected_examples` items 500. Text fields: `topic`, `angle`, `target_audience`, `core_promise`, `constraints` and `confidence_notes` 2,000; `audience_knowledge_assumptions` and `desired_reader_experience` 600; `additional_editorial_guidance` 10,000. Split a long must-include point into several items rather than one paragraph.
|
|
138
|
+
|
|
137
139
|
## Example: practical B2B guide
|
|
138
140
|
|
|
139
141
|
```json
|
|
@@ -13,7 +13,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
13
13
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
14
14
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
15
15
|
- Prices, dates, and text inside the image must match the article.
|
|
16
|
-
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json
|
|
16
|
+
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --wait --json`. `--wait` waits for the edited image (up to 9 minutes; exit code 2 if it is still running) and returns its URL; one image generate takes `--wait` too. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
|
|
17
17
|
- Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
|
|
18
18
|
- `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
|
|
19
19
|
6. Check the SEO metadata of every generated image (`image list` shows `alt_text`, `file_slug`, `description`). After an article image is generated or edited, CoAuthor looks at the finished image and rewrites all three to describe what is actually in it; this lands a few seconds after the image shows `done`. Fields you or the user set with `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json` (or in the editor) are never rewritten, so set them only to fix something wrong. Images from drafts made before this change (mid-November 2026) keep their plan-based text: rewrite those by hand, because that text was written before the image existed.
|
|
@@ -33,7 +33,7 @@ The live URL is where the post is published. `post_details.published_url` holds
|
|
|
33
33
|
|
|
34
34
|
Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
|
|
35
35
|
|
|
36
|
-
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only.
|
|
36
|
+
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence, placement}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. `placement` is `existing_text` when `sentence` is already on that page: link its `anchor` words to the new post, and add nothing. It is `new_sentence` when the page has no fitting sentence and `sentence` is a proposed addition. Older posts have no `placement`; treat those as new sentences. After the post is published, offer the user these edits. It is `null` for other posts.
|
|
37
37
|
|
|
38
38
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
39
39
|
|
|
@@ -227,6 +227,8 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
|
|
|
227
227
|
- `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
|
|
228
228
|
- `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
|
|
229
229
|
|
|
230
|
+
**Field limits.** Text over a limit is rejected with `contract_field_too_long` (the error names the field and item), never silently cut. List items: `must_include`, `must_avoid`, `non_negotiables`, `structure_preferences`, `evidence_expectations` and `citation_expectations` items up to 600 characters each (40 items; 20 for `structure_preferences`, 30 for evidence and citation); `liked_examples` / `rejected_examples` items 500. Text fields: `topic`, `angle`, `target_audience`, `core_promise`, `constraints` and `confidence_notes` 2,000; `audience_knowledge_assumptions` and `desired_reader_experience` 600; `additional_editorial_guidance` 10,000. Split a long must-include point into several items rather than one paragraph.
|
|
231
|
+
|
|
230
232
|
### Example: practical B2B guide
|
|
231
233
|
|
|
232
234
|
```json
|
|
@@ -378,7 +380,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
378
380
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
379
381
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
380
382
|
- Prices, dates, and text inside the image must match the article.
|
|
381
|
-
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json
|
|
383
|
+
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --wait --json`. `--wait` waits for the edited image (up to 9 minutes; exit code 2 if it is still running) and returns its URL; one image generate takes `--wait` too. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
|
|
382
384
|
- Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
|
|
383
385
|
- `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
|
|
384
386
|
6. Check the SEO metadata of every generated image (`image list` shows `alt_text`, `file_slug`, `description`). After an article image is generated or edited, CoAuthor looks at the finished image and rewrites all three to describe what is actually in it; this lands a few seconds after the image shows `done`. Fields you or the user set with `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json` (or in the editor) are never rewritten, so set them only to fix something wrong. Images from drafts made before this change (mid-November 2026) keep their plan-based text: rewrite those by hand, because that text was written before the image existed.
|
|
@@ -479,7 +481,7 @@ The live URL is where the post is published. `post_details.published_url` holds
|
|
|
479
481
|
|
|
480
482
|
Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
|
|
481
483
|
|
|
482
|
-
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only.
|
|
484
|
+
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence, placement}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. `placement` is `existing_text` when `sentence` is already on that page: link its `anchor` words to the new post, and add nothing. It is `new_sentence` when the page has no fitting sentence and `sentence` is a proposed addition. Older posts have no `placement`; treat those as new sentences. After the post is published, offer the user these edits. It is `null` for other posts.
|
|
483
485
|
|
|
484
486
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
485
487
|
|