@numbered/docs-to-context 0.1.4 → 0.1.5

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.
Files changed (3) hide show
  1. package/README.md +47 -9
  2. package/package.json +1 -1
  3. package/scripts/inject.ts +9 -5
package/README.md CHANGED
@@ -12,7 +12,7 @@ Run from the project root. Auto-detects platform (Next.js or Shopify).
12
12
 
13
13
  ### Options
14
14
 
15
- ```bash
15
+ ```
16
16
  bunx @numbered/docs-to-context [project_root] [options]
17
17
 
18
18
  --platform nextjs|shopify Force platform detection
@@ -20,6 +20,24 @@ bunx @numbered/docs-to-context [project_root] [options]
20
20
  --output path Custom output directory
21
21
  ```
22
22
 
23
+ ### Output
24
+
25
+ ```
26
+ @numbered/docs-to-context
27
+ ─────────────────────
28
+
29
+ Extract
30
+ ● Platform: nextjs
31
+ ✓ Extracted 74 components
32
+ /path/to/project/docs/components
33
+
34
+ Inject
35
+ ● Found 14 core doc(s)
36
+ ✓ Injected index into CLAUDE.md
37
+
38
+ Done.
39
+ ```
40
+
23
41
  ## What it does
24
42
 
25
43
  1. **Extracts** component APIs from source files into per-component MDX docs at `docs/components/`
@@ -29,11 +47,13 @@ bunx @numbered/docs-to-context [project_root] [options]
29
47
 
30
48
  ### Injected format
31
49
 
32
- Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
50
+ Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). Files are grouped by directory to minimize token usage:
33
51
 
34
52
  ```markdown
35
53
  <!-- PROJECT_DOCS_START -->
54
+
36
55
  ## Project Docs
56
+
37
57
  |[Frontend]|root: ./docs
38
58
  |frontend:{design-system.md,grid-system.md}
39
59
  [Component Index]|root: ./docs/components
@@ -43,9 +63,16 @@ Follows the [Vercel compressed folder path convention](https://vercel.com/blog/a
43
63
  |[Entities]|root: ./docs
44
64
  |specs/architecture:{README.md,entities.md,entity-relationship-diagram.md}
45
65
  |specs/architecture/entities:{about.md,journal.md,happening.md}
66
+
46
67
  <!-- PROJECT_DOCS_END -->
47
68
  ```
48
69
 
70
+ Three sections:
71
+
72
+ - **Frontend** — design tokens, grid/layout (read before styling)
73
+ - **Components** — per-component MDX with props, variants, defaults
74
+ - **Entities** — content architecture (read before schema/data work)
75
+
49
76
  ## Supported platforms
50
77
 
51
78
  ### Next.js
@@ -69,17 +96,28 @@ Scans `snippets/*.liquid` and extracts:
69
96
 
70
97
  The following files are automatically included in the index when present:
71
98
 
72
- | Section | Path | Purpose |
73
- |---|---|---|
74
- | Frontend | `docs/design-system.md` | Design tokens, typography, colors |
75
- | Frontend | `docs/grid-system.md` | Grid system, breakpoints, fluid utilities |
99
+ | Section | Path | Purpose |
100
+ | -------- | --------------------------------- | ----------------------------------------- |
101
+ | Frontend | `docs/design-system.md` | Design tokens, typography, colors |
102
+ | Frontend | `docs/grid-system.md` | Grid system, breakpoints, fluid utilities |
76
103
  | Entities | `docs/specs/architecture/**/*.md` | Document types, ER diagrams, entity specs |
77
104
 
105
+ ## Fresh clone
106
+
107
+ Since `docs/components/` is gitignored, agents on a fresh clone will see:
108
+
109
+ ```
110
+ |If ./docs/components is missing, run: bunx @numbered/docs-to-context
111
+ ```
112
+
113
+ No plugin install, no auth — just `bun` and the public npm package.
114
+
78
115
  ## Publishing
79
116
 
80
117
  ```bash
81
- cd packages/project-docs
118
+ cd packages/docs-to-context
82
119
  npm login --scope=@numbered
83
- bun run publish:dry # preview
84
- bun run publish:npm # publish to npm (public)
120
+ bun run publish:dry # preview
121
+ bun run publish:patch # bump patch + publish
122
+ bun run publish:minor # bump minor + publish
85
123
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numbered/docs-to-context",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Generate project docs (component APIs, design system, architecture) and inject index into CLAUDE.md",
5
5
  "bin": {
6
6
  "docs-to-context": "scripts/generate.ts"
package/scripts/inject.ts CHANGED
@@ -124,11 +124,15 @@ function injectIntoClaudeMd(claudeMdPath: string, block: string) {
124
124
 
125
125
  const content = readFileSync(claudeMdPath, 'utf-8')
126
126
 
127
- // Single-pass: replace returns original if no match
128
- const replaced = content.replace(MARKER_PATTERN, block)
129
- const newContent = replaced === content
130
- ? content.trimEnd() + '\n\n' + block + '\n'
131
- : replaced
127
+ // Single-pass: replacer callback tracks whether a match occurred
128
+ let matched = false
129
+ const replaced = content.replace(MARKER_PATTERN, () => {
130
+ matched = true
131
+ return block
132
+ })
133
+ const newContent = matched
134
+ ? replaced
135
+ : content.trimEnd() + '\n\n' + block + '\n'
132
136
 
133
137
  writeFileSync(claudeMdPath, newContent, 'utf-8')
134
138
  log.success('Injected index into CLAUDE.md')