@clickminded/coauthor-cli 0.0.8 → 0.0.9

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 CHANGED
@@ -91,6 +91,7 @@ Install one target at a time:
91
91
  coauthor skills install codex
92
92
  coauthor skills install claude
93
93
  coauthor skills install cursor
94
+ coauthor skills install agents
94
95
  ```
95
96
 
96
97
  Default install paths are:
@@ -98,8 +99,11 @@ Default install paths are:
98
99
  - Codex: `~/.codex/skills/coauthor/SKILL.md`
99
100
  - Claude: `./.claude/skills/coauthor/SKILL.md`
100
101
  - Cursor: `./.cursor/rules/coauthor-cli.mdc`
102
+ - Agents: `./.agents/skills/coauthor/SKILL.md`
101
103
 
102
- Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install Claude/Cursor skills into a specific project.
104
+ Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude/Cursor/Agents skills into a specific project.
105
+
106
+ Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future npm package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
103
107
 
104
108
  ## Common Commands
105
109
 
package/dist/commands.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { setTimeout as sleep } from 'node:timers/promises';
2
2
  import { spawn } from 'node:child_process';
3
+ import { createHash } from 'node:crypto';
3
4
  import { mkdir, readFile, writeFile } from 'node:fs/promises';
4
5
  import { homedir } from 'node:os';
5
6
  import { dirname, join, resolve } from 'node:path';
@@ -400,11 +401,12 @@ async function runOperationCommand(action, input, client) {
400
401
  }
401
402
  throw new Error('Usage: coauthor operation <list|show|status>');
402
403
  }
403
- const SKILL_NAMES = ['codex', 'claude', 'cursor'];
404
+ const SKILL_NAMES = ['codex', 'claude', 'cursor', 'agents'];
404
405
  const SKILL_TEMPLATE_PATHS = {
405
406
  codex: '../skills/codex/SKILL.md',
406
407
  claude: '../skills/claude/SKILL.md',
407
408
  cursor: '../skills/cursor/coauthor-cli.mdc',
409
+ agents: '../skills/agents/SKILL.md',
408
410
  };
409
411
  async function runSkillsCommand(action, input) {
410
412
  if (!action || action === 'list') {
@@ -435,41 +437,112 @@ async function runSkillsCommand(action, input) {
435
437
  data: { results },
436
438
  };
437
439
  }
438
- throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|all]');
440
+ throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|agents|all]');
439
441
  }
440
442
  function resolveRequestedSkills(value) {
441
443
  if (!value || value === 'all')
442
444
  return [...SKILL_NAMES];
443
445
  if (isSkillName(value))
444
446
  return [value];
445
- throw new Error('Usage: coauthor skills install <codex|claude|cursor|all>');
447
+ throw new Error('Usage: coauthor skills install <codex|claude|cursor|agents|all>');
446
448
  }
447
449
  function isSkillName(value) {
448
450
  return SKILL_NAMES.includes(value);
449
451
  }
450
452
  async function installSkill(params) {
451
453
  const targetPath = getSkillInstallPath(params.skill, params.cwd);
454
+ const templatePath = getSkillTemplatePath(params.skill);
455
+ const template = await readFile(templatePath, 'utf8');
456
+ const templateHash = sha256(template);
452
457
  if (!params.force && await fileExists(targetPath)) {
458
+ const current = await readFile(targetPath, 'utf8');
459
+ if (sha256(current) === templateHash) {
460
+ await recordManagedSkill({
461
+ skill: params.skill,
462
+ path: targetPath,
463
+ template: getSkillTemplateRelativePath(params.skill),
464
+ templateHash,
465
+ });
466
+ }
453
467
  return { skill: params.skill, status: 'skipped', path: targetPath };
454
468
  }
455
469
  if (params.dryRun) {
456
470
  return { skill: params.skill, status: 'dry_run', path: targetPath };
457
471
  }
458
- const template = await readFile(getSkillTemplatePath(params.skill), 'utf8');
459
472
  await mkdir(dirname(targetPath), { recursive: true });
460
473
  await writeFile(targetPath, template, { mode: 0o644 });
474
+ await recordManagedSkill({
475
+ skill: params.skill,
476
+ path: targetPath,
477
+ template: getSkillTemplateRelativePath(params.skill),
478
+ templateHash,
479
+ });
461
480
  return { skill: params.skill, status: 'installed', path: targetPath };
462
481
  }
463
482
  function getSkillTemplatePath(skill) {
464
- return fileURLToPath(new URL(SKILL_TEMPLATE_PATHS[skill], import.meta.url));
483
+ return fileURLToPath(new URL(getSkillTemplateRelativePath(skill), import.meta.url));
484
+ }
485
+ function getSkillTemplateRelativePath(skill) {
486
+ return SKILL_TEMPLATE_PATHS[skill];
465
487
  }
466
488
  function getSkillInstallPath(skill, cwd) {
467
489
  if (skill === 'codex')
468
490
  return join(homedir(), '.codex', 'skills', 'coauthor', 'SKILL.md');
469
491
  if (skill === 'claude')
470
492
  return join(cwd, '.claude', 'skills', 'coauthor', 'SKILL.md');
493
+ if (skill === 'agents')
494
+ return join(cwd, '.agents', 'skills', 'coauthor', 'SKILL.md');
471
495
  return join(cwd, '.cursor', 'rules', 'coauthor-cli.mdc');
472
496
  }
497
+ async function recordManagedSkill(entry) {
498
+ const registry = await readManagedSkillRegistry();
499
+ const existing = registry.skills.findIndex((skill) => skill.path === entry.path);
500
+ const next = {
501
+ ...entry,
502
+ updatedAt: new Date().toISOString(),
503
+ };
504
+ if (existing >= 0) {
505
+ registry.skills[existing] = next;
506
+ }
507
+ else {
508
+ registry.skills.push(next);
509
+ }
510
+ const registryPath = getManagedSkillRegistryPath();
511
+ await mkdir(dirname(registryPath), { recursive: true });
512
+ await writeFile(registryPath, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o644 });
513
+ }
514
+ async function readManagedSkillRegistry() {
515
+ try {
516
+ const raw = await readFile(getManagedSkillRegistryPath(), 'utf8');
517
+ const parsed = JSON.parse(raw);
518
+ if (parsed.version !== 1 || !Array.isArray(parsed.skills)) {
519
+ return { version: 1, skills: [] };
520
+ }
521
+ return {
522
+ version: 1,
523
+ skills: parsed.skills.filter((skill) => {
524
+ return Boolean(skill)
525
+ && isSkillName(skill.skill)
526
+ && typeof skill.path === 'string'
527
+ && typeof skill.template === 'string'
528
+ && typeof skill.templateHash === 'string';
529
+ }),
530
+ };
531
+ }
532
+ catch (error) {
533
+ if (isMissingFileError(error))
534
+ return { version: 1, skills: [] };
535
+ throw error;
536
+ }
537
+ }
538
+ function sha256(value) {
539
+ return createHash('sha256').update(value).digest('hex');
540
+ }
541
+ function getManagedSkillRegistryPath() {
542
+ return process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY
543
+ ? resolve(process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY)
544
+ : join(homedir(), '.config', 'coauthor', 'managed-skills.json');
545
+ }
473
546
  async function fileExists(path) {
474
547
  try {
475
548
  await readFile(path);
@@ -848,6 +921,7 @@ export function helpResult() {
848
921
  ' operation list|show|status',
849
922
  ' credits',
850
923
  ' skills list|install',
924
+ ' skills install supports codex|claude|cursor|agents|all',
851
925
  ].join('\n'),
852
926
  };
853
927
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.8",
3
+ "version": "0.0.9",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -19,11 +19,13 @@
19
19
  },
20
20
  "files": [
21
21
  "dist",
22
+ "scripts",
22
23
  "skills",
23
24
  "README.md"
24
25
  ],
25
26
  "scripts": {
26
27
  "build": "tsc",
28
+ "postinstall": "node scripts/postinstall.mjs",
27
29
  "test": "node --import tsx --test test/*.test.ts",
28
30
  "typecheck": "tsc --noEmit"
29
31
  },
@@ -0,0 +1,96 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { mkdir, readFile, writeFile } from 'node:fs/promises'
3
+ import { dirname, join } from 'node:path'
4
+ import { fileURLToPath } from 'node:url'
5
+ import { homedir } from 'node:os'
6
+
7
+ const packageRoot = fileURLToPath(new URL('..', import.meta.url))
8
+ const registryPath = join(homedir(), '.config', 'coauthor', 'managed-skills.json')
9
+
10
+ async function main() {
11
+ const registry = await readRegistry()
12
+ if (registry.skills.length === 0) return
13
+
14
+ let changed = false
15
+ const nextSkills = []
16
+ for (const skill of registry.skills) {
17
+ const templatePath = resolveTemplatePath(skill.template)
18
+ if (!templatePath) {
19
+ nextSkills.push(skill)
20
+ continue
21
+ }
22
+
23
+ const template = await readFile(templatePath, 'utf8').catch(() => null)
24
+ if (template === null) {
25
+ nextSkills.push(skill)
26
+ continue
27
+ }
28
+
29
+ const current = await readFile(skill.path, 'utf8').catch((error) => {
30
+ return error && error.code === 'ENOENT' ? '' : null
31
+ })
32
+ if (current === null) {
33
+ nextSkills.push(skill)
34
+ continue
35
+ }
36
+
37
+ const currentHash = sha256(current)
38
+ const nextHash = sha256(template)
39
+ const safeToUpdate = current === '' || currentHash === skill.templateHash || currentHash === nextHash
40
+ if (!safeToUpdate) {
41
+ nextSkills.push(skill)
42
+ continue
43
+ }
44
+
45
+ if (currentHash !== nextHash) {
46
+ await mkdir(dirname(skill.path), { recursive: true })
47
+ await writeFile(skill.path, template, { mode: 0o644 })
48
+ }
49
+
50
+ nextSkills.push({
51
+ ...skill,
52
+ templateHash: nextHash,
53
+ updatedAt: new Date().toISOString(),
54
+ })
55
+ changed = true
56
+ }
57
+
58
+ if (changed) {
59
+ await mkdir(dirname(registryPath), { recursive: true })
60
+ await writeFile(registryPath, `${JSON.stringify({ version: 1, skills: nextSkills }, null, 2)}\n`, { mode: 0o644 })
61
+ }
62
+ }
63
+
64
+ async function readRegistry() {
65
+ try {
66
+ const raw = await readFile(registryPath, 'utf8')
67
+ const parsed = JSON.parse(raw)
68
+ if (parsed?.version !== 1 || !Array.isArray(parsed.skills)) return { version: 1, skills: [] }
69
+ return {
70
+ version: 1,
71
+ skills: parsed.skills.filter((skill) => {
72
+ return skill
73
+ && typeof skill.skill === 'string'
74
+ && typeof skill.path === 'string'
75
+ && typeof skill.template === 'string'
76
+ && typeof skill.templateHash === 'string'
77
+ }),
78
+ }
79
+ } catch (error) {
80
+ if (error && error.code === 'ENOENT') return { version: 1, skills: [] }
81
+ throw error
82
+ }
83
+ }
84
+
85
+ function resolveTemplatePath(template) {
86
+ if (!template.startsWith('../skills/')) return null
87
+ return join(packageRoot, template.replace(/^\.\.\//, ''))
88
+ }
89
+
90
+ function sha256(value) {
91
+ return createHash('sha256').update(value).digest('hex')
92
+ }
93
+
94
+ main().catch((error) => {
95
+ console.warn(`[coauthor] skipped managed skill auto-update: ${error instanceof Error ? error.message : String(error)}`)
96
+ })
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: coauthor
3
+ description: Use the CoAuthor Agent CLI for project/workflow operations instead of browser routes, curl, or direct database access. Applies when inspecting or advancing CoAuthor projects, operations, exports, publishing, tokens, or workflow status.
4
+ ---
5
+
6
+ This skill guides agent use of the CoAuthor CLI.
7
+
8
+ ## CLI First
9
+
10
+ - Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
11
+ - Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
12
+ - Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
+ - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
14
+ - Use `--json` for machine-readable output and parse fields from that output.
15
+ - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
16
+ - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
+ - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
+ - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
20
+ - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
21
+ - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
+ - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
23
+
24
+ ## Safety
25
+
26
+ - Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
27
+ - Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
28
+ - Pass tokens through environment variables or secret-backed CLI options only; do not paste them into prompts, logs, or shell history.
29
+ - Treat publish/export operations as live side effects.
30
+ - Require explicit user intent before live publish/export.
31
+ - Include `--yes` only when the user has clearly approved the live publish/export action.
32
+
33
+ ## Workflow
34
+
35
+ 1. Identify the project, operation, or export target.
36
+ 2. Run the relevant `coauthor` command with `--json`.
37
+ 3. Add `--wait` when starting or advancing asynchronous work.
38
+ 4. If anything is uncertain, query workflow/research/draft status and report the current state.
39
+ 5. For live publish/export, confirm explicit user intent, then run with `--yes`.
40
+
41
+ ## Chat Transcript
42
+
43
+ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
44
+
45
+ When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
46
+
47
+ ## Draft Export
48
+
49
+ Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
50
+
51
+ Use `coauthor draft get <project-id> --format html --json` when the user needs HTML with resolved image tags.
52
+
53
+ Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
54
+
55
+ Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
15
15
  - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
+ - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
18
20
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
19
21
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
+ - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
20
23
 
21
24
  ## Safety
22
25
 
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
32
35
  1. Identify the project, operation, or export target.
33
36
  2. Run the relevant `coauthor` command with `--json`.
34
37
  3. Add `--wait` when starting or advancing asynchronous work.
35
- 4. If anything is uncertain, query operation status and report the current state.
38
+ 4. If anything is uncertain, query workflow/research/draft status and report the current state.
36
39
  5. For live publish/export, confirm explicit user intent, then run with `--yes`.
37
40
 
41
+ ## Chat Transcript
42
+
43
+ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
44
+
45
+ When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
46
+
38
47
  ## Draft Export
39
48
 
40
49
  Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
15
15
  - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
+ - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
18
20
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
19
21
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
+ - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
20
23
 
21
24
  ## Safety
22
25
 
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
32
35
  1. Identify the project, operation, or export target.
33
36
  2. Run the relevant `coauthor` command with `--json`.
34
37
  3. Add `--wait` when starting or advancing asynchronous work.
35
- 4. If anything is uncertain, query operation status and report the current state.
38
+ 4. If anything is uncertain, query workflow/research/draft status and report the current state.
36
39
  5. For live publish/export, confirm explicit user intent, then run with `--yes`.
37
40
 
41
+ ## Chat Transcript
42
+
43
+ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
44
+
45
+ When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
46
+
38
47
  ## Draft Export
39
48
 
40
49
  Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
@@ -12,8 +12,11 @@ alwaysApply: true
12
12
  - Use `--wait` when starting asynchronous work and the user expects a completed result.
13
13
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
14
14
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
15
+ - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
16
+ - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
15
17
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
16
18
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
19
+ - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
17
20
  - Never print tokens, service-role keys, cookies, or authorization headers.
18
21
  - Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
19
22
  - Pass tokens through environment variables or secret-backed CLI options only.
@@ -23,6 +26,8 @@ alwaysApply: true
23
26
 
24
27
  ## Draft Export
25
28
 
29
+ - Use `coauthor chat show <project-id> --json` to retrieve workspace chat transcripts after long chat responses.
30
+ - Treat `coauthor chat <project-id> --stage draft --json` as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable.
26
31
  - Use `coauthor draft get <project-id> --format markdown --json` for finished draft Markdown. Generated images resolve into Markdown image URLs when available.
27
32
  - Use `coauthor draft get <project-id> --format html --json` for HTML with resolved image tags.
28
33
  - Use `coauthor draft get <project-id> --format text --json` for plain text with image URL references.