@mcptoolshop/promo-kit 0.1.0 → 0.1.2

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/CHANGELOG.md +13 -0
  2. package/README.md +90 -37
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2 — 2026-02-16
4
+
5
+ ### Changed
6
+
7
+ - Rewrite npm README for scannability (product-page layout, split seed/artifact tables, KIT_CONFIG example)
8
+ - Logo sized to 420px (was 200→300, still too small on npmjs.com)
9
+
10
+ ## 0.1.1 — 2026-02-16
11
+
12
+ ### Fixed
13
+
14
+ - Add logo to npm README (renders on npmjs.com via raw GitHub URL)
15
+
3
16
  ## 0.1.0 — 2026-02-16
4
17
 
5
18
  Initial release of the portable promotion engine.
package/README.md CHANGED
@@ -1,48 +1,74 @@
1
- # @mcptoolshop/promo-kit
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop/mcp-tool-shop/main/logo.png" width="420" alt="mcp-tool-shop logo" />
3
+ </p>
2
4
 
3
- Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection — zero dependencies.
5
+ <h1 align="center">@mcptoolshop/promo-kit</h1>
6
+
7
+ <p align="center">
8
+ <b>Portable promotion engine for tool catalogs.</b><br/>
9
+ Receipt-backed promotions · freeze modes · drift detection · <b>zero dependencies</b>
10
+ </p>
11
+
12
+ ---
4
13
 
5
14
  ## What it does
6
15
 
7
- `promo-kit` gives your tool catalog a complete promotion pipeline:
16
+ `promo-kit` gives your tool catalog a complete, governed promotion pipeline:
8
17
 
9
- - **Bootstrap** 17 zero-state seed files (governance, promo queue, experiments, etc.)
10
- - **Generate** promotion decisions, baselines, drift reports, and trust receipts
11
- - **Verify** everything with SHA-256 hashed inputs and commit SHAs
12
- - **Freeze** automation when you need human review
18
+ - **Bootstraps** a zero-state data model (governance, promo queue, experiments, submissions)
19
+ - **Generates** promotion decisions, baselines, drift reports, and trust receipts
20
+ - **Verifies inputs** with SHA-256 hashes (and ties outputs back to commits)
21
+ - **Supports freeze modes** when you need human review
22
+ - **Keeps data local** (no cloud services, no trackers, no runtime npm deps)
13
23
 
14
- All data stays local. No cloud dependencies. No runtime npm dependencies.
24
+ If your catalog needs "trust you can audit," this is the boring machinery that makes it real.
25
+
26
+ ---
15
27
 
16
28
  ## Quickstart
17
29
 
30
+ Install:
31
+
18
32
  ```bash
19
- npm install @mcptoolshop/promo-kit
33
+ npm i @mcptoolshop/promo-kit
34
+ ```
35
+
36
+ Initialize (creates `kit.config.json` from a template if missing, then seeds data):
20
37
 
21
- # Initialize (auto-creates kit.config.json from template)
38
+ ```bash
22
39
  npx promo-kit init
40
+ ```
41
+
42
+ Edit `kit.config.json` (minimum):
43
+
44
+ - `org.name`
45
+ - `org.account`
46
+ - `site.title`
47
+ - `contact.email`
23
48
 
24
- # Edit kit.config.json with your org details:
25
- # org.name, org.account, site.title, contact.email
49
+ Validate the installation:
26
50
 
27
- # Validate the installation
51
+ ```bash
28
52
  npx promo-kit selftest
29
53
  ```
30
54
 
31
- ## CLI Commands
55
+ ---
56
+
57
+ ## CLI
32
58
 
33
59
  ### `promo-kit init`
34
60
 
35
- Creates `kit.config.json` (if absent) and bootstraps 17 seed files in your data directory.
61
+ Creates `kit.config.json` (if absent) and bootstraps seed files in your configured data directory.
36
62
 
37
63
  ```bash
38
- promo-kit init # create config + seeds
39
- promo-kit init --dry-run # show what would be created
40
- promo-kit init --force # overwrite existing kit.config.json
64
+ promo-kit init
65
+ promo-kit init --dry-run
66
+ promo-kit init --force
41
67
  ```
42
68
 
43
69
  ### `promo-kit selftest`
44
70
 
45
- Validates config, seed files, and runs all portable core generators in dry-run mode.
71
+ Validates config + seeds and runs the portable core generators in dry-run mode.
46
72
 
47
73
  ```bash
48
74
  promo-kit selftest
@@ -50,7 +76,7 @@ promo-kit selftest
50
76
 
51
77
  ### `promo-kit migrate`
52
78
 
53
- Applies schema version upgrades when `kitVersion` changes.
79
+ Applies schema upgrades when `kitVersion` changes.
54
80
 
55
81
  ```bash
56
82
  promo-kit migrate
@@ -59,25 +85,33 @@ promo-kit migrate
59
85
  ### Flags
60
86
 
61
87
  ```bash
62
- promo-kit --version # show version
63
- promo-kit --help # show usage
64
- promo-kit --print-config # show resolved config after defaults
88
+ promo-kit --version
89
+ promo-kit --help
90
+ promo-kit --print-config
65
91
  ```
66
92
 
93
+ ---
94
+
67
95
  ## Programmatic API
68
96
 
69
97
  ```js
70
- import { bootstrap, migrate, getConfig, getRoot, loadKitConfig } from "@mcptoolshop/promo-kit";
71
-
72
- // Bootstrap seed files in a directory
73
- const result = bootstrap("/path/to/your/project");
98
+ import {
99
+ bootstrap,
100
+ migrate,
101
+ getConfig,
102
+ getRoot,
103
+ loadKitConfig
104
+ } from "@mcptoolshop/promo-kit";
105
+
106
+ // Create seed files (idempotent)
107
+ const result = bootstrap("/path/to/project");
74
108
  // => { success: true, errors: [], created: [...], skipped: [...] }
75
109
 
76
- // Get resolved config (deep-merged with defaults)
110
+ // Read resolved config (deep-merged with defaults)
77
111
  const config = getConfig();
78
112
 
79
- // Run migrations
80
- const migrationResult = migrate("/path/to/your/project");
113
+ // Apply migrations (if needed)
114
+ const migrationResult = migrate("/path/to/project");
81
115
  ```
82
116
 
83
117
  Config utilities are also available as a separate export:
@@ -86,36 +120,55 @@ Config utilities are also available as a separate export:
86
120
  import { getConfig, getRoot } from "@mcptoolshop/promo-kit/config";
87
121
  ```
88
122
 
123
+ ---
124
+
89
125
  ## What it generates
90
126
 
91
- `promo-kit init` creates these seed files in your data directory:
127
+ By default, `promo-kit init` creates a set of seed files in your configured data directory.
128
+
129
+ **Core seeds:**
92
130
 
93
131
  | File | Purpose |
94
132
  |------|---------|
95
- | `governance.json` | Freeze modes, promo caps, hard rules |
133
+ | `governance.json` | Freeze modes, caps, hard rules |
96
134
  | `promo-queue.json` | Weekly promotion candidates |
97
- | `experiments.json` | Active A/B experiments |
135
+ | `experiments.json` | Active experiments |
98
136
  | `submissions.json` | External tool submissions |
99
137
  | `overrides.json` | Per-tool metadata overrides |
100
138
  | `ops-history.json` | Workflow run history |
101
139
  | `feedback.jsonl` | Append-only feedback log |
102
140
  | `worthy.json` | Worthiness rubric and scores |
141
+
142
+ **Generated artifacts** (produced by the pipeline):
143
+
144
+ | File | Purpose |
145
+ |------|---------|
103
146
  | `promo-decisions.json` | Generated promotion decisions |
104
147
  | `experiment-decisions.json` | Generated experiment decisions |
105
148
  | `baseline.json` | Computed baseline metrics |
106
149
  | `feedback-summary.json` | Aggregated feedback |
107
150
  | `queue-health.json` | Queue health metrics |
108
151
  | `recommendations.json` | Advisory recommendations |
109
- | `recommendation-patch.json` | Recommended data patches |
152
+ | `recommendation-patch.json` | Recommended governed data patches |
110
153
  | `decision-drift.json` | Week-over-week drift report |
111
154
  | `telemetry/rollup.json` | Telemetry aggregates |
112
155
 
156
+ ---
157
+
113
158
  ## Environment
114
159
 
115
160
  | Variable | Purpose |
116
161
  |----------|---------|
117
162
  | `KIT_CONFIG` | Path to an alternate `kit.config.json` (overrides cwd discovery) |
118
163
 
164
+ Example:
165
+
166
+ ```bash
167
+ KIT_CONFIG=examples/pilot-org/kit.config.json npx promo-kit selftest
168
+ ```
169
+
170
+ ---
171
+
119
172
  ## Requirements
120
173
 
121
174
  - Node.js >= 22
@@ -123,9 +176,9 @@ import { getConfig, getRoot } from "@mcptoolshop/promo-kit/config";
123
176
 
124
177
  ## Links
125
178
 
126
- - [Portable Core docs](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/portable-core.md) — full contract and field reference
127
- - [Presskit Handbook](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/presskit-handbook.md) — brand assets and verification walkthrough
128
- - [Trust Center](https://mcp-tool-shop.github.io/trust/) — live verification infrastructure
179
+ - [Portable Core docs](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/portable-core.md) — contract + field reference
180
+ - [Presskit Handbook](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/presskit-handbook.md) — assets + verification walkthrough
181
+ - [Trust Center](https://mcp-tool-shop.github.io/trust/) — live example of the verification UX
129
182
 
130
183
  ## License
131
184
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mcptoolshop/promo-kit",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection.",
5
5
  "type": "module",
6
6
  "main": "./index.mjs",