@clickminded/coauthor-cli 0.0.44 → 0.0.46
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/dist/commands.js +68 -1
- package/dist/parser.js +2 -0
- package/package.json +1 -1
- package/skills/coauthor/references/brief-and-contract.md +1 -0
- package/skills/coauthor/references/publishing-and-export.md +2 -0
- package/skills/coauthor/references/troubleshooting.md +4 -1
- package/skills/cursor/coauthor-cli.mdc +7 -1
package/README.md
CHANGED
|
@@ -46,6 +46,7 @@ A typical piece:
|
|
|
46
46
|
|
|
47
47
|
```sh
|
|
48
48
|
coauthor profile list --json # pick the writer profile (voice, context, image style)
|
|
49
|
+
coauthor site status --json # SEO mode: the profile website's page index (limited rollout)
|
|
49
50
|
coauthor project create --title "Post title" --contract @brief.json --profile <profile id> --json
|
|
50
51
|
coauthor source add <id> notes.pdf --json # optional reference documents, before research
|
|
51
52
|
coauthor workflow run <id> --target contract --briefing-mode strict --json # CoAuthor questions the brief
|
package/dist/commands.js
CHANGED
|
@@ -37,6 +37,8 @@ export async function runCommand(input, context) {
|
|
|
37
37
|
return runLogCommand(action, input, context.client);
|
|
38
38
|
if (scope === 'profile')
|
|
39
39
|
return runProfileCommand(action, input, context.client);
|
|
40
|
+
if (scope === 'site')
|
|
41
|
+
return runSiteCommand(action, input, context.client);
|
|
40
42
|
if (scope === 'integrations')
|
|
41
43
|
return { ok: true, data: await context.client.request({ path: 'integrations' }) };
|
|
42
44
|
if (scope === 'source')
|
|
@@ -709,6 +711,19 @@ function describeMarketCoverage(data) {
|
|
|
709
711
|
}
|
|
710
712
|
return undefined;
|
|
711
713
|
}
|
|
714
|
+
// SEO mode (7.3): a one-line summary of the checklist that comes with post details.
|
|
715
|
+
function postSeoMessage(data) {
|
|
716
|
+
const seo = getResponseValue(data, 'seo');
|
|
717
|
+
if (!seo || typeof seo.keyword !== 'string')
|
|
718
|
+
return undefined;
|
|
719
|
+
const count = (key) => (typeof seo.counts?.[key] === 'number' ? seo.counts[key] : 0);
|
|
720
|
+
const parts = [`${count('pass')} passed`];
|
|
721
|
+
if (count('warn'))
|
|
722
|
+
parts.push(`${count('warn')} worth a look`);
|
|
723
|
+
if (count('fail'))
|
|
724
|
+
parts.push(`${count('fail')} missing`);
|
|
725
|
+
return `Targeting "${seo.keyword}": SEO checklist ${parts.join(', ')}. Details in data.seo.checks.`;
|
|
726
|
+
}
|
|
712
727
|
async function runPostDetailsCommand(action, input, client) {
|
|
713
728
|
const projectId = requireProjectId(input);
|
|
714
729
|
const path = `projects/${encodeURIComponent(projectId)}/post-details`;
|
|
@@ -717,7 +732,7 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
717
732
|
const details = getResponseValue(data, 'post_details');
|
|
718
733
|
return details === null
|
|
719
734
|
? { ok: true, message: 'This post has no post details. They are generated for drafts created after the feature launched.', data }
|
|
720
|
-
: { ok: true, data };
|
|
735
|
+
: { ok: true, message: postSeoMessage(data), data };
|
|
721
736
|
}
|
|
722
737
|
if (action === 'set') {
|
|
723
738
|
const body = parseJsonOption(input.values);
|
|
@@ -1852,6 +1867,48 @@ async function runProfileCommand(action, input, client) {
|
|
|
1852
1867
|
}
|
|
1853
1868
|
throw new Error('Usage: coauthor profile <list|show>');
|
|
1854
1869
|
}
|
|
1870
|
+
function siteMessage(data, request) {
|
|
1871
|
+
const site = getResponseValue(data, 'site');
|
|
1872
|
+
if (!site)
|
|
1873
|
+
return 'This profile has no website. Add one to the profile in the CoAuthor web app.';
|
|
1874
|
+
const origin = typeof site.origin === 'string' ? site.origin : 'The site';
|
|
1875
|
+
if (request === 'queued')
|
|
1876
|
+
return `Reindexing ${origin}. Check progress with \`coauthor site status\`.`;
|
|
1877
|
+
if (request === 'already_indexing')
|
|
1878
|
+
return `${origin} is already being indexed.`;
|
|
1879
|
+
const pages = typeof site.indexed_pages === 'number' ? site.indexed_pages : 0;
|
|
1880
|
+
const when = typeof site.last_indexed_at === 'string' ? ` (last indexed ${site.last_indexed_at.slice(0, 10)})` : '';
|
|
1881
|
+
if (site.status === 'ready')
|
|
1882
|
+
return `${origin}: ${pages} page${pages === 1 ? '' : 's'} indexed${when}.`;
|
|
1883
|
+
if (site.status === 'indexing')
|
|
1884
|
+
return `${origin} is being indexed now.`;
|
|
1885
|
+
if (site.status === 'blocked')
|
|
1886
|
+
return `${origin} could not be read: no readable sitemap, or the site blocks crawlers${pages ? `. ${pages} page${pages === 1 ? '' : 's'} known from search data` : ''}.`;
|
|
1887
|
+
if (site.status === 'failed')
|
|
1888
|
+
return `The last index of ${origin} failed. Try \`coauthor site reindex\`.`;
|
|
1889
|
+
return `${origin} has not been indexed yet.`;
|
|
1890
|
+
}
|
|
1891
|
+
// SEO mode (limited rollout): the site index behind a profile's website, which
|
|
1892
|
+
// internal links and own-site evidence read. Defaults to the default profile.
|
|
1893
|
+
async function runSiteCommand(action, input, client) {
|
|
1894
|
+
if (action && !['status', 'reindex'].includes(action))
|
|
1895
|
+
throw new Error('Usage: coauthor site <status|reindex> [--profile <profile-id>]');
|
|
1896
|
+
let profileId = getString(input.values, 'profile') ?? input.positionals[0];
|
|
1897
|
+
if (!profileId) {
|
|
1898
|
+
const profiles = await client.request({ path: 'profiles' });
|
|
1899
|
+
const fallback = getResponseValue(profiles, 'default_profile_id');
|
|
1900
|
+
if (typeof fallback !== 'string' || !fallback)
|
|
1901
|
+
throw new Error('No writer profile found. Create one in the CoAuthor web app.');
|
|
1902
|
+
profileId = fallback;
|
|
1903
|
+
}
|
|
1904
|
+
const path = `profiles/${encodeURIComponent(profileId)}/site`;
|
|
1905
|
+
if (action === 'reindex') {
|
|
1906
|
+
const data = await client.request({ method: 'POST', path: `${path}/reindex`, body: {} });
|
|
1907
|
+
return { ok: true, message: siteMessage(data, getResponseValue(data, 'request')), data };
|
|
1908
|
+
}
|
|
1909
|
+
const data = await client.request({ path });
|
|
1910
|
+
return { ok: true, message: siteMessage(data), data };
|
|
1911
|
+
}
|
|
1855
1912
|
const SOURCE_TYPES = { pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', markdown: 'text/markdown' };
|
|
1856
1913
|
// Mirrors the server: base64 over the API caps PDFs at ~3.3 MB; text at 512 KB.
|
|
1857
1914
|
const MAX_SOURCE_PDF_BYTES = 3_300_000;
|
|
@@ -2650,6 +2707,7 @@ export function helpResult(command = []) {
|
|
|
2650
2707
|
' repurpose list|generate|show|save|status|render|download',
|
|
2651
2708
|
' brief review|answer',
|
|
2652
2709
|
' profile list|show',
|
|
2710
|
+
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
2653
2711
|
' source list|add|remove',
|
|
2654
2712
|
' integrations list',
|
|
2655
2713
|
' log add|show',
|
|
@@ -2754,6 +2812,14 @@ function commandHelp(command) {
|
|
|
2754
2812
|
'',
|
|
2755
2813
|
'Writer profiles hold the voice, writer and business context, and visual style. New projects use the default (most recently used) profile unless you pass --profile to project create. A project keeps its profile for good.',
|
|
2756
2814
|
].join('\n'),
|
|
2815
|
+
site: [
|
|
2816
|
+
'Usage: coauthor site status [--profile <profile-id>] [--json]',
|
|
2817
|
+
' coauthor site reindex [--profile <profile-id>] [--json]',
|
|
2818
|
+
'',
|
|
2819
|
+
'SEO mode (limited rollout). CoAuthor reads the website on a writer profile from its sitemap (up to 500 recent pages) to link new posts to it and cite its own pages as evidence.',
|
|
2820
|
+
'status shows the website, its index status (pending, indexing, ready, blocked, failed) and how many pages are indexed. Without --profile it uses the default profile.',
|
|
2821
|
+
'reindex starts a fresh read (free). It answers already_indexing during a crawl and reindex_too_soon within 15 minutes of the last one; no_website when the profile has no website.',
|
|
2822
|
+
].join('\n'),
|
|
2757
2823
|
integrations: [
|
|
2758
2824
|
'Usage: coauthor integrations list [--json]',
|
|
2759
2825
|
'',
|
|
@@ -2887,6 +2953,7 @@ function commandHelp(command) {
|
|
|
2887
2953
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
2888
2954
|
'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
|
|
2889
2955
|
'Posts drafted before post details launched have none (show returns post_details: null; set returns post_details_unavailable).',
|
|
2956
|
+
'SEO posts also return seo: the target keyword, market, SEO research credits and a checklist computed from the current draft (pass, warn, fail or skip per check).',
|
|
2890
2957
|
].join('\n'),
|
|
2891
2958
|
share: [
|
|
2892
2959
|
'Usage: coauthor share <project-id> [--json]',
|
package/dist/parser.js
CHANGED
|
@@ -177,6 +177,8 @@ function commandLength(positionals) {
|
|
|
177
177
|
return second && ['add', 'show'].includes(second) ? 2 : 1;
|
|
178
178
|
if (first === 'profile')
|
|
179
179
|
return second && ['list', 'show'].includes(second) ? 2 : 1;
|
|
180
|
+
if (first === 'site')
|
|
181
|
+
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
180
182
|
if (first === 'integrations')
|
|
181
183
|
return second === 'list' ? 2 : 1;
|
|
182
184
|
if (first === 'source')
|
package/package.json
CHANGED
|
@@ -13,6 +13,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
13
13
|
## Profiles and source documents
|
|
14
14
|
|
|
15
15
|
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
16
|
+
- `coauthor site status [--profile <id>] --json` (SEO mode, limited rollout) shows how much of the profile's website CoAuthor has read (`site.status`: pending, indexing, ready, blocked, failed; `site.indexed_pages`). SEO posts link to those pages and cite them as evidence. `coauthor site reindex` refreshes it after the user publishes new pages; it is free and needs no confirmation.
|
|
16
17
|
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
17
18
|
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
18
19
|
|
|
@@ -26,6 +26,8 @@ coauthor post-details set <id> --seo-title "..." --description "..." --slug "...
|
|
|
26
26
|
|
|
27
27
|
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. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
28
28
|
|
|
29
|
+
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 or intro is worth fixing before publishing: edit the title with `project rename`, or the first paragraph with `draft revise`. `seo` is `null` for other posts.
|
|
30
|
+
|
|
29
31
|
## Share link (public)
|
|
30
32
|
|
|
31
33
|
`coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
|
|
@@ -30,7 +30,10 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
30
30
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
31
31
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
32
32
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
|
-
| `feature_unavailable` | SEO
|
|
33
|
+
| `feature_unavailable` | SEO features (`search-brief`, `project create --keyword`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
|
|
34
|
+
| `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
|
|
35
|
+
| `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
|
|
36
|
+
| `site_index_unavailable` | The site reader couldn't be reached. | Try again later; posts are still written, just without new internal links. |
|
|
34
37
|
| `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
|
|
35
38
|
| `confirmation_required` | `search-brief set-keyword` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
|
|
36
39
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|
|
@@ -92,6 +92,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
92
92
|
### Profiles and source documents
|
|
93
93
|
|
|
94
94
|
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
95
|
+
- `coauthor site status [--profile <id>] --json` (SEO mode, limited rollout) shows how much of the profile's website CoAuthor has read (`site.status`: pending, indexing, ready, blocked, failed; `site.indexed_pages`). SEO posts link to those pages and cite them as evidence. `coauthor site reindex` refreshes it after the user publishes new pages; it is free and needs no confirmation.
|
|
95
96
|
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
96
97
|
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
97
98
|
|
|
@@ -405,6 +406,8 @@ coauthor post-details set <id> --seo-title "..." --description "..." --slug "...
|
|
|
405
406
|
|
|
406
407
|
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. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
407
408
|
|
|
409
|
+
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 or intro is worth fixing before publishing: edit the title with `project rename`, or the first paragraph with `draft revise`. `seo` is `null` for other posts.
|
|
410
|
+
|
|
408
411
|
### Share link (public)
|
|
409
412
|
|
|
410
413
|
`coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
|
|
@@ -547,7 +550,10 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
547
550
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
548
551
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
549
552
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
550
|
-
| `feature_unavailable` | SEO
|
|
553
|
+
| `feature_unavailable` | SEO features (`search-brief`, `project create --keyword`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
|
|
554
|
+
| `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
|
|
555
|
+
| `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
|
|
556
|
+
| `site_index_unavailable` | The site reader couldn't be reached. | Try again later; posts are still written, just without new internal links. |
|
|
551
557
|
| `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
|
|
552
558
|
| `confirmation_required` | `search-brief set-keyword` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
|
|
553
559
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|