@impulselab/directory 1.0.8 → 2.7.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.
Files changed (4) hide show
  1. package/README.md +60 -120
  2. package/dist/index.js +1595 -0
  3. package/package.json +28 -20
  4. package/index.js +0 -666
package/README.md CHANGED
@@ -1,148 +1,88 @@
1
- # Impulse Directory Command Installer
1
+ # @impulselab/directory
2
2
 
3
- An NPX command by [Impulse Lab](https://impulselab.ai) that downloads prompts from Impulse Directory and installs them for Claude Desktop or Cursor.
3
+ Sync versioned skills, commands and agent configs across Claude Code, Cursor and Codex.
4
4
 
5
- ## 🚀 Installation and Usage
5
+ ## Quick Start
6
6
 
7
- ### Direct usage with npx
8
-
9
- ```bash
10
- npx @impulselab/directory <user-slug>/<command-slug> [--target <target>]
11
- npx @impulselab/directory stack <stack-id> [--target <target>]
7
+ ```sh
8
+ npx @impulselab/directory login
9
+ npx @impulselab/directory sync
12
10
  ```
13
11
 
14
- `--target` selects the installation target. When omitted the command defaults to `claude-slash`.
15
-
16
- When using the `stack` command, all prompts in the stack are installed for the chosen tool. Stacks must be constrained to a specific tool to be installed via NPX.
17
-
18
- ### Targets
19
-
20
- | Target | Description | Destination |
21
- |--------|-------------|-------------|
22
- | `claude-slash` | Claude slash command | `.claude/commands` (falls back to `~/.claude/commands`)
23
- | `claude-sub-agent` | Claude sub agent | `.claude/agents` (falls back to `~/.claude/agents`)
24
- | `cursor-command` | Cursor command | `.cursor/commands` (project only)
25
- | `cursor-rule` | Cursor rule | `.cursor/rules` (project only)
26
-
27
- > **Note**: Cursor targets require running the installer inside a Cursor project (a folder containing `.cursor/`). The command fails if no project folder is found.
28
-
29
- ### Examples
30
-
31
- ```bash
32
- # Download a Claude slash command from impulse.directory
33
- npx @impulselab/directory john/my-awesome-command
34
-
35
- # Install as a Claude sub agent
36
- npx @impulselab/directory john/my-awesome-command --target claude-sub-agent
12
+ `login` (no flags) starts a browser-based device authorization flow: it prints
13
+ a short code and a verification URL, opens your browser, and waits while you
14
+ approve the request on impulse.directory. Once approved it provisions and
15
+ stores an API key automatically — no copy-paste.
37
16
 
38
- # Install as a Cursor command (inside a Cursor project)
39
- npx @impulselab/directory john/my-awesome-command --target cursor-command
17
+ For headless or CI environments, pass an API key created in your profile
18
+ settings directly:
40
19
 
41
- # Install as a Cursor rule (inside a Cursor project)
42
- npx @impulselab/directory john/my-awesome-command --target cursor-rule
43
-
44
- # Install an Impulse stack (tool-specific stack ID)
45
- npx @impulselab/directory stack 01JH0000000ABCDEF --target claude-slash
46
-
47
- # Use a custom URL (local development)
48
- IMPULSE_BASE_URL=localhost:3000 npx @impulselab/directory dev-user/dev-command
49
-
50
- # Use another server
51
- IMPULSE_BASE_URL=my-custom-domain.com npx @impulselab/directory author/custom-command
20
+ ```sh
21
+ npx @impulselab/directory login --key <api-key>
52
22
  ```
53
23
 
54
- ## 📁 Command Placement Logic
55
-
56
- ### Claude targets (`claude-slash`, `claude-sub-agent`)
57
-
58
- The command searches for the `.claude` folder in the following order:
59
-
60
- 1. **Current folder**: Looks for `.claude/<target>/` in the current working directory
61
- 2. **Parent folders**: Goes up the tree to find a `.claude` folder
62
- 3. **Fallback home**: Uses `~/.claude/<target>/` if no project folder is found
63
-
64
- This allows:
65
- - Installing commands at the project level (shared with the team)
66
- - Installing personal commands (user only)
67
-
68
- ### Cursor targets (`cursor-command`, `cursor-rule`)
24
+ Either way, the key is stored in `~/.impulse/config.json` with file mode `600`.
69
25
 
70
- - Must be executed inside a Cursor project (a directory containing `.cursor/`)
71
- - Always installs into the project `.cursor` folder
72
- - Fails with an explicit message if no Cursor project is detected
26
+ ## Push Flow
73
27
 
74
- ## 🔧 Configuration
28
+ Edit a synced file locally, then publish a new version:
75
29
 
76
- ### Environment Variables
77
-
78
- | Variable | Description | Default |
79
- |----------|-------------|--------|
80
- | `IMPULSE_BASE_URL` | Base URL to download commands | `impulse.directory` |
81
-
82
- ### Automatic HTTPS/HTTP Handling
83
-
84
- - **HTTPS by default**: All URLs use HTTPS
85
- - **Fallback HTTP**: If HTTPS fails, the command automatically tries HTTP
86
- - **Localhost auto-HTTP**: URLs containing `localhost` or `127.0.0.1` use HTTP directly
87
-
88
- ## 📝 Command Format
89
-
90
- Downloaded prompts are saved as `<command-slug>.md`. Stack installs will save each command in the stack using the prompt slug (with a stack-prefixed fallback when needed).
91
-
92
- Example download URL:
93
- ```
94
- https://impulse.directory/raw/user-slug/command-slug
30
+ ```sh
31
+ npx @impulselab/directory push ~/.claude/commands/example.md -m "Tighten instructions"
32
+ npx @impulselab/directory sync
95
33
  ```
96
34
 
97
- Stack installation payloads are fetched from:
35
+ If the remote version changed first, `push` keeps your file and asks you to sync before trying again.
98
36
 
99
- ```
100
- https://impulse.directory/api/stacks/<stack-id>/npx
101
- ```
102
-
103
- ## 🛠️ Development
37
+ ## Commands
104
38
 
105
- ### Local Test
39
+ | Command | Description |
40
+ | --- | --- |
41
+ | `impulse login [--key <key>] [--url <baseUrl>]` | Browser device-flow login; `--key` is the headless/CI fallback |
42
+ | `impulse logout` | Remove the saved API key |
43
+ | `impulse whoami` | Show the authenticated user |
44
+ | `impulse sync [--project] [--prune] [--force] [--dry-run] [--json]` | Install or update synced artifacts |
45
+ | `impulse status [--project] [--json]` | Show synced, modified, outdated and missing files |
46
+ | `impulse push <path> [-m <changelog>]` | Publish a local edit as a new artifact version |
47
+ | `impulse add <owner/slug> [--target <target>]` | Public install without lock tracking; interactive picker in a TTY |
48
+ | `impulse add stack <id> [--target <target>]` | One-shot public stack install |
49
+ | `impulse agents` | List enabled agents |
50
+ | `impulse agents enable\|disable <claude\|codex\|cursor>` | Update agent targets |
106
51
 
107
- ```bash
108
- # From the npx/impulse-claude/ folder
109
- node index.js --help
110
- node index.js test-user/test-command
111
- ```
52
+ ## Installing an artifact
112
53
 
113
- ### File Structure
54
+ The web UI shows a single command per artifact:
114
55
 
115
- ```
116
- npx/impulse-claude/
117
- ├── package.json # NPM configuration
118
- ├── index.js # Main script
119
- └── README.md # Documentation
56
+ ```sh
57
+ npx @impulselab/directory <owner>/<slug>
120
58
  ```
121
59
 
122
- ## 📚 Using Downloaded Prompts
60
+ Run it in a terminal and `impulse` asks where to install — a multi-select of the
61
+ destinations that make sense for that artifact's kind (Claude Code global/project,
62
+ Cursor project, Codex global, …). Pick one or more; the file is written to each.
123
63
 
124
- - **Claude slash commands**: use `/command-name` inside Claude Desktop.
125
- - **Claude sub agents**: open Claude Desktop and select the agent from the agents list.
126
- - **Cursor commands**: trigger Cursor's command palette and run the command by name.
127
- - **Cursor rules**: Cursor loads rules automatically from `.cursor/rules` for the project.
64
+ For scripting and CI, pass `--target` to skip the prompt and install to a fixed
65
+ destination (backwards compatible one-shot behaviour):
128
66
 
129
- ## 🔍 Troubleshooting
130
-
131
- ### Common Errors
67
+ ```sh
68
+ npx @impulselab/directory <owner>/<slug> --target claude-slash
69
+ ```
132
70
 
133
- 1. **Command not found (404)**: Check the command slug
134
- 2. **Network error**: Check your connection and the base URL
135
- 3. **Permissions**: Make sure you have write permissions in the destination folder
136
- 4. **Cursor project missing**: Ensure you're running the command inside a folder containing `.cursor/`
71
+ The picker is skipped automatically when stdin/stdout is not a TTY, when `--target`
72
+ is set, or when `CI` is set. Legacy
73
+ `npx @impulselab/directory user/slug --target claude-slash` still works and is
74
+ treated as `impulse add user/slug`.
137
75
 
138
- ### Debug
76
+ > Note: `impulse add stack <id>` installs are non-interactive and use each
77
+ > artifact's per-target default for now.
139
78
 
140
- To see download details:
141
- ```bash
142
- # The command automatically displays the download path and destination folder
143
- npx @impulselab/directory debug-user/debug-command
144
- ```
79
+ ## Target Mapping
145
80
 
146
- ## 🏷️ Branding
81
+ | Kind | Claude global | Claude project | Codex global | Cursor project |
82
+ | --- | --- | --- | --- | --- |
83
+ | `skill` | `~/.claude/skills/<slug>/SKILL.md` | `.claude/skills/<slug>/SKILL.md` | - | - |
84
+ | `command` | `~/.claude/commands/<slug>.md` | `.claude/commands/<slug>.md` | `~/.codex/prompts/<slug>.md` | `.cursor/commands/<slug>.md` |
85
+ | `agent` | `~/.claude/agents/<slug>.md` | `.claude/agents/<slug>.md` | - | - |
86
+ | `rule` | - | - | - | `.cursor/rules/<slug>.mdc` |
147
87
 
148
- Made by Impulse Lab — `https://impulselab.ai`
88
+ Global sync covers Claude Code and Claude Cowork because both read `~/.claude`. Codex slash commands sync to `~/.codex/prompts`. Cursor artifacts are project-scoped, so run `impulse sync --project` from inside the project.