@clickminded/coauthor-cli 0.0.77 → 0.0.79

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 CHANGED
@@ -916,6 +916,21 @@ async function runDraftReviseCommand(projectId, input, context) {
916
916
  data: started,
917
917
  };
918
918
  }
919
+ if (getResponseString(revision, 'state') === 'failed') {
920
+ // A failed revision is an error, never a result to review (dogfood, Nov 2026: a "safe limit" failure
921
+ // came back as ok: true with apply/discard next_commands).
922
+ const code = getResponseString(revision, 'error_code') ?? 'revision_failed';
923
+ const reply = getResponseString(revision, 'assistant_message');
924
+ const tooBig = /budget_exhausted$/.test(code);
925
+ return {
926
+ ok: false,
927
+ status: 'failed',
928
+ code,
929
+ exitCode: 1,
930
+ message: `Revision ${revisionId} failed (${code}); the draft was not changed.${reply ? `\nCoAuthor replied: ${reply}` : ''}${tooBig ? '\nSplit the instruction: send one or two fixes per `draft revise`, or edit exact text directly (references/editing-drafts.md).' : ''}`,
931
+ data: revision,
932
+ };
933
+ }
919
934
  if (getResponseValue(revision, 'awaiting_review') !== true) {
920
935
  // No changes usually means CoAuthor asked a question or explained why it
921
936
  // did not edit. Show its reply so the caller can answer or rephrase.
package/dist/output.d.ts CHANGED
@@ -5,6 +5,8 @@ export type CommandResult = {
5
5
  message?: string;
6
6
  data?: JsonValue;
7
7
  exitCode?: number;
8
+ /** Machine-readable failure code for --json (otherwise derived from status). */
9
+ code?: string;
8
10
  settings_url?: string;
9
11
  resume_command?: string;
10
12
  /** The Idempotency-Key sent with the command's live request; look it up with `coauthor operation status <key>`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.77",
3
+ "version": "0.0.79",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -36,7 +36,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
36
36
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
37
37
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
38
38
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
39
- 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims and FAQ answers that defer. Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
39
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
40
40
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
41
41
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
42
42
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -12,6 +12,7 @@ coauthor draft revise <id> --instruction "Cut the intro to two sentences and lea
12
12
 
13
13
  - The result's `data.groups` lists each proposed change with `before_markdown` and `after_markdown`. Review every group against the brief: is it accurate, in voice, and limited to what was asked?
14
14
  - Apply all groups: `coauthor draft revision apply <id> <revision-id> --json`. Keep only some with `--accept <group id>,<group id>`, or all but some with `--reject <group id>`, copying the ids (`review_…`) from `data.groups[].id`. Groups not named in `--accept` are dropped. Drop the whole revision with `coauthor draft revision discard <id> <revision-id> --json`.
15
+ - A failed revision exits 1 with `ok: false`, `status: "failed"` and a `code`; the draft is unchanged. `call_budget_exhausted`, `token_budget_exhausted`, `cost_budget_exhausted` and `time_budget_exhausted` mean the request was too big for one pass: send one or two fixes per `draft revise`, or make exact text fixes (a URL, a checklist's `[ ]` markers) with a direct edit (section 2).
15
16
  - `status: "no_changes"` usually means CoAuthor asked a question instead of guessing. Read `data.assistant_message`, then run `draft revise` again with a clearer instruction.
16
17
  - Name the place precisely ("the paragraph after the 'Write the first line' heading") and give numbers for cuts ("under 60 words"). Vague targets get a clarifying question back, and a vague "tighten" changes little.
17
18
  - One revision can be open on a draft at a time, and an open one blocks the user's saves in the browser. Always apply or discard it. `revision_pending` means one is already open. A revision you leave waiting for review is discarded automatically after 30 minutes (`expires_at` in `draft revision show`), so review it promptly; after that, start a new one.
@@ -98,4 +98,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
98
98
 
99
99
  ## Before retrying anything
100
100
 
101
- Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
101
+ Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
@@ -38,7 +38,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
38
38
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
39
39
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
40
40
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
41
- 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims and FAQ answers that defer. Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
41
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
42
42
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
43
43
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
44
44
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -312,6 +312,7 @@ coauthor draft revise <id> --instruction "Cut the intro to two sentences and lea
312
312
 
313
313
  - The result's `data.groups` lists each proposed change with `before_markdown` and `after_markdown`. Review every group against the brief: is it accurate, in voice, and limited to what was asked?
314
314
  - Apply all groups: `coauthor draft revision apply <id> <revision-id> --json`. Keep only some with `--accept <group id>,<group id>`, or all but some with `--reject <group id>`, copying the ids (`review_…`) from `data.groups[].id`. Groups not named in `--accept` are dropped. Drop the whole revision with `coauthor draft revision discard <id> <revision-id> --json`.
315
+ - A failed revision exits 1 with `ok: false`, `status: "failed"` and a `code`; the draft is unchanged. `call_budget_exhausted`, `token_budget_exhausted`, `cost_budget_exhausted` and `time_budget_exhausted` mean the request was too big for one pass: send one or two fixes per `draft revise`, or make exact text fixes (a URL, a checklist's `[ ]` markers) with a direct edit (section 2).
315
316
  - `status: "no_changes"` usually means CoAuthor asked a question instead of guessing. Read `data.assistant_message`, then run `draft revise` again with a clearer instruction.
316
317
  - Name the place precisely ("the paragraph after the 'Write the first line' heading") and give numbers for cuts ("under 60 words"). Vague targets get a clarifying question back, and a vague "tighten" changes little.
317
318
  - One revision can be open on a draft at a time, and an open one blocks the user's saves in the browser. Always apply or discard it. `revision_pending` means one is already open. A revision you leave waiting for review is discarded automatically after 30 minutes (`expires_at` in `draft revision show`), so review it promptly; after that, start a new one.
@@ -814,4 +815,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
814
815
 
815
816
  ### Before retrying anything
816
817
 
817
- Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
818
+ Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.