md4ai 0.10.1 → 0.10.3

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 +145 -0
  2. package/dist/index.bundled.js +439 -162
  3. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,145 @@
1
+ # md4ai
2
+
3
+ CLI for [MD4AI](https://www.md4ai.com) — scan your Claude Code projects and sync results to a web dashboard.
4
+
5
+ Discovers Claude configuration files, builds dependency graphs, detects orphans and broken references, catalogues skills and marketplace plugins, and pushes everything to a shared dashboard for team visibility.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install -g md4ai
11
+ ```
12
+
13
+ Requires **Node.js 22** or later.
14
+
15
+ ## Setup
16
+
17
+ 1. **Create an account** at [md4ai.com](https://www.md4ai.com) and create a project.
18
+
19
+ 2. **Set the Supabase key** in your shell profile:
20
+
21
+ ```bash
22
+ export MD4AI_SUPABASE_ANON_KEY="your-anon-key"
23
+ ```
24
+
25
+ 3. **Log in:**
26
+
27
+ ```bash
28
+ md4ai login
29
+ ```
30
+
31
+ 4. **Link your project:**
32
+
33
+ ```bash
34
+ cd /path/to/your-claude-project
35
+ md4ai link <project-id>
36
+ ```
37
+
38
+ The project ID is in the URL when viewing your project on the dashboard.
39
+
40
+ ## Commands
41
+
42
+ ### Scanning & Syncing
43
+
44
+ | Command | Description |
45
+ |---------|-------------|
46
+ | `md4ai scan [path]` | Scan a Claude project and push results to the dashboard. Defaults to current directory. |
47
+ | `md4ai scan --offline` | Scan locally only — generates `output/index.html` without pushing to Supabase. |
48
+ | `md4ai sync` | Re-push the most recent scan data for the current project. |
49
+ | `md4ai sync --all` | Re-scan and sync all linked projects on this device. |
50
+ | `md4ai link <project-id>` | Link the current directory to a dashboard project and run an initial scan. |
51
+
52
+ ### Analysis
53
+
54
+ | Command | Description |
55
+ |---------|-------------|
56
+ | `md4ai simulate <prompt>` | Show which files Claude Code would load for a given prompt. |
57
+ | `md4ai print <title>` | Generate a printable A3 wall-chart HTML with the dependency graph and skills table. |
58
+ | `md4ai init-manifest` | Scaffold an `env-manifest.md` from detected `.env` files in the project. |
59
+
60
+ ### Account & Device Management
61
+
62
+ | Command | Description |
63
+ |---------|-------------|
64
+ | `md4ai login` | Authenticate with email and password. |
65
+ | `md4ai logout` | Clear stored credentials. |
66
+ | `md4ai status` | Show login status, linked folders, and last sync time. |
67
+ | `md4ai add-folder` | Create a new project folder on the dashboard. |
68
+ | `md4ai add-device` | Add a device path to an existing project. |
69
+ | `md4ai list-devices` | List all devices and their linked projects. |
70
+
71
+ ### Monitoring
72
+
73
+ | Command | Description |
74
+ |---------|-------------|
75
+ | `md4ai mcp-watch` | Monitor MCP server status on this device (runs until Ctrl+C, polls every 30s). |
76
+
77
+ ### Other
78
+
79
+ | Command | Description |
80
+ |---------|-------------|
81
+ | `md4ai import <zipfile>` | Import an exported team bundle. |
82
+ | `md4ai update` | Check for updates and install if available. |
83
+ | `md4ai config set <key> <value>` | Set a configuration value (e.g. `vercel-token`). |
84
+
85
+ ## What Gets Scanned
86
+
87
+ Running `md4ai scan` discovers files in `.claude/`, `CLAUDE.md`, `skills.md`, and `docs/plans/`. It then:
88
+
89
+ - **Builds a dependency graph** by parsing markdown links, bare file paths, `$CLAUDE_PROJECT_DIR` references, and JSON hook configurations.
90
+ - **Detects orphans** — files not reachable from any root configuration.
91
+ - **Finds broken references** — links pointing to files that don't exist on disk.
92
+ - **Catalogues skills** — both project-specific and machine-wide, including marketplace plugins.
93
+ - **Flags stale files** — anything not modified in over 90 days.
94
+ - **Scans environment variables** — if an `env-manifest.md` is present, checks local `.env` files, Vercel, and GitHub Secrets for drift.
95
+ - **Detects tooling** — frameworks, runtimes, and packages from `package.json` and MCP settings.
96
+
97
+ Scan output:
98
+
99
+ ```
100
+ Files found: 41
101
+ References: 41
102
+ Broken refs: 2
103
+ Orphans: 3
104
+ Stale files: 0
105
+ Skills: 19
106
+ Toolings: 55
107
+ Env Vars: 24 (manifest found)
108
+ Plugins: 17 (17 skills)
109
+ Data hash: 9868c4a8b50f...
110
+ ```
111
+
112
+ ## File Locations
113
+
114
+ | Item | Path |
115
+ |------|------|
116
+ | Credentials | `~/.md4ai/credentials.json` |
117
+ | State | `~/.md4ai/state.json` |
118
+ | Local scan preview | `output/index.html` (in scanned project) |
119
+ | Print exports | `output/print-<timestamp>.html` |
120
+
121
+ ## Web Dashboard
122
+
123
+ All scan data syncs to [md4ai.com](https://www.md4ai.com) where you can:
124
+
125
+ - Browse the dependency graph interactively
126
+ - View file contents with structure navigation
127
+ - Track environment variable drift across local, Vercel, and GitHub
128
+ - Monitor MCP server status per device
129
+ - Share projects with team members
130
+ - Compare skills across machines
131
+
132
+ ## Tech Stack
133
+
134
+ - **TypeScript** (strict, ESM)
135
+ - **Commander** for CLI parsing
136
+ - **Supabase** for auth and data storage
137
+ - **esbuild** for bundling
138
+
139
+ ## Support
140
+
141
+ For questions, feedback, or bug reports: [richard@mediahq2.com](mailto:richard@mediahq2.com)
142
+
143
+ ## Licence
144
+
145
+ MIT — see [LICENCE](https://github.com/Media-HQ-2-Ltd/MD4AI/blob/main/LICENSE) for details.