@clickminded/coauthor-cli 0.0.22 → 0.0.24

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
@@ -1,7 +1,8 @@
1
1
  import { setTimeout as sleep } from 'node:timers/promises';
2
2
  import { spawn } from 'node:child_process';
3
3
  import { createHash } from 'node:crypto';
4
- import { mkdir, readFile, writeFile } from 'node:fs/promises';
4
+ import { existsSync } from 'node:fs';
5
+ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
5
6
  import { homedir } from 'node:os';
6
7
  import { dirname, join, resolve } from 'node:path';
7
8
  import { fileURLToPath } from 'node:url';
@@ -28,6 +29,10 @@ export async function runCommand(input, context) {
28
29
  return runArtifactCommand('research-plan', action, input, context.client);
29
30
  if (scope === 'research')
30
31
  return runResearchCommand(action, input, context);
32
+ if (scope === 'brief')
33
+ return runBriefCommand(action, input, context.client);
34
+ if (scope === 'log')
35
+ return runLogCommand(action, input, context.client);
31
36
  if (scope === 'draft')
32
37
  return runDraftCommand(action, input, context);
33
38
  if (scope === 'workflow')
@@ -411,6 +416,17 @@ async function runArtifactCommand(artifact, action, input, client) {
411
416
  const data = await client.request({ path: basePath });
412
417
  return { ok: true, data };
413
418
  }
419
+ if (action === 'revise' && artifact !== 'contract') {
420
+ const feedback = getString(input.values, 'feedback') ?? input.positionals.slice(1).join(' ');
421
+ if (!feedback.trim())
422
+ throw new Error(`Usage: coauthor ${artifact} revise <projectId> --feedback "..." [--force]`);
423
+ const data = await client.request({
424
+ method: 'POST',
425
+ path: `${basePath}/revise`,
426
+ body: { feedback, ...(getBoolean(input.values, 'force') ? { force: true } : {}) },
427
+ });
428
+ return { ok: true, message: revisionMessage(artifact, data), data };
429
+ }
414
430
  if (artifact === 'contract' && action === 'generate') {
415
431
  throw new Error('contract generate is not supported. The brief comes from `coauthor project create`; refine it with `coauthor chat <project-id> --stage contract --message "..."` or replace it with `coauthor contract save <project-id> --data @contract.json`.');
416
432
  }
@@ -698,98 +714,208 @@ async function runOperationCommand(action, input, client) {
698
714
  }
699
715
  throw new Error('Usage: coauthor operation <list|show|status>');
700
716
  }
701
- const SKILL_NAMES = ['codex', 'claude', 'cursor', 'agents'];
702
- const SKILL_TEMPLATE_PATHS = {
703
- codex: '../skills/codex/SKILL.md',
704
- claude: '../skills/claude/SKILL.md',
705
- cursor: '../skills/cursor/coauthor-cli.mdc',
706
- agents: '../skills/agents/SKILL.md',
717
+ const SKILL_NAMES = ['claude', 'codex', 'agents', 'cursor'];
718
+ const AGENT_LABELS = {
719
+ claude: 'Claude Code',
720
+ codex: 'Codex',
721
+ agents: 'Agents (.agents/skills)',
722
+ cursor: 'Cursor',
707
723
  };
724
+ // Relative to dist/commands.js (and src/commands.ts) inside the package.
725
+ const SKILL_TEMPLATE_DIR = '../skills/coauthor';
726
+ const CURSOR_TEMPLATE = '../skills/cursor/coauthor-cli.mdc';
708
727
  async function runSkillsCommand(action, input) {
728
+ const cwd = resolve(getString(input.values, 'cwd') ?? process.cwd());
729
+ const scope = parseSkillScope(getString(input.values, 'scope'));
709
730
  if (!action || action === 'list') {
710
- const cwd = resolve(getString(input.values, 'cwd') ?? process.cwd());
711
- return {
712
- ok: true,
713
- data: {
714
- skills: SKILL_NAMES.map((skill) => ({
715
- skill,
716
- path: getSkillInstallPath(skill, cwd),
717
- })),
718
- },
719
- };
731
+ const skills = [];
732
+ for (const skill of SKILL_NAMES) {
733
+ const target = skillTarget(skill, skill === 'cursor' ? 'project' : scope ?? 'user', cwd);
734
+ skills.push({ skill, agent: AGENT_LABELS[skill], scope: target.scope, path: target.path, status: await skillStatus(skill, target.path) });
735
+ }
736
+ const legacy = await legacyProjectCopies(cwd);
737
+ return { ok: true, data: { skills, ...(legacy.length > 0 ? { project_copies: legacy } : {}) } };
720
738
  }
721
739
  if (action === 'install') {
722
- const requested = input.positionals[0];
723
- const skills = resolveRequestedSkills(requested);
724
- const cwd = resolve(getString(input.values, 'cwd') ?? process.cwd());
740
+ const skills = resolveRequestedSkills(input.positionals[0]);
725
741
  const force = getBoolean(input.values, 'force');
726
742
  const dryRun = getBoolean(input.values, 'dry-run');
727
743
  const results = [];
728
744
  for (const skill of skills) {
729
- results.push(await installSkill({ skill, cwd, force, dryRun }));
745
+ results.push(await installSkill({ skill, scope: scope ?? 'user', cwd, force, dryRun }));
730
746
  }
747
+ const warnings = (scope ?? 'user') === 'user'
748
+ ? (await legacyProjectCopies(cwd)).map((copy) => `An older project-level copy is at ${copy.path}. Your agent may load both; delete it, or update it with \`coauthor skills install ${copy.skill} --scope project\`.`)
749
+ : [];
731
750
  return {
732
751
  ok: true,
733
- message: dryRun ? 'Skill install dry run complete' : 'Skill install complete',
734
- data: { results },
752
+ message: formatSkillInstallMessage(results, warnings, dryRun),
753
+ data: { results, ...(warnings.length > 0 ? { warnings } : {}) },
735
754
  };
736
755
  }
737
- throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|agents|all]');
756
+ throw new Error('Usage: coauthor skills <list|install> [claude|codex|agents|cursor|all] [--scope user|project]');
738
757
  }
758
+ function parseSkillScope(value) {
759
+ if (value === undefined)
760
+ return null;
761
+ if (value === 'user' || value === 'project')
762
+ return value;
763
+ throw new Error('--scope must be user or project');
764
+ }
765
+ // No target: install for the agents this machine has (Claude Code, Codex),
766
+ // falling back to Claude Code. Cursor and .agents are opt-in.
739
767
  function resolveRequestedSkills(value) {
740
- if (!value || value === 'all')
741
- return [...SKILL_NAMES];
742
- if (isSkillName(value))
768
+ if (!value) {
769
+ const detected = ['claude', 'codex'].filter((skill) => existsSync(join(homedir(), `.${skill}`)));
770
+ return detected.length > 0 ? [...detected] : ['claude'];
771
+ }
772
+ if (value === 'all')
773
+ return ['claude', 'codex', 'agents'];
774
+ if (SKILL_NAMES.includes(value))
743
775
  return [value];
744
- throw new Error('Usage: coauthor skills install <codex|claude|cursor|agents|all>');
776
+ throw new Error('Usage: coauthor skills install [claude|codex|agents|cursor|all] [--scope user|project]');
777
+ }
778
+ function skillTarget(skill, scope, cwd) {
779
+ if (skill === 'cursor')
780
+ return { path: join(cwd, '.cursor', 'rules', 'coauthor-cli.mdc'), scope: 'project' };
781
+ if (skill === 'codex') {
782
+ if (scope === 'project')
783
+ throw new Error('Codex skills install per user. Run `coauthor skills install codex` without --scope project.');
784
+ return { path: join(homedir(), '.codex', 'skills', 'coauthor'), scope: 'user' };
785
+ }
786
+ const base = scope === 'project' ? cwd : homedir();
787
+ return { path: join(base, skill === 'claude' ? '.claude' : '.agents', 'skills', 'coauthor'), scope };
788
+ }
789
+ async function skillTemplates(skill) {
790
+ if (skill === 'cursor')
791
+ return [{ template: CURSOR_TEMPLATE, relative: '' }];
792
+ const root = templatePath(SKILL_TEMPLATE_DIR);
793
+ return (await listFiles(root)).map((file) => ({ template: `${SKILL_TEMPLATE_DIR}/${file}`, relative: file }));
794
+ }
795
+ async function listFiles(dir, prefix = '') {
796
+ const files = [];
797
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
798
+ const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
799
+ if (entry.isDirectory())
800
+ files.push(...await listFiles(join(dir, entry.name), relativePath));
801
+ else
802
+ files.push(relativePath);
803
+ }
804
+ return files.sort();
745
805
  }
746
- function isSkillName(value) {
747
- return SKILL_NAMES.includes(value);
806
+ function templatePath(template) {
807
+ return fileURLToPath(new URL(template, import.meta.url));
748
808
  }
749
809
  async function installSkill(params) {
750
- const targetPath = getSkillInstallPath(params.skill, params.cwd);
751
- const templatePath = getSkillTemplatePath(params.skill);
752
- const template = await readFile(templatePath, 'utf8');
753
- const templateHash = sha256(template);
754
- if (!params.force && await fileExists(targetPath)) {
755
- const current = await readFile(targetPath, 'utf8');
756
- if (sha256(current) === templateHash) {
757
- await recordManagedSkill({
758
- skill: params.skill,
759
- path: targetPath,
760
- template: getSkillTemplateRelativePath(params.skill),
761
- templateHash,
762
- });
810
+ const target = skillTarget(params.skill, params.scope, params.cwd);
811
+ const registry = await readManagedSkillRegistry();
812
+ const files = [];
813
+ for (const { template, relative } of await skillTemplates(params.skill)) {
814
+ const path = relative ? join(target.path, ...relative.split('/')) : target.path;
815
+ const contents = await readFile(templatePath(template), 'utf8');
816
+ const templateHash = sha256(contents);
817
+ const current = await readFile(path, 'utf8').catch((error) => isMissingFileError(error) ? null : Promise.reject(error));
818
+ const currentHash = current === null ? null : sha256(current);
819
+ const managed = registry.skills.find((entry) => entry.path === path);
820
+ let status;
821
+ if (currentHash === templateHash)
822
+ status = 'unchanged';
823
+ else if (current === null)
824
+ status = 'installed';
825
+ // Overwrite a file only when it is the copy we wrote earlier (or --force),
826
+ // so local edits survive upgrades.
827
+ else if (params.force || managed?.templateHash === currentHash)
828
+ status = 'updated';
829
+ else
830
+ status = 'skipped';
831
+ if (params.dryRun) {
832
+ files.push({ path, status: status === 'unchanged' || status === 'skipped' ? status : 'dry_run' });
833
+ continue;
763
834
  }
764
- return { skill: params.skill, status: 'skipped', path: targetPath };
765
- }
766
- if (params.dryRun) {
767
- return { skill: params.skill, status: 'dry_run', path: targetPath };
835
+ if (status === 'installed' || status === 'updated') {
836
+ await mkdir(dirname(path), { recursive: true });
837
+ await writeFile(path, contents, { mode: 0o644 });
838
+ }
839
+ if (status !== 'skipped')
840
+ await recordManagedSkill({ skill: params.skill, path, template, templateHash });
841
+ files.push({ path, status });
768
842
  }
769
- await mkdir(dirname(targetPath), { recursive: true });
770
- await writeFile(targetPath, template, { mode: 0o644 });
771
- await recordManagedSkill({
843
+ const statuses = new Set(files.map((file) => file.status));
844
+ const status = statuses.has('skipped')
845
+ ? 'skipped'
846
+ : statuses.has('dry_run')
847
+ ? 'dry_run'
848
+ : statuses.has('updated')
849
+ ? 'updated'
850
+ : statuses.has('installed')
851
+ ? 'installed'
852
+ : 'unchanged';
853
+ return {
772
854
  skill: params.skill,
773
- path: targetPath,
774
- template: getSkillTemplateRelativePath(params.skill),
775
- templateHash,
776
- });
777
- return { skill: params.skill, status: 'installed', path: targetPath };
778
- }
779
- function getSkillTemplatePath(skill) {
780
- return fileURLToPath(new URL(getSkillTemplateRelativePath(skill), import.meta.url));
781
- }
782
- function getSkillTemplateRelativePath(skill) {
783
- return SKILL_TEMPLATE_PATHS[skill];
855
+ scope: target.scope,
856
+ path: target.path,
857
+ status,
858
+ files,
859
+ ...(status === 'skipped' ? { note: 'Some files have local changes and were left alone. Re-run with --force to overwrite them.' } : {}),
860
+ };
784
861
  }
785
- function getSkillInstallPath(skill, cwd) {
786
- if (skill === 'codex')
787
- return join(homedir(), '.codex', 'skills', 'coauthor', 'SKILL.md');
788
- if (skill === 'claude')
789
- return join(cwd, '.claude', 'skills', 'coauthor', 'SKILL.md');
790
- if (skill === 'agents')
791
- return join(cwd, '.agents', 'skills', 'coauthor', 'SKILL.md');
792
- return join(cwd, '.cursor', 'rules', 'coauthor-cli.mdc');
862
+ async function skillStatus(skill, root) {
863
+ const registry = await readManagedSkillRegistry();
864
+ let present = 0;
865
+ let outdated = false;
866
+ let modified = false;
867
+ for (const { template, relative } of await skillTemplates(skill)) {
868
+ const path = relative ? join(root, ...relative.split('/')) : root;
869
+ const current = await readFile(path, 'utf8').catch(() => null);
870
+ if (current === null) {
871
+ outdated = true;
872
+ continue;
873
+ }
874
+ present += 1;
875
+ const currentHash = sha256(current);
876
+ if (currentHash === sha256(await readFile(templatePath(template), 'utf8')))
877
+ continue;
878
+ if (registry.skills.some((entry) => entry.path === path && entry.templateHash === currentHash))
879
+ outdated = true;
880
+ else
881
+ modified = true;
882
+ }
883
+ if (present === 0)
884
+ return 'missing';
885
+ if (modified)
886
+ return 'modified';
887
+ return outdated ? 'outdated' : 'current';
888
+ }
889
+ // Older CLI versions installed into the current repo. A user-level install
890
+ // next to one of those means the agent may load two different versions.
891
+ async function legacyProjectCopies(cwd) {
892
+ if (resolve(cwd) === resolve(homedir()))
893
+ return [];
894
+ const copies = [];
895
+ for (const skill of ['claude', 'agents']) {
896
+ const path = join(cwd, skill === 'claude' ? '.claude' : '.agents', 'skills', 'coauthor');
897
+ if (existsSync(join(path, 'SKILL.md')))
898
+ copies.push({ skill, path });
899
+ }
900
+ return copies;
901
+ }
902
+ function formatSkillInstallMessage(results, warnings, dryRun) {
903
+ const lines = results.map((result) => {
904
+ const verb = {
905
+ installed: 'installed at',
906
+ updated: 'updated at',
907
+ unchanged: 'already up to date at',
908
+ skipped: 'left unchanged (local edits) at',
909
+ dry_run: 'would be written to',
910
+ }[result.status];
911
+ return `${AGENT_LABELS[result.skill]}: CoAuthor skill ${verb} ${result.path}${result.note ? `\n ${result.note}` : ''}`;
912
+ });
913
+ if (!dryRun && results.some((result) => result.status === 'installed' || result.status === 'updated')) {
914
+ lines.push('', 'Next steps:', '1. Start a new agent session so it loads the skill.', '2. Sign in once with `coauthor auth login` if you have not already.', '3. Ask your agent: "Use CoAuthor to write a blog post about <your topic>."');
915
+ }
916
+ if (warnings.length > 0)
917
+ lines.push('', ...warnings);
918
+ return lines.join('\n');
793
919
  }
794
920
  async function recordManagedSkill(entry) {
795
921
  const registry = await readManagedSkillRegistry();
@@ -819,7 +945,7 @@ async function readManagedSkillRegistry() {
819
945
  version: 1,
820
946
  skills: parsed.skills.filter((skill) => {
821
947
  return Boolean(skill)
822
- && isSkillName(skill.skill)
948
+ && SKILL_NAMES.includes(skill.skill)
823
949
  && typeof skill.path === 'string'
824
950
  && typeof skill.template === 'string'
825
951
  && typeof skill.templateHash === 'string';
@@ -840,17 +966,6 @@ function getManagedSkillRegistryPath() {
840
966
  ? resolve(process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY)
841
967
  : join(homedir(), '.config', 'coauthor', 'managed-skills.json');
842
968
  }
843
- async function fileExists(path) {
844
- try {
845
- await readFile(path);
846
- return true;
847
- }
848
- catch (error) {
849
- return isMissingFileError(error)
850
- ? false
851
- : Promise.reject(error);
852
- }
853
- }
854
969
  function isMissingFileError(error) {
855
970
  return typeof error === 'object'
856
971
  && error !== null
@@ -1187,8 +1302,21 @@ async function buildArtifactApproveBody(artifact, input, client, basePath) {
1187
1302
  function enrichChatResult(data, projectId, stage) {
1188
1303
  if (!data || typeof data !== 'object' || Array.isArray(data))
1189
1304
  return data;
1305
+ // Return the reply and which tools CoAuthor used, not the raw model message
1306
+ // (reasoning signatures and tool payloads are noise for an agent).
1307
+ const parts = extractNestedValue(data, ['responseMessage', 'parts']);
1308
+ const tools = Array.isArray(parts)
1309
+ ? parts.flatMap((part) => {
1310
+ const type = part && typeof part === 'object' && !Array.isArray(part) ? part.type : null;
1311
+ if (typeof type !== 'string' || !type.startsWith('tool-'))
1312
+ return [];
1313
+ const state = part.state;
1314
+ return [{ tool: type.slice('tool-'.length), state: typeof state === 'string' ? state : null }];
1315
+ })
1316
+ : [];
1190
1317
  const result = {
1191
- ...data,
1318
+ text: typeof data.text === 'string' ? data.text : '',
1319
+ tools,
1192
1320
  transcript_command: `coauthor chat show ${projectId} --json`,
1193
1321
  };
1194
1322
  if (stage?.trim().toLowerCase() === 'draft') {
@@ -1197,6 +1325,66 @@ function enrichChatResult(data, projectId, stage) {
1197
1325
  }
1198
1326
  return result;
1199
1327
  }
1328
+ function revisionMessage(artifact, data) {
1329
+ const summary = getResponseString(data, 'summary');
1330
+ const diff = getResponseValue(data, 'diff');
1331
+ const lines = [`${artifact === 'outline' ? 'Outline' : 'Research plan'} revised and saved (not approved).`];
1332
+ if (summary)
1333
+ lines.push(summary);
1334
+ if (diff && typeof diff === 'object' && !Array.isArray(diff)) {
1335
+ const list = (key) => {
1336
+ const value = diff[key];
1337
+ return Array.isArray(value) ? value : [];
1338
+ };
1339
+ const names = (values) => values.map((value) => typeof value === 'string' ? value : JSON.stringify(value)).join('; ');
1340
+ if (list('added').length > 0)
1341
+ lines.push(`Added: ${names(list('added'))}`);
1342
+ if (list('removed').length > 0)
1343
+ lines.push(`Removed: ${names(list('removed'))}`);
1344
+ if (list('renamed').length > 0)
1345
+ lines.push(`Renamed: ${list('renamed').map((entry) => `${entry.from} -> ${entry.to}`).join('; ')}`);
1346
+ if (list('changed').length > 0)
1347
+ lines.push(`Changed: ${list('changed').map((entry) => entry.heading ?? entry.section).join('; ')}`);
1348
+ if (diff.reordered === true)
1349
+ lines.push('Sections were reordered.');
1350
+ }
1351
+ lines.push(`Review it with: coauthor ${artifact} show <project-id> --json, then approve with: coauthor ${artifact} approve <project-id> --json`);
1352
+ return lines.join('\n');
1353
+ }
1354
+ async function runBriefCommand(action, input, client) {
1355
+ const projectId = requireProjectId(input);
1356
+ const path = `projects/${encodeURIComponent(projectId)}/brief`;
1357
+ if (action === 'review') {
1358
+ const data = await client.request({ method: 'POST', path: `${path}/review`, body: {} });
1359
+ return { ok: true, data };
1360
+ }
1361
+ if (action === 'answer') {
1362
+ if (readJsonOptionText(input.values) === undefined) {
1363
+ throw new Error('Usage: coauthor brief answer <projectId> --data @answers.json ({"answers":[{"question":"...","answer":"...","source":"agent|user|assumption"}]})');
1364
+ }
1365
+ const body = parseJsonOption(input.values);
1366
+ if (getBoolean(input.values, 'force'))
1367
+ body.force = true;
1368
+ const data = await client.request({ method: 'POST', path: `${path}/answer`, body });
1369
+ return { ok: true, message: `Brief updated (not approved). Changed: ${getResponseValue(data, 'changed_fields')?.join(', ') || 'nothing'}.`, data };
1370
+ }
1371
+ throw new Error('Usage: coauthor brief <review|answer> <projectId>');
1372
+ }
1373
+ async function runLogCommand(action, input, client) {
1374
+ const projectId = requireProjectId(input);
1375
+ const path = `projects/${encodeURIComponent(projectId)}/log`;
1376
+ if (action === 'show' || !action)
1377
+ return { ok: true, data: await client.request({ path }) };
1378
+ if (action === 'add') {
1379
+ const message = getString(input.values, 'message') ?? input.positionals.slice(1).join(' ');
1380
+ if (!message.trim())
1381
+ throw new Error('Usage: coauthor log add <projectId> --message "..." [--kind decision|assumption|question]');
1382
+ const kind = getString(input.values, 'kind');
1383
+ const data = await client.request({ method: 'POST', path, body: { message, ...(kind ? { kind } : {}) } });
1384
+ return { ok: true, message: 'Logged.', data };
1385
+ }
1386
+ throw new Error('Usage: coauthor log <add|show> <projectId>');
1387
+ }
1200
1388
  function enrichResearchStatus(data) {
1201
1389
  if (!data || typeof data !== 'object' || Array.isArray(data))
1202
1390
  return data;
@@ -1376,8 +1564,10 @@ export function helpResult(command = []) {
1376
1564
  ' workspace show',
1377
1565
  ' chat [show|list]',
1378
1566
  ' contract show|save|approve',
1379
- ' outline show|generate|save|approve',
1380
- ' research-plan show|generate|save|approve',
1567
+ ' outline show|generate|revise|save|approve',
1568
+ ' research-plan show|generate|revise|save|approve',
1569
+ ' brief review|answer',
1570
+ ' log add|show',
1381
1571
  ' research run|status|structured',
1382
1572
  ' draft generate|status|get|save|revise',
1383
1573
  ' draft revision show|apply|discard',
@@ -1388,13 +1578,13 @@ export function helpResult(command = []) {
1388
1578
  ' thread list|show|create|generate|save',
1389
1579
  ' slideshow show|save',
1390
1580
  ' publish thread',
1391
- ' export list|blog|clickminded|wordpress',
1581
+ ' export list|wordpress',
1392
1582
  ' operation list|show|status',
1393
1583
  ' credits',
1394
1584
  ' share <project-id>',
1395
1585
  ' models list|preferences show|preferences set',
1396
1586
  ' skills list|install',
1397
- ' skills install supports codex|claude|cursor|agents|all',
1587
+ ' skills install [claude|codex|agents|cursor|all] [--scope user|project] (default: the agents on this machine, per user)',
1398
1588
  ].join('\n'),
1399
1589
  };
1400
1590
  }
@@ -1450,11 +1640,109 @@ function commandHelp(command) {
1450
1640
  'Fails with 409 if the draft changed since you read it (re-read and reapply), or if the user edited it in the browser in the last 90 seconds (--force overrides).',
1451
1641
  DRAFT_SAVE_SHAPE,
1452
1642
  ].join('\n'),
1643
+ project: [
1644
+ 'Usage: coauthor project <create|list|show> [<project-id>] [--json]',
1645
+ '',
1646
+ 'create: --title, --topic, --audience, --contract <json|@file>. list: --limit. show: one project.',
1647
+ ].join('\n'),
1648
+ brief: [
1649
+ 'Usage: coauthor brief review <project-id> [--json]',
1650
+ ' coauthor brief answer <project-id> --data @answers.json [--force] [--json]',
1651
+ '',
1652
+ 'review: CoAuthor critiques the brief and returns data.verdict, concerns, and questions (each with why, the field it changes, and answerable_by agent|human). Nothing is saved.',
1653
+ 'answer: {"answers":[{"question","answer","source":"agent|user|assumption"}], "apply_suggested_patch"?: {...}}. CoAuthor folds them into the brief and returns changed_fields. The brief is saved, not approved.',
1654
+ ].join('\n'),
1655
+ log: [
1656
+ 'Usage: coauthor log add <project-id> --message "..." [--kind decision|assumption|question] [--json]',
1657
+ ' coauthor log show <project-id> [--json]',
1658
+ '',
1659
+ 'A decision log the user also sees in the project workspace in the web app.',
1660
+ ].join('\n'),
1661
+ contract: [
1662
+ 'Usage: coauthor contract <show|save|approve> <project-id> [--data <json|@file>] [--json]',
1663
+ '',
1664
+ 'save replaces the brief ({"contract":{...}}); approve approves the saved brief. To have CoAuthor review it: coauthor workflow run <project-id> --target contract --briefing-mode strict --json',
1665
+ ].join('\n'),
1666
+ outline: [
1667
+ 'Usage: coauthor outline <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
1668
+ '',
1669
+ 'generate creates an outline without approving it (data.sections). show returns the saved outline (data.artifact).',
1670
+ 'revise --feedback: CoAuthor rewrites the outline from your feedback, saves it (not approved), and returns data.diff.',
1671
+ 'save replaces it with the complete list {"sections":[...]}; omitted sections are removed. approve approves the saved outline.',
1672
+ ].join('\n'),
1673
+ 'research-plan': [
1674
+ 'Usage: coauthor research-plan <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
1675
+ '',
1676
+ 'generate requires an approved outline (data.research_tasks). show returns the saved plan (data.artifact).',
1677
+ 'revise --feedback: CoAuthor rewrites the plan from your feedback (add sources, change depth), saves it (not approved), and returns data.diff.',
1678
+ 'save replaces it with {"research_tasks":[...]}; approve approves the saved plan.',
1679
+ ].join('\n'),
1680
+ research: [
1681
+ 'Usage: coauthor research <run|status|structured> <project-id> [--wait] [--json]',
1682
+ ].join('\n'),
1683
+ workflow: [
1684
+ 'Usage: coauthor workflow <status|run|resume|rewind|approve> <project-id> [--target <contract|outline|research-plan|research|draft>] [--wait] [--json]',
1685
+ '',
1686
+ 'run --target draft --wait runs every remaining step to a finished draft. resume continues research or draft after a timeout or pause.',
1687
+ ].join('\n'),
1688
+ chat: [
1689
+ 'Usage: coauthor chat <project-id> --message "..." [--stage <contract|outline|research-plan|draft>] [--json]',
1690
+ ' coauthor chat show <project-id> [--json]',
1691
+ '',
1692
+ "Talk to CoAuthor about the project. The reply text is in data.text. Re-read the artifact afterwards: CoAuthor's summary can differ from what was saved.",
1693
+ ].join('\n'),
1694
+ image: [
1695
+ 'Usage: coauthor image <list|status|show|generate|edit|metadata> <project-id> [...] [--json]',
1696
+ '',
1697
+ 'list: planned placeholders (use each id). generate/edit: --placeholder-id <id> [--edit-prompt "..."]. status: generation progress.',
1698
+ 'metadata <project-id> <placeholder id>: --alt-text, --description, --file-slug.',
1699
+ ].join('\n'),
1700
+ thread: [
1701
+ 'Usage: coauthor thread <show|generate|save> <project-id> [--data <json|@file>] [--writing-model <id>] [--json]',
1702
+ '',
1703
+ 'generate writes an X thread from the draft. show returns data.thread.posts and connected X accounts (data.social_accounts).',
1704
+ 'save takes {"posts":[...], "destination_url"?, "selected_social_account_id"?}. Publish with: coauthor publish thread <project-id> --yes',
1705
+ ].join('\n'),
1706
+ publish: [
1707
+ 'Usage: coauthor publish thread <project-id> --yes [--json]',
1708
+ '',
1709
+ 'Posts the X thread now. Needs a login with publish permission: coauthor auth login --with-publish',
1710
+ ].join('\n'),
1711
+ export: [
1712
+ 'Usage: coauthor export list <project-id> [--json]',
1713
+ ' coauthor export wordpress <project-id> --yes --slug <slug> [--connection-id <id>] [--json]',
1714
+ '',
1715
+ 'wordpress creates a draft post on the connected WordPress site and returns wordpress_edit_url.',
1716
+ 'Needs a login with publish permission (coauthor auth login --with-publish). With several sites connected, the error lists their ids for --connection-id.',
1717
+ ].join('\n'),
1718
+ share: [
1719
+ 'Usage: coauthor share <project-id> [--json]',
1720
+ '',
1721
+ 'Returns the public read-only link (data.share_url), creating it if needed. Anyone with the link can read the draft.',
1722
+ ].join('\n'),
1723
+ credits: [
1724
+ 'Usage: coauthor credits <project-id> [--json]',
1725
+ '',
1726
+ 'Shows the plan, credits used and remaining this period, and the reset date.',
1727
+ ].join('\n'),
1728
+ 'skills install': [
1729
+ 'Usage: coauthor skills install [claude|codex|agents|cursor|all] [--scope user|project] [--force] [--dry-run] [--json]',
1730
+ '',
1731
+ 'With no target, installs the CoAuthor skill for the agents on this machine (Claude Code, Codex) in your user folder.',
1732
+ '--scope project installs Claude or .agents skills into the current repo instead. Cursor rules are always per project.',
1733
+ 'Files you edited are left alone unless you pass --force.',
1734
+ ].join('\n'),
1735
+ 'skills list': [
1736
+ 'Usage: coauthor skills list [--scope user|project] [--json]',
1737
+ '',
1738
+ 'Shows where the skill is installed for each agent and whether it is current, outdated, modified, or missing.',
1739
+ ].join('\n'),
1453
1740
  'draft revise': [
1454
- 'Usage: coauthor draft revise <project-id> --instruction "..." [--wait] [--apply] [--accept <ids> | --reject <ids>] [--json]',
1741
+ 'Usage: coauthor draft revise <project-id> --instruction "..." [--wait] [--apply] [--json]',
1455
1742
  '',
1456
1743
  "CoAuthor's editor rewrites the draft from your instruction. With --wait the command returns the proposed changes as groups (before/after markdown) for you to review.",
1457
- 'Then: coauthor draft revision apply <project-id> <revision-id> [--accept g1,g2 | --reject g3], or coauthor draft revision discard <project-id> <revision-id>.',
1744
+ 'Then: coauthor draft revision apply <project-id> <revision-id> [--accept <group ids> | --reject <group ids>], or coauthor draft revision discard <project-id> <revision-id>.',
1745
+ 'Group ids are the data.groups[].id values (review_...), comma-separated.',
1458
1746
  '--apply applies every group as soon as the revision is ready. Only one revision can be open on a draft at a time.',
1459
1747
  ].join('\n'),
1460
1748
  'draft revision': [
@@ -1489,5 +1777,5 @@ function commandHelp(command) {
1489
1777
  'Generates a social thread from the saved draft.',
1490
1778
  ].join('\n'),
1491
1779
  };
1492
- return help[key] ?? help[command.slice(0, 2).join(' ')] ?? null;
1780
+ return help[key] ?? help[command.slice(0, 2).join(' ')] ?? help[command[0] ?? ''] ?? null;
1493
1781
  }
package/dist/parser.js CHANGED
@@ -65,6 +65,9 @@ const OPTIONS = {
65
65
  'grounding-mode': { type: 'string' },
66
66
  'image-generation-model': { type: 'string' },
67
67
  instruction: { type: 'string' },
68
+ scope: { type: 'string' },
69
+ feedback: { type: 'string' },
70
+ kind: { type: 'string' },
68
71
  apply: { type: 'boolean', default: false },
69
72
  accept: { type: 'string' },
70
73
  reject: { type: 'string' },
@@ -141,6 +144,10 @@ function commandLength(positionals) {
141
144
  return second === 'show' ? 2 : 1;
142
145
  if (first === 'chat')
143
146
  return second && ['show', 'list'].includes(second) ? 2 : 1;
147
+ if (first === 'brief')
148
+ return second && ['review', 'answer'].includes(second) ? 2 : 1;
149
+ if (first === 'log')
150
+ return second && ['add', 'show'].includes(second) ? 2 : 1;
144
151
  if (first === 'skills')
145
152
  return second && ['list', 'install'].includes(second) ? 2 : 1;
146
153
  if (first === 'models')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.22",
3
+ "version": "0.0.24",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",