@clickminded/coauthor-cli 0.0.76 → 0.0.77

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.
@@ -12,6 +12,11 @@ export type CommandContext = {
12
12
  export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
13
13
  export declare function describeImageOperation(operation: JsonValue | undefined): string | null;
14
14
  export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?: (line: string) => void): void;
15
+ /**
16
+ * The draft check (brief compliance and consistency) of the finished draft. A draft with open items is
17
+ * reported as completed *with items to review*, never as plainly done.
18
+ */
19
+ export declare function draftCompletionMessage(base: string, status: JsonValue): string;
15
20
  /**
16
21
  * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
17
22
  * list (at most 4 endings, at most one custom).
package/dist/commands.js CHANGED
@@ -637,7 +637,11 @@ async function runDraftCommand(action, input, context) {
637
637
  return { ok: true, data };
638
638
  }
639
639
  if (action === 'status') {
640
- return { ok: true, data: await client.request({ path: `${basePath}/status` }) };
640
+ const data = await client.request({ path: `${basePath}/status` });
641
+ const record = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
642
+ const done = record.phase === 'complete' || record.project_state === 'draft_generated' || record.project_state === 'editing';
643
+ const message = done ? draftCompletionMessage('Draft ready', data) : undefined;
644
+ return { ok: true, ...(message && message !== 'Draft ready' ? { message } : {}), data };
641
645
  }
642
646
  if (action === 'get') {
643
647
  const format = getString(input.values, 'format');
@@ -1673,6 +1677,23 @@ async function waitForResearch(client, projectId, initialData, baseUrl) {
1673
1677
  }
1674
1678
  return waitTimedOutResult(projectId, 'research', initialData, latest, null);
1675
1679
  }
1680
+ /**
1681
+ * The draft check (brief compliance and consistency) of the finished draft. A draft with open items is
1682
+ * reported as completed *with items to review*, never as plainly done.
1683
+ */
1684
+ export function draftCompletionMessage(base, status) {
1685
+ const check = status && typeof status === 'object' && !Array.isArray(status) ? status.quality_check : null;
1686
+ if (!check || typeof check !== 'object' || Array.isArray(check))
1687
+ return base;
1688
+ const record = check;
1689
+ const open = Array.isArray(record.unresolved) ? record.unresolved.length : 0;
1690
+ if (record.status === 'needs_review' && open > 0) {
1691
+ return `${base}, with ${open} draft check ${open === 1 ? 'item' : 'items'} to review (quality_check.unresolved): the draft may miss part of the brief.`;
1692
+ }
1693
+ if (record.status === 'failed')
1694
+ return `${base}; the draft check could not run, so check it against the brief yourself.`;
1695
+ return base;
1696
+ }
1676
1697
  async function waitForDraft(client, projectId, initialData, baseUrl) {
1677
1698
  const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
1678
1699
  const pollMs = waitPollMs();
@@ -1683,7 +1704,7 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
1683
1704
  const state = getResponseString(latest, 'project_state');
1684
1705
  const phase = getResponseString(latest, 'phase');
1685
1706
  if (state === 'draft_generated' || state === 'editing' || phase === 'complete') {
1686
- return { ok: true, message: 'Draft completed', data: latest };
1707
+ return { ok: true, message: draftCompletionMessage('Draft completed', latest), data: latest };
1687
1708
  }
1688
1709
  if (phase === 'paused_requires_key')
1689
1710
  return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
@@ -1710,7 +1731,7 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
1710
1731
  if (draftState === 'draft_generated' || draftState === 'editing' || draftPhase === 'complete') {
1711
1732
  return {
1712
1733
  ok: true,
1713
- message: 'Workflow target draft completed',
1734
+ message: draftCompletionMessage('Workflow target draft completed', latestDraft),
1714
1735
  data: {
1715
1736
  workflow: initialData,
1716
1737
  research_status: latestResearch,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.76",
3
+ "version": "0.0.77",
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 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 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.
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`).
@@ -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`. 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`) 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 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 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.
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`).
@@ -814,4 +814,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
814
814
 
815
815
  ### Before retrying anything
816
816
 
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`. Starting a step twice can spend credits twice.
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.