@elmundi/ship-cli 0.8.0 → 0.8.1
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 +63 -32
- package/lib/commands/init.mjs +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,60 +1,91 @@
|
|
|
1
1
|
# @elmundi/ship-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Ship** in your repository: agents get a standing policy to call the **methodology HTTP API** (semantic search, full doc fetch, catalog bodies, retro feedback) via the **`ship`** CLI and the URLs/snippets `ship init` writes.
|
|
4
4
|
|
|
5
|
-
Published under the
|
|
5
|
+
Published as **`@elmundi/ship-cli`** under the [elmundi](https://www.npmjs.com/org/elmundi) org; the binary name is **`ship`**.
|
|
6
6
|
|
|
7
7
|
## Requirements
|
|
8
8
|
|
|
9
|
-
- **Node.js 20+**
|
|
9
|
+
- **Node.js 20+**
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
13
|
-
After the package is [published to npm](https://www.npmjs.com/package/@elmundi/ship-cli):
|
|
14
|
-
|
|
15
13
|
```bash
|
|
16
14
|
npm install -g @elmundi/ship-cli
|
|
17
|
-
# or
|
|
15
|
+
# or one-off:
|
|
18
16
|
npx @elmundi/ship-cli help
|
|
19
17
|
```
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
## Bring Ship into your project (main path)
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
You **do not** need the Ship monorepo cloned for day-to-day use. Work in **your product repo** and wire agents to the same methodology API the CLI uses.
|
|
24
22
|
|
|
25
|
-
1.
|
|
26
|
-
2. From **any** directory, point **`SHIP_API_BASE`** at the **deployed methodology API** and list patterns or catalogs (same server as search):
|
|
23
|
+
### 1. Pick the API URL
|
|
27
24
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```
|
|
25
|
+
- **`SHIP_API_BASE`** — env var the CLI and injected snippets use (no trailing slash).
|
|
26
|
+
- Or pass **`--base-url`** on each command.
|
|
27
|
+
- Default matches other Ship tooling (public methodology host unless you override for local FastAPI).
|
|
32
28
|
|
|
33
|
-
|
|
29
|
+
### 2. Preview what `ship init` will change
|
|
34
30
|
|
|
35
|
-
|
|
31
|
+
From the **root of the repo** you want agents to use:
|
|
36
32
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
33
|
+
```bash
|
|
34
|
+
cd /path/to/your-product
|
|
35
|
+
npx @elmundi/ship-cli init --dry-run
|
|
36
|
+
```
|
|
41
37
|
|
|
42
|
-
|
|
38
|
+
`ship init` **detects what is already in the tree** and only plans injections for those stacks:
|
|
43
39
|
|
|
44
|
-
|
|
40
|
+
| If the repo has… | `ship init` can add… |
|
|
41
|
+
|------------------|----------------------|
|
|
42
|
+
| `.cursor/` | Cursor rule **`.cursor/rules/ship-methodology-api.mdc`** |
|
|
43
|
+
| **`AGENTS.md`** | Appended section (Codex-style / generic agents file) |
|
|
44
|
+
| **`CLAUDE.md`** | Appended section |
|
|
45
|
+
| **`.codex/`** | **`SHIP_API.md`** under `.codex/` |
|
|
46
|
+
| **`.github/copilot-instructions.md`** | Appended section |
|
|
45
47
|
|
|
46
|
-
|
|
47
|
-
|--------|--------|
|
|
48
|
-
| `ship pattern|tool|workflow|collection …` (plural aliases) | Same **`SHIP_API_BASE`** as search/docs when not on disk. **Local:** cwd inside Ship or **`SHIP_REPO`**. |
|
|
49
|
-
| `ship search`, `ship docs fetch|feedback` | **`SHIP_API_BASE`** (default public methodology URL; override locally) or `--base-url`. |
|
|
50
|
-
| `ship init` | Target repo cwd; **`SHIP_API_BASE` / `--base-url`** is the API URL written into snippets. |
|
|
48
|
+
If **none** of the above exist, init offers a **standalone** **`SHIP_AGENT_API.md`** in the repo root so humans can copy the contract into whatever system you use later.
|
|
51
49
|
|
|
52
|
-
|
|
50
|
+
Use **`--only cursor|agents-md|claude-md|codex|copilot`** to limit targets; **`--cwd <dir>`** to point at another root.
|
|
53
51
|
|
|
54
|
-
|
|
52
|
+
### 3. Apply with confirmation (recommended)
|
|
55
53
|
|
|
56
|
-
|
|
54
|
+
Interactive run prints the plan and asks **Apply these changes? [y/N]**:
|
|
57
55
|
|
|
58
|
-
|
|
56
|
+
```bash
|
|
57
|
+
npx @elmundi/ship-cli init
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
After you confirm **`y`**, it writes/updates the files above. Injected content tells agents to **use the Ship methodology API** (and the **`ship`** CLI from a dev shell): **search → fetch** workflow, **`ship docs fetch`** for documentation paths, **`ship pattern|tool|workflow|collection`** for catalog entries, and **`ship docs feedback`** for safe retro notes — so methodology and **tools/workflows** discovery stay consistent with the server.
|
|
61
|
+
|
|
62
|
+
### 4. Non-interactive (CI or scripts)
|
|
63
|
+
|
|
64
|
+
Only after you are happy with **`--dry-run`**:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npx @elmundi/ship-cli init --yes
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**`--force`** replaces blocks that were already injected (same marker). Without **`--force`**, existing injections are skipped.
|
|
71
|
+
|
|
72
|
+
## Commands (quick reference)
|
|
73
|
+
|
|
74
|
+
| Command | Role |
|
|
75
|
+
|--------|------|
|
|
76
|
+
| **`ship init`** | Inject agent-facing rules / sections with your **`SHIP_API_BASE`** (or **`--base-url`**). |
|
|
77
|
+
| **`ship search …`** | Vector search over methodology corpus (`POST /search`). |
|
|
78
|
+
| **`ship docs fetch …`**, **`ship docs feedback …`** | Documentation file fetch and retro feedback (`POST /fetch` with `path`, `POST /feedback`). |
|
|
79
|
+
| **`ship pattern|tool|workflow|collection`** **`list` \| `show` \| `fetch` \| `search`** | Catalogs; hosted mode uses the same API (including **`fetch`** via `POST /fetch` with `kind` + `id`). Plural aliases (`patterns`, `tools`, …) work. |
|
|
80
|
+
|
|
81
|
+
**Maintainers / full Ship checkout:** if the current directory (or **`SHIP_REPO`**) is inside the Ship monorepo, **`list` / `show` / `fetch`** for catalogs can read manifests from **disk** instead of HTTP. **`ship search`** always uses HTTP.
|
|
82
|
+
|
|
83
|
+
Run **`ship help`** for full usage.
|
|
84
|
+
|
|
85
|
+
## Versioning (until the CLI stabilizes)
|
|
86
|
+
|
|
87
|
+
Releases **bump the patch (third) number only** (e.g. `0.8.0` → `0.8.1`) while the command surface and docs are still settling. Minor/major bumps resume once things are stable.
|
|
88
|
+
|
|
89
|
+
## Publishing (maintainers)
|
|
59
90
|
|
|
60
|
-
|
|
91
|
+
GitHub Action **Publish @elmundi/ship-cli to npm** (tag **`cli-v<version>`** must match **`cli/package.json`**, or use **workflow_dispatch**). Repository secret **`NPM_TOKEN`** required. Publish from monorepo root: **`npm publish -w @elmundi/ship-cli`**, not `npm publish --prefix cli` (root package is private).
|
package/lib/commands/init.mjs
CHANGED
|
@@ -17,7 +17,7 @@ export async function initCommand(ctx, args) {
|
|
|
17
17
|
ship init [--yes] [--force] [--dry-run] [--only <id>] [--cwd <dir>]
|
|
18
18
|
|
|
19
19
|
Writes Cursor rules and/or markdown sections that point agents at the Ship methodology API
|
|
20
|
-
(base URL from SHIP_API_BASE or --base-url
|
|
20
|
+
(base URL from SHIP_API_BASE or --base-url; same default as other commands, e.g. ship.elmundi.com).
|
|
21
21
|
|
|
22
22
|
Flags:
|
|
23
23
|
--dry-run Show the plan only (recommended before first use).
|
package/package.json
CHANGED