@saptools/cf-export 0.1.0 â 0.1.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 +154 -45
- package/dist/index.js +0 -0
- package/package.json +10 -10
package/README.md
CHANGED
|
@@ -1,45 +1,86 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# ðĪ `@saptools/cf-export`
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Export CAP / Cloud Foundry project artifacts (package.json, lockfiles, .cdsrc.json, default-env.json, .npmrc) from a running SAP BTP Cloud Foundry application.** (v0.1.1+)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Pull the exact files you need for local development or debugging directly from a live CF container using `cf ssh` + CF API.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
[](https://www.npmjs.com/package/@saptools/cf-export)
|
|
10
|
+
[](./LICENSE)
|
|
11
|
+
[](https://nodejs.org)
|
|
12
|
+
[](https://packagephobia.com/result?p=@saptools/cf-export)
|
|
13
|
+
[](https://www.typescriptlang.org)
|
|
10
14
|
|
|
11
|
-
|
|
15
|
+
[Install](#-install) âĒ [Quick Start](#-quick-start) âĒ [CLI](#-cli) âĒ [API](#-programmatic-usage) âĒ [Development](#-development)
|
|
12
16
|
|
|
13
|
-
|
|
14
|
-
|--------------------|----------------------------|------------------------------------|
|
|
15
|
-
| `package.json` | cf ssh cat | optional |
|
|
16
|
-
| `package-lock.json`| cf ssh cat | optional |
|
|
17
|
-
| `pnpm-lock.yaml` | cf ssh cat | optional |
|
|
18
|
-
| `.cdsrc.json` | cf ssh cat | optional |
|
|
19
|
-
| `default-env.json` | `cf curl /v3/apps/.../env` | synthesized (VCAP + env vars) |
|
|
20
|
-
| `.npmrc` | cf ssh cat | optional, written 0600 |
|
|
17
|
+
</div>
|
|
21
18
|
|
|
22
|
-
|
|
19
|
+
---
|
|
23
20
|
|
|
24
|
-
##
|
|
21
|
+
## âĻ Features
|
|
22
|
+
|
|
23
|
+
- ðĶ **Selective artifact export** â default exports everything, or pick exactly what you need with `--file`
|
|
24
|
+
- ð **Remote root support** â specify `--remote-root` (or "root url") to locate files when they are not at the standard `/home/vcap/app`
|
|
25
|
+
- ð **Synthesized `default-env.json`** â built from live `cf curl /v3/apps/.../env` (full VCAP_SERVICES + env vars)
|
|
26
|
+
- ðĄïļ **Best-effort for optional files** â missing files (package.json, locks, .cdsrc.json, .npmrc) are skipped gracefully
|
|
27
|
+
- 𧰠**CLI + typed library** â use from terminal or Node.js/TypeScript with full types
|
|
28
|
+
- ð **Secure by default** â sensitive files (`default-env.json`, `.npmrc`) written with `0600` permissions
|
|
29
|
+
- ðŠķ **Lightweight** â only depends on `commander` + reuses `@saptools/cf-files`
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## ðĶ Install
|
|
25
34
|
|
|
26
35
|
```bash
|
|
36
|
+
# Global CLI
|
|
27
37
|
npm install -g @saptools/cf-export
|
|
28
|
-
|
|
29
|
-
|
|
38
|
+
|
|
39
|
+
# Or as a library
|
|
40
|
+
npm install @saptools/cf-export
|
|
41
|
+
# pnpm add @saptools/cf-export
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> [!NOTE]
|
|
45
|
+
> Requires **Node.js âĨ 20** and the official **`cf` CLI** on `PATH`.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## ð Quick Start
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Export credentials (used only during the operation)
|
|
53
|
+
export SAP_EMAIL="you@company.com"
|
|
54
|
+
export SAP_PASSWORD="your-sap-password"
|
|
55
|
+
|
|
56
|
+
# Export all artifacts for an app (default behavior)
|
|
57
|
+
saptools-cf-export -r ap10 -o my-org -s dev -a my-cap-app --out ./exported
|
|
58
|
+
|
|
59
|
+
# Export with a custom remote root
|
|
60
|
+
saptools-cf-export -r ap10 -o my-org -s dev -a my-cap-app \
|
|
61
|
+
--remote-root /home/vcap/app/srv \
|
|
62
|
+
--out ./exported
|
|
63
|
+
|
|
64
|
+
# Export only specific files
|
|
65
|
+
saptools-cf-export -r ap10 -o my-org -s dev -a my-cap-app \
|
|
66
|
+
--file package.json --file pnpm-lock.yaml --file default-env.json
|
|
30
67
|
```
|
|
31
68
|
|
|
32
|
-
|
|
69
|
+
After export you will have the requested files locally, ready for local CAP development or attaching to tickets.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 𧰠CLI
|
|
33
74
|
|
|
34
|
-
|
|
35
|
-
- `cf` CLI installed and in PATH
|
|
36
|
-
- `SAP_EMAIL` and `SAP_PASSWORD` environment variables (for `cf auth`)
|
|
75
|
+
The default (and only) command is `export`.
|
|
37
76
|
|
|
38
|
-
|
|
77
|
+
```bash
|
|
78
|
+
saptools-cf-export [options]
|
|
79
|
+
```
|
|
39
80
|
|
|
40
|
-
|
|
81
|
+
### Common examples
|
|
41
82
|
|
|
42
|
-
|
|
83
|
+
**Export everything (recommended default)**
|
|
43
84
|
|
|
44
85
|
```bash
|
|
45
86
|
saptools-cf-export \
|
|
@@ -50,23 +91,46 @@ saptools-cf-export \
|
|
|
50
91
|
--out ./exported-artifacts
|
|
51
92
|
```
|
|
52
93
|
|
|
53
|
-
|
|
94
|
+
**With custom remote root**
|
|
54
95
|
|
|
55
96
|
```bash
|
|
56
97
|
saptools-cf-export -r ap10 -o my-org -s dev -a my-cap-app \
|
|
57
|
-
--remote-root /home/vcap/app
|
|
98
|
+
--remote-root /home/vcap/app \
|
|
58
99
|
--out ./out
|
|
59
100
|
```
|
|
60
101
|
|
|
61
|
-
|
|
102
|
+
**Selective export**
|
|
62
103
|
|
|
63
104
|
```bash
|
|
64
|
-
saptools-cf-export ... --file package.json --file
|
|
105
|
+
saptools-cf-export ... --file package.json --file default-env.json
|
|
65
106
|
```
|
|
66
107
|
|
|
67
|
-
|
|
108
|
+
### Options
|
|
109
|
+
|
|
110
|
+
| Flag | Description | Required |
|
|
111
|
+
|-----------------------|-----------------------------------------------------------------------------|----------|
|
|
112
|
+
| `-r, --region <key>` | CF region key (e.g. `ap10`, `eu10`) | Yes |
|
|
113
|
+
| `-o, --org <name>` | CF org name | Yes |
|
|
114
|
+
| `-s, --space <name>` | CF space name | Yes |
|
|
115
|
+
| `-a, --app <name>` | CF app name | Yes |
|
|
116
|
+
| `--out <dir>` | Output directory (default: current working directory) | No |
|
|
117
|
+
| `--remote-root <path>`| Hint for the base directory inside the container (the "root url") | No |
|
|
118
|
+
| `--file <name>` | Artifact to export (repeatable). Omit to export all | No |
|
|
119
|
+
| `--all` | Explicitly request all supported artifacts (default behavior) | No |
|
|
120
|
+
|
|
121
|
+
**Supported artifact names** (use with `--file`):
|
|
122
|
+
- `package.json`
|
|
123
|
+
- `package-lock.json`
|
|
124
|
+
- `pnpm-lock.yaml`
|
|
125
|
+
- `.cdsrc.json`
|
|
126
|
+
- `default-env.json`
|
|
127
|
+
- `.npmrc`
|
|
128
|
+
|
|
129
|
+
Missing optional files are skipped (only `default-env.json` failures when explicitly selected will surface clearly).
|
|
130
|
+
|
|
131
|
+
---
|
|
68
132
|
|
|
69
|
-
## Programmatic
|
|
133
|
+
## ð§âðŧ Programmatic Usage
|
|
70
134
|
|
|
71
135
|
```ts
|
|
72
136
|
import { exportArtifacts, formatExportCompletionMessage } from "@saptools/cf-export";
|
|
@@ -79,41 +143,86 @@ const result = await exportArtifacts({
|
|
|
79
143
|
app: "my-cap-app",
|
|
80
144
|
},
|
|
81
145
|
outDir: "./export-dir",
|
|
82
|
-
remoteRoot: "/home/vcap/app",
|
|
146
|
+
remoteRoot: "/home/vcap/app", // optional "root url"
|
|
83
147
|
// artifacts: ["default-env.json", "pnpm-lock.yaml"], // optional subset
|
|
84
148
|
});
|
|
85
149
|
|
|
86
|
-
console.log(
|
|
150
|
+
console.log(
|
|
151
|
+
formatExportCompletionMessage(
|
|
152
|
+
"my-cap-app",
|
|
153
|
+
result.writtenFiles,
|
|
154
|
+
result.skipped
|
|
155
|
+
)
|
|
156
|
+
);
|
|
87
157
|
```
|
|
88
158
|
|
|
159
|
+
**Exported types & helpers** (see `src/index.ts` for full list):
|
|
160
|
+
- `exportArtifacts(options)`
|
|
161
|
+
- `formatExportCompletionMessage(appName, written, skipped)`
|
|
162
|
+
- `CfTarget`, `ArtifactName`, `ExportArtifactsOptions`, etc.
|
|
163
|
+
- Low-level: `fetchDefaultEnvJson`, `fetchRemoteTextFile`, `buildRemoteFilePaths`, `openCfSession`, etc.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
89
167
|
## Environment variables
|
|
90
168
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
169
|
+
| Variable | Purpose |
|
|
170
|
+
|----------------------|----------------------------------------------------------------------|
|
|
171
|
+
| `SAP_EMAIL` | SAP SSO email (required for `cf auth`) |
|
|
172
|
+
| `SAP_PASSWORD` | SAP SSO password |
|
|
173
|
+
| `CF_EXPORT_CF_HOME` | Reuse an existing `CF_HOME` (advanced) |
|
|
174
|
+
| `CF_EXPORT_CF_BIN` | Override the `cf` binary path (mainly for testing / fake-cf) |
|
|
175
|
+
|
|
176
|
+
---
|
|
94
177
|
|
|
95
178
|
## How remote root works
|
|
96
179
|
|
|
97
|
-
When `--remote-root`
|
|
180
|
+
When `--remote-root` is provided, candidate paths are tried in this order:
|
|
98
181
|
|
|
99
|
-
1. `${remoteRoot}/<
|
|
100
|
-
2. `/home/vcap/app/<
|
|
101
|
-
3. `<
|
|
182
|
+
1. `${remoteRoot}/<filename>`
|
|
183
|
+
2. `/home/vcap/app/<filename>`
|
|
184
|
+
3. `<filename>` (relative, last resort)
|
|
102
185
|
|
|
103
|
-
This matches the
|
|
186
|
+
This matches the strategy used by the "Export" feature in the SAP Tools VS Code extension.
|
|
187
|
+
|
|
188
|
+
---
|
|
104
189
|
|
|
105
190
|
## Security
|
|
106
191
|
|
|
107
|
-
- `default-env.json` and `.npmrc` are written with mode `0600`.
|
|
108
|
-
-
|
|
109
|
-
- Credentials are never logged.
|
|
192
|
+
- `default-env.json` and `.npmrc` are always written with mode `0600`.
|
|
193
|
+
- Every operation uses an isolated temporary `CF_HOME` (unless you explicitly override via env).
|
|
194
|
+
- Credentials are never logged or written to disk by this tool.
|
|
195
|
+
- Treat any exported `default-env.json` as a secret.
|
|
196
|
+
|
|
197
|
+
---
|
|
110
198
|
|
|
111
|
-
## Development (inside monorepo)
|
|
199
|
+
## ð ïļ Development (inside monorepo)
|
|
112
200
|
|
|
113
201
|
```bash
|
|
202
|
+
pnpm install
|
|
114
203
|
pnpm --filter @saptools/cf-export build
|
|
115
204
|
pnpm --filter @saptools/cf-export typecheck
|
|
116
205
|
pnpm --filter @saptools/cf-export lint
|
|
117
206
|
pnpm --filter @saptools/cf-export test:unit
|
|
118
207
|
pnpm --filter @saptools/cf-export test:e2e:fake
|
|
119
208
|
```
|
|
209
|
+
|
|
210
|
+
The fake-backed e2e tests do not require real SAP credentials.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## ð Related packages
|
|
215
|
+
|
|
216
|
+
- ðĨ [`@saptools/cf-files`](https://www.npmjs.com/package/@saptools/cf-files) â download files & generate `default-env.json` from CF
|
|
217
|
+
- ð [`@saptools/cf-sync`](https://www.npmjs.com/package/@saptools/cf-sync) â full CF topology + HANA binding sync
|
|
218
|
+
- 𧰠[Full saptools monorepo](https://github.com/dongitran/saptools)
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## ð License
|
|
223
|
+
|
|
224
|
+
MIT ÂĐ Dong Tran
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
Made to make SAP BTP CF development less painful âĻ
|
package/dist/index.js
CHANGED
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@saptools/cf-export",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Export CAP/CF project artifacts (package.json, lockfiles, .cdsrc.json, default-env.json, .npmrc) from running SAP BTP Cloud Foundry apps",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"publishConfig": {
|
|
@@ -24,14 +24,6 @@
|
|
|
24
24
|
"engines": {
|
|
25
25
|
"node": ">=20.0.0"
|
|
26
26
|
},
|
|
27
|
-
"scripts": {
|
|
28
|
-
"build": "tsup",
|
|
29
|
-
"typecheck": "tsc --noEmit",
|
|
30
|
-
"lint": "eslint src tests --ignore-pattern tests/e2e/fixtures/fake-cf.mjs",
|
|
31
|
-
"test:unit": "vitest run --coverage",
|
|
32
|
-
"test:e2e": "playwright test",
|
|
33
|
-
"test:e2e:fake": "playwright test tests/e2e/cf-export.e2e.ts"
|
|
34
|
-
},
|
|
35
27
|
"keywords": [
|
|
36
28
|
"sap",
|
|
37
29
|
"cloud-foundry",
|
|
@@ -62,5 +54,13 @@
|
|
|
62
54
|
"@vitest/coverage-v8": "^3.0.0",
|
|
63
55
|
"tsup": "^8.3.0",
|
|
64
56
|
"vitest": "^3.0.0"
|
|
57
|
+
},
|
|
58
|
+
"scripts": {
|
|
59
|
+
"build": "tsup",
|
|
60
|
+
"typecheck": "tsc --noEmit",
|
|
61
|
+
"lint": "eslint src tests --ignore-pattern tests/e2e/fixtures/fake-cf.mjs",
|
|
62
|
+
"test:unit": "vitest run --coverage",
|
|
63
|
+
"test:e2e": "playwright test",
|
|
64
|
+
"test:e2e:fake": "playwright test tests/e2e/cf-export.e2e.ts"
|
|
65
65
|
}
|
|
66
|
-
}
|
|
66
|
+
}
|