codebook-strategy 1.0.2 → 1.0.4

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
@@ -2,6 +2,9 @@
2
2
 
3
3
  **Your AI coding assistant re-reads your whole codebase every session.** `codebook-strategy` builds a small set of notes it reads instead — so it gets the *right* context, not *all* the context.
4
4
 
5
+ > ⚠️ **Run it, don't install it.** This is a one-shot scaffolding CLI, **not** a dependency.
6
+ > Use `npx` (or `pnpm dlx`) — do **not** run `npm install codebook-strategy`.
7
+
5
8
  ```bash
6
9
  npx codebook-strategy init
7
10
  ```
@@ -59,17 +62,19 @@ It starts as structure and becomes knowledge. `init` lays down empty templates.
59
62
  ### `init`
60
63
 
61
64
  ```bash
62
- npx codebook-strategy init [--force]
65
+ npx codebook-strategy init [--tool <list>] [--force]
63
66
  ```
64
67
 
65
68
  - Confirms you're in a project (looks for `package.json`, `.git`, or `src/`).
66
- - Detects your LLM tooling and injects the strategy into the right config file:
67
- - `CLAUDE.md` / `.claude/` → **Claude Code**
68
- - `.cursorrules` / `.cursor/` → **Cursor**
69
- - `AGENTS.md` → **Amp / Warp**
70
- - none detected → creates all three
69
+ - **Injects the strategy into every supported agent by default** — `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (Amp / Warp / Codex). That way it doesn't matter which agent — or how many — your team uses; whichever one someone opens, it finds the strategy. The agents it detects in use are marked in the output.
70
+ - Narrow it with `--tool` if you only want specific agents:
71
+ ```bash
72
+ npx codebook-strategy init --tool claude
73
+ npx codebook-strategy init --tool claude,cursor
74
+ npx codebook-strategy init --tool all # explicit default
75
+ ```
71
76
  - Scaffolds `book/` with `PREFACE.md`, `INDEX.md`, `CONNECTIONS.md`, and `chapters/`.
72
- - Existing config files are **appended to**, never overwritten. Existing book files are left untouched unless you pass `--force`.
77
+ - Existing config files are **appended to**, never overwritten (and never double-injected). Existing book files are left untouched unless you pass `--force`.
73
78
 
74
79
  ### `status`
75
80
 
package/bin/cli.js CHANGED
@@ -18,7 +18,9 @@ ${bold('Commands')}
18
18
  validate Check the book for index/chapter/connection mismatches
19
19
 
20
20
  ${bold('Options for init')}
21
- --force Overwrite an existing book/ directory
21
+ --tool <list> Which agents to set up: claude, cursor, agents, or all.
22
+ Comma-separated. Default: all (covers every agent).
23
+ --force Overwrite an existing book/ directory
22
24
 
23
25
  ${bold('After init')}
24
26
  Tell your LLM: ${dim('"Implement the book strategy"')}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codebook-strategy",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
4
4
  "description": "Your AI coding assistant re-reads your whole codebase every session. codebook-strategy builds a small set of notes it reads instead.",
5
5
  "bin": {
6
6
  "codebook-strategy": "bin/cli.js"
@@ -3,7 +3,12 @@
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
5
 
6
- const { isProject, detectTargets } = require('../utils/detect-environment');
6
+ const {
7
+ isProject,
8
+ detectPresent,
9
+ resolveTargets,
10
+ ALL_KEYS,
11
+ } = require('../utils/detect-environment');
7
12
  const {
8
13
  exists,
9
14
  ensureDir,
@@ -25,8 +30,19 @@ function read(templatePath) {
25
30
  return fs.readFileSync(path.join(TEMPLATES, templatePath), 'utf8');
26
31
  }
27
32
 
33
+ // Read the value of a flag, supporting both `--flag value` and `--flag=value`.
34
+ function getFlagValue(args, name) {
35
+ for (let i = 0; i < args.length; i++) {
36
+ const a = args[i];
37
+ if (a === name) return args[i + 1];
38
+ if (a.startsWith(name + '=')) return a.slice(name.length + 1);
39
+ }
40
+ return undefined;
41
+ }
42
+
28
43
  function init(args) {
29
44
  const force = args.includes('--force');
45
+ const toolArg = getFlagValue(args, '--tool');
30
46
  const cwd = process.cwd();
31
47
 
32
48
  if (!isProject(cwd)) {
@@ -39,6 +55,19 @@ function init(args) {
39
55
  return 1;
40
56
  }
41
57
 
58
+ // Resolve which agents to write to. Default: every supported agent, so it
59
+ // never matters which one (or how many) the developer actually uses.
60
+ const { targets, invalid } = resolveTargets(toolArg);
61
+ if (invalid.length > 0) {
62
+ process.stderr.write(
63
+ red(`Unknown --tool value(s): ${invalid.join(', ')}`) +
64
+ '\n' +
65
+ dim(`Valid tools: ${ALL_KEYS.join(', ')}, or all.`) +
66
+ '\n'
67
+ );
68
+ return 1;
69
+ }
70
+
42
71
  const bookDir = path.join(cwd, 'book');
43
72
 
44
73
  // Handle an existing book/ directory.
@@ -77,14 +106,21 @@ function init(args) {
77
106
  bookResults.push({ name: 'book/chapters/', result: keepResult });
78
107
 
79
108
  // --- Inject strategy into config files --------------------------------
80
- const { detected, targets } = detectTargets(cwd);
109
+ // Which agents actually show signs of use here (for reporting only).
110
+ const present = detectPresent(cwd);
81
111
 
82
112
  const configResults = [];
83
113
  for (const target of targets) {
84
114
  const section = read(target.template);
85
115
  const filePath = path.join(cwd, target.file);
86
116
  const result = appendSection(filePath, section, STRATEGY_MARKER);
87
- configResults.push({ tool: target.tool, file: target.file, result });
117
+ configResults.push({
118
+ key: target.key,
119
+ tool: target.tool,
120
+ file: target.file,
121
+ result,
122
+ detected: present.includes(target.key),
123
+ });
88
124
  }
89
125
 
90
126
  // --- Report -----------------------------------------------------------
@@ -96,18 +132,19 @@ function init(args) {
96
132
  }
97
133
 
98
134
  process.stdout.write('\n' + bold('Config files') + '\n');
99
- if (detected) {
135
+ if (toolArg) {
100
136
  process.stdout.write(
101
- dim(' Detected existing LLM tooling; injected into:') + '\n'
137
+ dim(' Injecting strategy into the tool(s) you selected:') + '\n'
102
138
  );
103
139
  } else {
104
140
  process.stdout.write(
105
- dim(' No LLM tooling detected; created all three config files:') + '\n'
141
+ dim(' Covering every supported agent (pass --tool to narrow):') + '\n'
106
142
  );
107
143
  }
108
- for (const { tool, file, result } of configResults) {
144
+ for (const { tool, file, result, detected } of configResults) {
145
+ const mark = detected ? cyan(' ← in use here') : '';
109
146
  process.stdout.write(
110
- ' ' + formatResult(result) + ' ' + file + dim(` (${tool})`) + '\n'
147
+ ' ' + formatResult(result) + ' ' + file + dim(` (${tool})`) + mark + '\n'
111
148
  );
112
149
  }
113
150
 
@@ -12,38 +12,97 @@ function isProject(cwd) {
12
12
  );
13
13
  }
14
14
 
15
- // Detect which LLM tool config files/directories are present.
16
- // Returns a list of target descriptors. Each descriptor names the config file
17
- // the strategy should be injected into and the template it comes from.
15
+ // The coding agents we support. Each entry names the config file the strategy
16
+ // is injected into, the template it comes from, and the filesystem "signals"
17
+ // that hint the agent is in use here.
18
+ const TOOLS = {
19
+ claude: {
20
+ key: 'claude',
21
+ tool: 'Claude Code',
22
+ file: 'CLAUDE.md',
23
+ template: 'CLAUDE.md',
24
+ signals: ['CLAUDE.md', '.claude'],
25
+ },
26
+ cursor: {
27
+ key: 'cursor',
28
+ tool: 'Cursor',
29
+ file: '.cursorrules',
30
+ template: 'cursorrules',
31
+ signals: ['.cursorrules', '.cursor'],
32
+ },
33
+ agents: {
34
+ key: 'agents',
35
+ tool: 'Amp / Warp / Codex (AGENTS.md)',
36
+ file: 'AGENTS.md',
37
+ template: 'AGENTS.md',
38
+ signals: ['AGENTS.md'],
39
+ },
40
+ };
41
+
42
+ const ALL_KEYS = ['claude', 'cursor', 'agents'];
43
+
44
+ // Accept a few friendly spellings for the --tool flag.
45
+ const ALIASES = {
46
+ claude: 'claude',
47
+ 'claude-code': 'claude',
48
+ claudecode: 'claude',
49
+ cc: 'claude',
50
+ cursor: 'cursor',
51
+ agents: 'agents',
52
+ agent: 'agents',
53
+ 'agents.md': 'agents',
54
+ amp: 'agents',
55
+ warp: 'agents',
56
+ codex: 'agents',
57
+ };
58
+
59
+ // Which agents show signs of being used in this project. Informational only —
60
+ // by default we still write to every agent so nothing is missed.
61
+ function detectPresent(cwd) {
62
+ return ALL_KEYS.filter((key) =>
63
+ TOOLS[key].signals.some((s) => exists(path.join(cwd, s)))
64
+ );
65
+ }
66
+
67
+ // Resolve which config files to write to.
68
+ //
69
+ // toolArg undefined / null -> all agents (the safe default)
70
+ // toolArg 'all' -> all agents
71
+ // toolArg 'claude,cursor' -> just those (comma- or space-separated, aliases ok)
18
72
  //
19
- // If nothing is detected, all three targets are returned so the book works with
20
- // whichever tool the developer uses.
21
- function detectTargets(cwd) {
22
- const claude =
23
- exists(path.join(cwd, 'CLAUDE.md')) || exists(path.join(cwd, '.claude'));
24
- const cursor =
25
- exists(path.join(cwd, '.cursorrules')) || exists(path.join(cwd, '.cursor'));
26
- const agents = exists(path.join(cwd, 'AGENTS.md'));
27
-
28
- const all = {
29
- claude: { tool: 'Claude Code', file: 'CLAUDE.md', template: 'CLAUDE.md' },
30
- cursor: { tool: 'Cursor', file: '.cursorrules', template: 'cursorrules' },
31
- agents: { tool: 'Amp/Warp', file: 'AGENTS.md', template: 'AGENTS.md' },
32
- };
33
-
34
- const detected = [];
35
- if (claude) detected.push(all.claude);
36
- if (cursor) detected.push(all.cursor);
37
- if (agents) detected.push(all.agents);
38
-
39
- if (detected.length > 0) {
40
- return { detected: true, targets: detected };
73
+ // Returns { targets: [toolDescriptor], invalid: [badToken] }.
74
+ function resolveTargets(toolArg) {
75
+ if (!toolArg || String(toolArg).trim().toLowerCase() === 'all') {
76
+ return { targets: ALL_KEYS.map((k) => TOOLS[k]), invalid: [] };
77
+ }
78
+
79
+ const tokens = String(toolArg)
80
+ .split(/[,\s]+/)
81
+ .map((t) => t.trim().toLowerCase())
82
+ .filter(Boolean);
83
+
84
+ const keys = [];
85
+ const invalid = [];
86
+ for (const t of tokens) {
87
+ if (t === 'all') {
88
+ for (const k of ALL_KEYS) if (!keys.includes(k)) keys.push(k);
89
+ continue;
90
+ }
91
+ const k = ALIASES[t];
92
+ if (!k) {
93
+ invalid.push(t);
94
+ } else if (!keys.includes(k)) {
95
+ keys.push(k);
96
+ }
41
97
  }
42
98
 
43
- return { detected: false, targets: [all.claude, all.cursor, all.agents] };
99
+ return { targets: keys.map((k) => TOOLS[k]), invalid };
44
100
  }
45
101
 
46
102
  module.exports = {
47
103
  isProject,
48
- detectTargets,
104
+ detectPresent,
105
+ resolveTargets,
106
+ TOOLS,
107
+ ALL_KEYS,
49
108
  };