@solidactions/cli 1.33.0 → 2.0.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 +52 -12
- package/dist/commands/ai-init.js +5 -2
- package/dist/commands/dev.js +137 -1
- package/dist/commands/device-login.js +5 -3
- package/dist/commands/{docs-pull.js → doc-pull.js} +10 -10
- package/dist/commands/{docs-push.js → doc-push.js} +21 -10
- package/dist/commands/{docs-upload.js → doc-upload.js} +4 -4
- package/dist/commands/login.js +1 -1
- package/dist/commands/skill-exec.js +3 -3
- package/dist/commands/skill-run.js +2 -2
- package/dist/index.js +12 -12
- package/dist/utils/api.js +1 -1
- package/dist/utils/docs-manifest.js +4 -4
- package/dist/utils/sdk-version.js +62 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -235,34 +235,34 @@ For `skill dev` / `skill exec`, pass the command as separate words after `--` (e
|
|
|
235
235
|
|---------|-----------|-------------|
|
|
236
236
|
| `role push <dir>` | `--dry-run`, `--json` | Push a role definition (create or update) |
|
|
237
237
|
|
|
238
|
-
###
|
|
238
|
+
### doc
|
|
239
239
|
|
|
240
240
|
Manage docs in SA-Docs (the app's built-in documentation vault). `push` is drift-guarded for files previously pulled: a tracked file whose server revision has moved since the pull fails with `re-pull to merge, or pass --force to overwrite` rather than silently clobbering it; untracked files always go through the existing bulk-create path.
|
|
241
241
|
|
|
242
242
|
| Command | Key Flags | Description |
|
|
243
243
|
|---------|-----------|-------------|
|
|
244
|
-
| `
|
|
245
|
-
| `
|
|
246
|
-
| `
|
|
244
|
+
| `doc pull <folder> [dest]` | `-y`, `--overwrite`, `--json` | Download a Docs folder tree (markdown + media) to `dest` (defaults to `./<last-segment>/`); writes a `.solidactions-docs.json` revision manifest (including a `body_sha256` content hash per file) used by `push`'s drift guard. Falls back to fetching a single doc if `folder` is a doc path, not a folder |
|
|
245
|
+
| `doc push <dir>` | `--on-conflict`, `--type`, `--folder`, `--dry-run`, `--force`, `--json` | Recursively upload a local markdown tree. Manifest-tracked files (from a prior `pull`) are written with a `base_revision` guard and reported separately as written/drifted/unchanged; files whose content hash still matches the last pull are skipped as unchanged (no write, no revision bump). Tracked media files whose bytes changed are replaced the same way, under the same guard; a tracked media file missing locally is left alone — `push` never deletes. An untracked binary in the tree is warned about, never uploaded (use `doc upload`). `--force` skips the drift guard (unchanged files are still skipped). `--dry-run` previews without writing. Untracked files are created under the manifest's `folder_path` when `<dir>` came from a `doc pull` (pass `--folder` to override); an untracked file whose title already exists in the target folder is skipped per `--on-conflict` (default `skip`, reported as `duplicate_title`) |
|
|
246
|
+
| `doc upload <files...>` | `--folder`, `--title`, `--replace <doc-id-or-path>` | Upload one or more media files to SA-Docs (requires a token with the "docs" ability); `--title` only valid for a single file. `--replace` swaps the bytes behind an existing media doc instead of creating a new one — see below |
|
|
247
247
|
|
|
248
|
-
`
|
|
248
|
+
`doc upload <file> --replace <doc-id-or-path>` swaps the bytes behind an existing media doc, keeping its id, title, and folder, so embeds and references keep resolving — the old image stays in the doc's version history. Single file only; cannot be combined with `--title` or `--folder`. A purely numeric argument is a doc id; anything else is a docs path (`marketing/hero.png`), resolved against the doc's **title** — which `doc pull` may have sanitized, so for path-based work on a pulled folder prefer `doc push` instead:
|
|
249
249
|
|
|
250
250
|
```bash
|
|
251
|
-
solidactions
|
|
252
|
-
solidactions
|
|
251
|
+
solidactions doc upload logo-v2.png --replace 482
|
|
252
|
+
solidactions doc upload logo-v2.png --replace marketing/logo.png
|
|
253
253
|
```
|
|
254
254
|
|
|
255
|
-
**`
|
|
255
|
+
**`doc pull` propagates deletions, within limits.** A file is removed locally only when its doc was deleted on the server *and* the file's bytes still match what the last pull gave it (the manifest's `body_sha256`) — anything you've edited locally is kept, with a warning that it's now untracked (re-create a markdown doc with `doc push`, a media doc with `doc upload`). Deletions only propagate when the destination's existing manifest `folder_path` matches the folder you're pulling (so pulling a different folder into a directory holding an old manifest deletes nothing), and never on the single-doc pull path; when propagation is skipped for either reason, `pull` says so. Nothing outside the destination directory is removed: every candidate path is resolved physically (so a symlinked subdirectory cannot lead the delete outside), and a file the same pull just wrote is never deleted, even if a case-only rename makes it look orphaned on a case-insensitive filesystem.
|
|
256
256
|
|
|
257
|
-
**`
|
|
257
|
+
**`doc pull --overwrite` is destructive.** If a manifest-tracked file still exists on the server *and* your local copy no longer matches the `body_sha256` recorded at the last pull (i.e. you've edited it and haven't pushed yet), a plain `doc pull` — even with `-y`/`--yes` — refuses with exit 1, naming every modified file, rather than silently discarding your edits. Nothing is written before that refusal. `-y`/`--yes` only bypasses the generic "destination is not empty" prompt; it does not cover locally-modified tracked files. Pass `--overwrite` to discard those local changes and re-pull server content anyway (it also implies `--yes`).
|
|
258
258
|
|
|
259
259
|
You do **not** need `--overwrite` to keep an edited file whose doc was deleted on the server — that case is handled by deletion propagation above, on the default path, and the file is kept with a warning.
|
|
260
260
|
|
|
261
|
-
**Getting a doc id.** `
|
|
261
|
+
**Getting a doc id.** `doc upload --replace` accepts a docs path (`marketing/hero.png`), so you rarely need an id. If you want one, `doc pull` records it per file in the destination's `.solidactions-docs.json` sidecar, and `import_outputs` returns the ids it created. Note that `--replace` does not update a pulled directory's manifest. If you replace a tracked image out-of-band and leave the local file untouched, the next `doc push` reports it as **unchanged** and does nothing — the content hash matches, so `push` never asks the server. (Edit the local file too, and the drift guard fires as expected.) Re-pull to resync the manifest.
|
|
262
262
|
|
|
263
|
-
**`
|
|
263
|
+
**`doc push` and deleted docs.** If a tracked file's doc was deleted on the server, `push` names it per file (`doc <id> no longer exists (deleted remotely) — re-pull to untrack it, then push to re-create`) and carries on with the other files. Note the deleted doc still holds its title until it leaves the trash, so re-creating it needs the trashed copy restored or purged first — `push` says so if you hit it. `push` exits 1 on drift (a tracked doc moved on since your pull) and on any per-file server error; a deleted doc alone is not an error.
|
|
264
264
|
|
|
265
|
-
**`
|
|
265
|
+
**`doc pull` refuses to replace another folder's manifest.** If the destination already tracks a different folder, pulling into it would leave the previously tracked files untracked — and untracked files are not protected from being overwritten by a later pull. `pull` refuses (exit 1, before any network request) and names both folders. Pull into a different directory, or pass `--overwrite` to replace the manifest anyway. This also covers the single-doc pull path, whose one-entry manifest would otherwise clobber a folder's.
|
|
266
266
|
|
|
267
267
|
### workspace
|
|
268
268
|
|
|
@@ -297,8 +297,48 @@ git clone https://github.com/SolidActions/solidactions-cli.git
|
|
|
297
297
|
cd solidactions-cli
|
|
298
298
|
npm install
|
|
299
299
|
npm run build
|
|
300
|
+
npm test # vitest run
|
|
300
301
|
```
|
|
301
302
|
|
|
303
|
+
## Release Checklist
|
|
304
|
+
|
|
305
|
+
Run these before publishing a new version. `npm run check:release` covers the
|
|
306
|
+
first three in one command.
|
|
307
|
+
|
|
308
|
+
1. **Build** — `npm run build` (must be clean; `tsc` errors block the release).
|
|
309
|
+
2. **Unit tests** — `npm test`. Covers config resolution, command wiring, and
|
|
310
|
+
the `oauth-actions show` snippet renderer (the highest-risk regression
|
|
311
|
+
surface — array query-param serialization and the proxy-managed header
|
|
312
|
+
filter both have fixture-backed tests under `tests/fixtures/`).
|
|
313
|
+
3. **Init smoke** — `npm run smoke:init` scaffolds a project end to end.
|
|
314
|
+
4. **oauth-actions smoke** — `bash scripts/smoke.sh` exercises
|
|
315
|
+
`oauth-actions list|search|show` (plus the 404 path) against a real local
|
|
316
|
+
stub server, so it needs no credentials:
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
npm run build && bash scripts/smoke.sh
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
To smoke a deployed server instead, pass `--live` with real credentials:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
SOLIDACTIONS_HOST=https://app.solidactions.com \
|
|
326
|
+
SOLIDACTIONS_API_KEY=... \
|
|
327
|
+
SOLIDACTIONS_WORKSPACE_ID=... \
|
|
328
|
+
bash scripts/smoke.sh --live
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
The script exits non-zero on the first failed check.
|
|
332
|
+
5. **SDK docs pin** — `ai init` fetches `docs/sdk-reference.md` from a
|
|
333
|
+
`solidactions-ts-sdk` tag, not from that repo's `main`. The tag is derived
|
|
334
|
+
at runtime from the `@solidactions/sdk` version this package declares (see
|
|
335
|
+
`src/utils/sdk-version.ts`), so bumping that dependency moves the docs ref
|
|
336
|
+
with it — nothing to update by hand. `tests/sdk-docs-ref.test.ts` fails if
|
|
337
|
+
the declared range has no explicit minimum version to derive from.
|
|
338
|
+
6. **Version bump** — update `package.json`, then publish. Once the publish
|
|
339
|
+
flow from PR #78 lands, the GitHub release **tag** drives the published npm
|
|
340
|
+
version (semver-guarded); the bump commit stays conventional.
|
|
341
|
+
|
|
302
342
|
## License
|
|
303
343
|
|
|
304
344
|
MIT
|
package/dist/commands/ai-init.js
CHANGED
|
@@ -12,6 +12,7 @@ const prompts_1 = __importDefault(require("prompts"));
|
|
|
12
12
|
const fs_extra_1 = __importDefault(require("fs-extra"));
|
|
13
13
|
const path_1 = __importDefault(require("path"));
|
|
14
14
|
const github_1 = require("../utils/github");
|
|
15
|
+
const sdk_version_1 = require("../utils/sdk-version");
|
|
15
16
|
const markers_1 = require("../utils/markers");
|
|
16
17
|
const skills_1 = require("../utils/skills");
|
|
17
18
|
exports.NON_TTY_DEFAULT_NOTICE = 'No --claude/--agents given and non-interactive — defaulting to CLAUDE.md; pass --agents for Codex/Cursor/Gemini.';
|
|
@@ -60,8 +61,10 @@ async function aiInit(options = {}, resolvedTarget) {
|
|
|
60
61
|
console.log(chalk_1.default.blue('Fetching AI helper content...'));
|
|
61
62
|
// Fetch slim helper content for the chosen target.
|
|
62
63
|
const aiContent = await (0, skills_1.fetchAiHelperContent)(targetFile);
|
|
63
|
-
// Fetch SDK reference (always)
|
|
64
|
-
|
|
64
|
+
// Fetch SDK reference (always), pinned to the tag matching the
|
|
65
|
+
// @solidactions/sdk version this CLI declares, so scaffolded projects
|
|
66
|
+
// never get docs for an SDK newer than the one the CLI targets.
|
|
67
|
+
const sdkContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-ts-sdk', 'docs/sdk-reference.md', (0, sdk_version_1.sdkDocsRef)());
|
|
65
68
|
// Save SDK reference to .solidactions/sdk-reference.md.
|
|
66
69
|
fs_extra_1.default.ensureDirSync('.solidactions');
|
|
67
70
|
fs_1.default.writeFileSync('.solidactions/sdk-reference.md', sdkContent, 'utf8');
|
package/dist/commands/dev.js
CHANGED
|
@@ -37,9 +37,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
37
37
|
};
|
|
38
38
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
39
|
exports.buildSaApiClient = buildSaApiClient;
|
|
40
|
+
exports.assertProjectLocalConfig = assertProjectLocalConfig;
|
|
40
41
|
exports.resolveProjectSlug = resolveProjectSlug;
|
|
41
42
|
exports.runDev = runDev;
|
|
42
43
|
exports.dev = dev;
|
|
44
|
+
exports.resolveDevProjectDir = resolveDevProjectDir;
|
|
43
45
|
const child_process_1 = require("child_process");
|
|
44
46
|
const path_1 = __importDefault(require("path"));
|
|
45
47
|
const fs_1 = __importDefault(require("fs"));
|
|
@@ -48,6 +50,7 @@ const chalk_1 = __importDefault(require("chalk"));
|
|
|
48
50
|
const js_yaml_1 = __importDefault(require("js-yaml"));
|
|
49
51
|
const crypto_1 = require("crypto");
|
|
50
52
|
const module_1 = require("module");
|
|
53
|
+
const config_1 = require("../utils/config");
|
|
51
54
|
/**
|
|
52
55
|
* Build the production `SaApiClient`: fetches `variable-mappings` with
|
|
53
56
|
* `reveal=true` so secret values are populated on `ctx.vars`. When the token
|
|
@@ -79,6 +82,112 @@ function buildSaApiClient(config, projectSlug) {
|
|
|
79
82
|
};
|
|
80
83
|
return client;
|
|
81
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* Canonicalize a config path for identity comparison, so a project reached
|
|
87
|
+
* through a symlinked alias is not mistaken for a different project. Falls back
|
|
88
|
+
* to the given path when the file cannot be resolved (e.g. a broken symlink) —
|
|
89
|
+
* the caller is only comparing two paths, not dereferencing them.
|
|
90
|
+
*/
|
|
91
|
+
function realPath(p) {
|
|
92
|
+
try {
|
|
93
|
+
return fs_1.default.realpathSync(p);
|
|
94
|
+
}
|
|
95
|
+
catch {
|
|
96
|
+
return p;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Throw when a local config file exists but cannot be parsed as JSON.
|
|
101
|
+
*
|
|
102
|
+
* `readConfigFile()` swallows parse errors and returns null, which makes a
|
|
103
|
+
* corrupt local config indistinguishable from an absent one — resolution then
|
|
104
|
+
* falls through to the global config. Re-reading here lets us surface the
|
|
105
|
+
* actual parse error instead.
|
|
106
|
+
*/
|
|
107
|
+
function assertLocalConfigParses(configPath) {
|
|
108
|
+
try {
|
|
109
|
+
JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
|
|
110
|
+
}
|
|
111
|
+
catch (e) {
|
|
112
|
+
throw new Error(`local config at ${configPath} is malformed: ${e?.message ?? e}\n`
|
|
113
|
+
+ 'It exists but cannot be parsed, so config resolution would fall through to the global '
|
|
114
|
+
+ `config ${(0, config_1.getGlobalConfigPath)()}, which usually points at production.\n`
|
|
115
|
+
+ 'Fix: repair the file, or re-run `solidactions login --local` to rewrite it.');
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Refuse to run `dev --env` against a config the user did not choose.
|
|
120
|
+
*
|
|
121
|
+
* `dev --env` builds its API client from `resolveConfig(process.cwd())`, which
|
|
122
|
+
* falls back to the GLOBAL `~/.solidactions/config.json` when no project-local
|
|
123
|
+
* `.solidactions/config.json` is reachable. That global config typically points
|
|
124
|
+
* at PRODUCTION, so a workflow run from outside its project's `.solidactions`
|
|
125
|
+
* tree used to silently fetch vars from — and target — the wrong tenant, with
|
|
126
|
+
* no diagnostic beyond a bare 404 (issue #30).
|
|
127
|
+
*
|
|
128
|
+
* Three situations are refused:
|
|
129
|
+
* 1. No project-local config above the cwd — the run WOULD fall back to the
|
|
130
|
+
* global config.
|
|
131
|
+
* 2. A local config that EXISTS but does not parse — `readConfigFile()`
|
|
132
|
+
* swallows the parse error and returns null, so a corrupt file resolves
|
|
133
|
+
* exactly like an absent one and falls through to global. Same leak, but
|
|
134
|
+
* it slips past a path-existence check.
|
|
135
|
+
* 3. The entry file's project-local config is NOT the one the cwd resolves to
|
|
136
|
+
* — the run would target a different project's account. NOTE: this branch
|
|
137
|
+
* only engages for entries run IN-PROCESS (`.js`/`.mjs`). A `.ts` entry is
|
|
138
|
+
* re-exec'd by {@link reexecUnderTsx} with the child's cwd already set to
|
|
139
|
+
* the entry's own project root, so by the time the guard runs in the child
|
|
140
|
+
* the two paths are equal by construction — the child is correctly
|
|
141
|
+
* anchored to the entry's project and there is nothing to mismatch.
|
|
142
|
+
*
|
|
143
|
+
* `SOLIDACTIONS_HOST` / `SOLIDACTIONS_API_KEY` env overrides bypass the guard
|
|
144
|
+
* ONLY when BOTH are set. `resolveConfig()` picks host and apiKey INDEPENDENTLY
|
|
145
|
+
* (env > local > global), so with just one var set the OTHER field still falls
|
|
146
|
+
* through to the global config — i.e. a partial override would send a run to
|
|
147
|
+
* the production host, or to production credentials, exactly the way #30
|
|
148
|
+
* describes. A partial override therefore refuses like any other unanchored
|
|
149
|
+
* run, naming the field that would fall through.
|
|
150
|
+
*/
|
|
151
|
+
function assertProjectLocalConfig(entryPath, env) {
|
|
152
|
+
const envHost = !!process.env.SOLIDACTIONS_HOST;
|
|
153
|
+
const envApiKey = !!process.env.SOLIDACTIONS_API_KEY;
|
|
154
|
+
if (envHost && envApiKey) {
|
|
155
|
+
// Both credential fields come from env — nothing can fall to global.
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
const entryLocal = (0, config_1.findLocalConfigPath)(path_1.default.dirname(path_1.default.resolve(entryPath)));
|
|
159
|
+
const cwdLocal = (0, config_1.findLocalConfigPath)(process.cwd());
|
|
160
|
+
if (!cwdLocal) {
|
|
161
|
+
// Exactly one env override set: name the field that would fall through.
|
|
162
|
+
let partial = '';
|
|
163
|
+
if (envHost !== envApiKey) {
|
|
164
|
+
const supplied = envHost ? 'SOLIDACTIONS_HOST' : 'SOLIDACTIONS_API_KEY';
|
|
165
|
+
const missing = envHost ? 'apiKey' : 'host';
|
|
166
|
+
const missingVar = envHost ? 'SOLIDACTIONS_API_KEY' : 'SOLIDACTIONS_HOST';
|
|
167
|
+
partial = `${supplied} is set, but host and apiKey resolve independently — `
|
|
168
|
+
+ `\`${missing}\` would still come from the global config. `
|
|
169
|
+
+ `Set ${missingVar} too to target a host explicitly.\n`;
|
|
170
|
+
}
|
|
171
|
+
const found = entryLocal
|
|
172
|
+
? `The workflow's own project config is ${entryLocal}.\n`
|
|
173
|
+
: '';
|
|
174
|
+
throw new Error(`no project-local .solidactions/config.json found from ${process.cwd()}.\n`
|
|
175
|
+
+ `Refusing to run --env ${env} against the global config ${(0, config_1.getGlobalConfigPath)()}, `
|
|
176
|
+
+ 'which usually points at production.\n'
|
|
177
|
+
+ partial
|
|
178
|
+
+ found
|
|
179
|
+
+ 'Fix: cd into the project directory before running `solidactions dev`, '
|
|
180
|
+
+ 'or run `solidactions login --local` there to create a project-local config.');
|
|
181
|
+
}
|
|
182
|
+
// Exists — but a file that doesn't parse resolves like an absent one.
|
|
183
|
+
assertLocalConfigParses(cwdLocal);
|
|
184
|
+
if (entryLocal && realPath(entryLocal) !== realPath(cwdLocal)) {
|
|
185
|
+
throw new Error(`config mismatch: the workflow's project config is ${entryLocal}, `
|
|
186
|
+
+ `but this directory resolves to ${cwdLocal}.\n`
|
|
187
|
+
+ `Refusing to run --env ${env} against a config from a different project.\n`
|
|
188
|
+
+ 'Fix: cd into the workflow\'s project directory before running `solidactions dev`.');
|
|
189
|
+
}
|
|
190
|
+
}
|
|
82
191
|
/**
|
|
83
192
|
* Resolve the SA project slug for a workflow entry file and a target env.
|
|
84
193
|
*
|
|
@@ -271,6 +380,9 @@ async function runDev(opts) {
|
|
|
271
380
|
apiClient = opts.api;
|
|
272
381
|
}
|
|
273
382
|
else {
|
|
383
|
+
// Refuse BEFORE any config resolution / network work when the only
|
|
384
|
+
// reachable config is the global (usually production) one — see #30.
|
|
385
|
+
assertProjectLocalConfig(opts.entry, opts.env);
|
|
274
386
|
// Production path: build from CLI config.
|
|
275
387
|
// Lazy-import to keep tests fast (no config resolution needed).
|
|
276
388
|
const { requireConfigWithWorkspace } = await Promise.resolve().then(() => __importStar(require('../utils/api')));
|
|
@@ -603,7 +715,7 @@ async function dev(file, options) {
|
|
|
603
715
|
}
|
|
604
716
|
// .ts entry under plain node has no loader — re-exec under tsx, then return.
|
|
605
717
|
if (!hasTsLoader() && /\.(ts|tsx|mts|cts)$/.test(filePath)) {
|
|
606
|
-
const projectDir =
|
|
718
|
+
const projectDir = resolveDevProjectDir(filePath);
|
|
607
719
|
// Surface a clear slug-resolution error here (before forking) rather
|
|
608
720
|
// than letting the child fail with an opaque exit code. Only relevant
|
|
609
721
|
// when an env was requested (bare runs do no platform fetch).
|
|
@@ -651,6 +763,30 @@ async function dev(file, options) {
|
|
|
651
763
|
console.error(chalk_1.default.red(`✗ failed (${r.phase ?? 'run'}):`), r.error?.message ?? String(r.error));
|
|
652
764
|
process.exit(1);
|
|
653
765
|
}
|
|
766
|
+
/**
|
|
767
|
+
* Choose the cwd for the tsx re-exec child.
|
|
768
|
+
*
|
|
769
|
+
* The child's cwd decides which config `resolveConfig(process.cwd())` picks, so
|
|
770
|
+
* it must be anchored to the workflow's OWN `.solidactions/config.json` when one
|
|
771
|
+
* exists. Using the nearest `package.json` parent (the previous behaviour) is
|
|
772
|
+
* wrong in a monorepo: for `/repo/package.json` + `/repo/apps/a/.solidactions/`,
|
|
773
|
+
* an entry under `apps/a` would re-exec with cwd `/repo`, where no local config
|
|
774
|
+
* is reachable — so resolution fell back to the global (production) config and
|
|
775
|
+
* the #30 guard then refused a perfectly legitimate run.
|
|
776
|
+
*
|
|
777
|
+
* Preference order: the directory owning the entry's nearest local config, then
|
|
778
|
+
* the nearest `package.json` parent, then the current cwd. `npx` still resolves
|
|
779
|
+
* `tsx` by walking node_modules upward, so a package-less project directory is
|
|
780
|
+
* fine.
|
|
781
|
+
*/
|
|
782
|
+
function resolveDevProjectDir(entryPath) {
|
|
783
|
+
const localConfig = (0, config_1.findLocalConfigPath)(path_1.default.dirname(path_1.default.resolve(entryPath)));
|
|
784
|
+
if (localConfig) {
|
|
785
|
+
// <dir>/.solidactions/config.json → <dir>
|
|
786
|
+
return path_1.default.dirname(path_1.default.dirname(localConfig));
|
|
787
|
+
}
|
|
788
|
+
return findProjectRoot(entryPath) ?? process.cwd();
|
|
789
|
+
}
|
|
654
790
|
function findProjectRoot(startPath) {
|
|
655
791
|
let dir = path_1.default.dirname(startPath);
|
|
656
792
|
for (let i = 0; i < 10; i++) {
|
|
@@ -76,11 +76,13 @@ async function deviceLogin(options) {
|
|
|
76
76
|
const host = resolved.host;
|
|
77
77
|
console.log(chalk_1.default.blue('Requesting device authorization...'));
|
|
78
78
|
const code = await requestDeviceCode(host);
|
|
79
|
-
|
|
79
|
+
// Deliberately the bare verification_uri, never verification_uri_complete:
|
|
80
|
+
// the server ignores prefilled codes (phishing defense) — the user types
|
|
81
|
+
// the code shown here.
|
|
80
82
|
console.log('');
|
|
81
83
|
console.log(chalk_1.default.green('To finish signing in, visit:'));
|
|
82
|
-
console.log(' ' + chalk_1.default.blue.underline(
|
|
83
|
-
console.log(chalk_1.default.gray('
|
|
84
|
+
console.log(' ' + chalk_1.default.blue.underline(code.verification_uri));
|
|
85
|
+
console.log(chalk_1.default.gray(' and enter code: ') + chalk_1.default.bold(code.user_code));
|
|
84
86
|
console.log('');
|
|
85
87
|
console.log(chalk_1.default.gray('Waiting for approval in your browser...'));
|
|
86
88
|
let token;
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
/**
|
|
3
|
-
* solidactions
|
|
3
|
+
* solidactions doc pull <folder> [dest]
|
|
4
4
|
*
|
|
5
5
|
* Downloads a Docs folder tree from SA-Docs into a local markdown tree (the
|
|
6
|
-
* inverse of `
|
|
6
|
+
* inverse of `doc push`): BFS-walks the folder via `docs_vault list`,
|
|
7
7
|
* bulk-fetches doc bodies via `docs_vault bulk_read`, and writes each doc as
|
|
8
8
|
* <dest>/<relative-folder>/<sanitized-title>.md plus a revision manifest
|
|
9
9
|
* (<dest>/.solidactions-docs.json) recording id/title/current_revision_id
|
|
@@ -22,8 +22,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
22
22
|
exports.sha256Hex = exports.DOCS_MANIFEST = void 0;
|
|
23
23
|
exports.sanitizeSegment = sanitizeSegment;
|
|
24
24
|
exports.sanitizeTitle = sanitizeTitle;
|
|
25
|
-
exports.
|
|
26
|
-
exports.
|
|
25
|
+
exports.docPullWithConfig = docPullWithConfig;
|
|
26
|
+
exports.docPull = docPull;
|
|
27
27
|
const fs_1 = __importDefault(require("fs"));
|
|
28
28
|
const path_1 = __importDefault(require("path"));
|
|
29
29
|
const axios_1 = __importDefault(require("axios"));
|
|
@@ -335,7 +335,7 @@ function commitDocs(destination, planned) {
|
|
|
335
335
|
* Core implementation — accepts an injected config so tests can point at a
|
|
336
336
|
* stub server without touching the filesystem config.
|
|
337
337
|
*/
|
|
338
|
-
async function
|
|
338
|
+
async function docPullWithConfig(folderPath, dest, options, config) {
|
|
339
339
|
const destInput = dest ?? `./${lastSegment(folderPath)}`;
|
|
340
340
|
const destination = path_1.default.resolve(destInput);
|
|
341
341
|
// Captured once, before the walk, so deletion propagation (below) can diff
|
|
@@ -491,7 +491,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
|
|
|
491
491
|
continue;
|
|
492
492
|
const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
|
|
493
493
|
// Containment: a hand-edited or corrupt manifest key such as "../../etc/passwd"
|
|
494
|
-
// would otherwise resolve outside the pull destination. `
|
|
494
|
+
// would otherwise resolve outside the pull destination. `doc pull` never writes
|
|
495
495
|
// such a key (titles are sanitized), but this loop is the only code in the CLI
|
|
496
496
|
// that deletes files — never let it act on a path it did not create.
|
|
497
497
|
if (!absPath.startsWith(destPrefix))
|
|
@@ -553,10 +553,10 @@ async function report(destination, folderPath, fetched, options, config, extraWa
|
|
|
553
553
|
for (const file of keptModified) {
|
|
554
554
|
process.stderr.write(chalk_1.default.yellow(`! kept ${file} — deleted remotely but modified locally\n`));
|
|
555
555
|
if (keptModifiedMedia.has(file)) {
|
|
556
|
-
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; use `solidactions
|
|
556
|
+
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; use `solidactions doc upload` to re-create it)\n'));
|
|
557
557
|
}
|
|
558
558
|
else {
|
|
559
|
-
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; `
|
|
559
|
+
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; `doc push` will re-create it)\n'));
|
|
560
560
|
}
|
|
561
561
|
}
|
|
562
562
|
process.exit(0);
|
|
@@ -564,7 +564,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
|
|
|
564
564
|
/**
|
|
565
565
|
* Entry point called from index.ts.
|
|
566
566
|
*/
|
|
567
|
-
async function
|
|
567
|
+
async function docPull(folder, dest, options) {
|
|
568
568
|
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
569
|
-
await
|
|
569
|
+
await docPullWithConfig(folder, dest, options, config);
|
|
570
570
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
/**
|
|
3
|
-
* solidactions
|
|
3
|
+
* solidactions doc push <dir>
|
|
4
4
|
*
|
|
5
5
|
* Recursively uploads a local markdown tree into SA-Docs via the docs MCP
|
|
6
6
|
* server's `docs_vault bulk_create` tool, mirroring folder structure.
|
|
@@ -12,8 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
12
12
|
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
13
13
|
};
|
|
14
14
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
|
-
exports.
|
|
16
|
-
exports.
|
|
15
|
+
exports.docPushWithConfig = docPushWithConfig;
|
|
16
|
+
exports.docPush = docPush;
|
|
17
17
|
const fs_1 = __importDefault(require("fs"));
|
|
18
18
|
const path_1 = __importDefault(require("path"));
|
|
19
19
|
const axios_1 = __importDefault(require("axios"));
|
|
@@ -23,6 +23,16 @@ const api_1 = require("../utils/api");
|
|
|
23
23
|
const mcp_1 = require("../utils/mcp");
|
|
24
24
|
const docs_manifest_1 = require("../utils/docs-manifest");
|
|
25
25
|
const CHUNK_SIZE = 50;
|
|
26
|
+
const SKIP_DIRS = new Set(['node_modules']);
|
|
27
|
+
/**
|
|
28
|
+
* Directory/dot entries neither walker descends into or picks up: dotfiles and
|
|
29
|
+
* dot-directories (also covers the `.solidactions-docs.json` sidecar itself) and
|
|
30
|
+
* `node_modules/`. Shared so the markdown and binary walkers stay in lockstep —
|
|
31
|
+
* an untracked `.md` under `node_modules/` or a dot-directory must not be pushed.
|
|
32
|
+
*/
|
|
33
|
+
function isSkippedEntry(name) {
|
|
34
|
+
return name.startsWith('.') || SKIP_DIRS.has(name);
|
|
35
|
+
}
|
|
26
36
|
/**
|
|
27
37
|
* Recursively walk `dir` and collect all *.md files.
|
|
28
38
|
* Returns a list of absolute paths.
|
|
@@ -31,6 +41,8 @@ function walkMarkdownFiles(dir) {
|
|
|
31
41
|
const results = [];
|
|
32
42
|
const walk = (current) => {
|
|
33
43
|
for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
|
|
44
|
+
if (isSkippedEntry(entry.name))
|
|
45
|
+
continue;
|
|
34
46
|
const abs = path_1.default.join(current, entry.name);
|
|
35
47
|
if (entry.isDirectory()) {
|
|
36
48
|
walk(abs);
|
|
@@ -43,10 +55,9 @@ function walkMarkdownFiles(dir) {
|
|
|
43
55
|
walk(dir);
|
|
44
56
|
return results;
|
|
45
57
|
}
|
|
46
|
-
const SKIP_DIRS = new Set(['node_modules']);
|
|
47
58
|
/**
|
|
48
59
|
* Recursively walk `dir` and collect relative paths of non-.md files that
|
|
49
|
-
* are not present in the manifest — never uploaded by `
|
|
60
|
+
* are not present in the manifest — never uploaded by `doc push`; `doc
|
|
50
61
|
* upload` is the way to create media docs from these. Dotfiles and
|
|
51
62
|
* dot-directories are excluded (`entry.name.startsWith('.')` also covers the
|
|
52
63
|
* `.solidactions-docs.json` sidecar itself).
|
|
@@ -55,7 +66,7 @@ function walkUntrackedBinaries(dir, manifest) {
|
|
|
55
66
|
const results = [];
|
|
56
67
|
const walk = (current) => {
|
|
57
68
|
for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
|
|
58
|
-
if (
|
|
69
|
+
if (isSkippedEntry(entry.name))
|
|
59
70
|
continue;
|
|
60
71
|
const abs = path_1.default.join(current, entry.name);
|
|
61
72
|
if (entry.isDirectory()) {
|
|
@@ -139,7 +150,7 @@ function formatSummaryLine(summary, dryRun) {
|
|
|
139
150
|
* Core implementation — accepts an injected config so tests can point at a
|
|
140
151
|
* stub server without touching the filesystem config.
|
|
141
152
|
*/
|
|
142
|
-
async function
|
|
153
|
+
async function docPushWithConfig(dir, options, config) {
|
|
143
154
|
const absDir = path_1.default.resolve(dir);
|
|
144
155
|
if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
|
|
145
156
|
process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
|
|
@@ -410,7 +421,7 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
410
421
|
}
|
|
411
422
|
if (untrackedMedia.length > 0) {
|
|
412
423
|
for (const file of untrackedMedia.slice(0, 10)) {
|
|
413
|
-
process.stderr.write(chalk_1.default.yellow(`${file}: not pushed — use \`solidactions
|
|
424
|
+
process.stderr.write(chalk_1.default.yellow(`${file}: not pushed — use \`solidactions doc upload\`\n`));
|
|
414
425
|
}
|
|
415
426
|
if (untrackedMedia.length > 10) {
|
|
416
427
|
process.stderr.write(chalk_1.default.yellow(`… and ${untrackedMedia.length - 10} more\n`));
|
|
@@ -457,7 +468,7 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
457
468
|
/**
|
|
458
469
|
* Entry point called from index.ts.
|
|
459
470
|
*/
|
|
460
|
-
async function
|
|
471
|
+
async function docPush(dir, options) {
|
|
461
472
|
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
462
|
-
await
|
|
473
|
+
await docPushWithConfig(dir, options, config);
|
|
463
474
|
}
|
|
@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
36
36
|
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
37
37
|
};
|
|
38
38
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
|
-
exports.
|
|
39
|
+
exports.docUpload = docUpload;
|
|
40
40
|
const fs = __importStar(require("fs"));
|
|
41
41
|
const path = __importStar(require("path"));
|
|
42
42
|
const axios_1 = __importDefault(require("axios"));
|
|
@@ -47,9 +47,9 @@ const api_1 = require("../utils/api");
|
|
|
47
47
|
* Resolve `--replace` to a doc id. A purely numeric value is an id; anything else
|
|
48
48
|
* is a docs path, resolved against the doc's *title* via GET /docs/by-path.
|
|
49
49
|
*
|
|
50
|
-
* Note the title is not always the local filename: `
|
|
50
|
+
* Note the title is not always the local filename: `doc pull` sanitizes
|
|
51
51
|
* filesystem-illegal characters and may suffix collisions. For path-based work
|
|
52
|
-
* on a pulled folder, `
|
|
52
|
+
* on a pulled folder, `doc push` is the right verb.
|
|
53
53
|
*/
|
|
54
54
|
async function resolveReplaceTarget(config, replace) {
|
|
55
55
|
if (/^\d+$/.test(replace)) {
|
|
@@ -95,7 +95,7 @@ async function resolveReplaceTarget(config, replace) {
|
|
|
95
95
|
* sequentially. `--title` is only valid for a single file — with multiple
|
|
96
96
|
* files, every upload would otherwise silently collide on the same title.
|
|
97
97
|
*/
|
|
98
|
-
async function
|
|
98
|
+
async function docUpload(files, options = {}) {
|
|
99
99
|
if (options.title && files.length > 1) {
|
|
100
100
|
console.error(chalk_1.default.red('--title can only be used when uploading a single file.'));
|
|
101
101
|
process.exit(1);
|
package/dist/commands/login.js
CHANGED
|
@@ -123,7 +123,7 @@ async function selectWorkspaceInteractively(workspaces) {
|
|
|
123
123
|
console.log(chalk_1.default.gray(`Auto-selected workspace: ${workspaces[0].name}`));
|
|
124
124
|
return workspaces[0];
|
|
125
125
|
}
|
|
126
|
-
console.log(chalk_1.default.blue('\nSelect
|
|
126
|
+
console.log(chalk_1.default.blue('\nSelect your default workspace (change anytime with `solidactions workspace set`):\n'));
|
|
127
127
|
workspaces.forEach((ws, i) => {
|
|
128
128
|
console.log(` ${chalk_1.default.white(`${i + 1}.`)} ${ws.name}`);
|
|
129
129
|
});
|
|
@@ -11,7 +11,7 @@ exports.skillExec = skillExec;
|
|
|
11
11
|
*
|
|
12
12
|
* ALWAYS executes the server-stored skill (the artifact) — never local edits;
|
|
13
13
|
* that's `skill dev <dir>`. --target picks WHERE the stored skill executes:
|
|
14
|
-
* sandbox — the server-managed sandbox via crews MCP
|
|
14
|
+
* sandbox — the server-managed sandbox via crews MCP sandbox_exec (v1.30 behavior)
|
|
15
15
|
* host — this machine, from a transparent revision-checked cache under
|
|
16
16
|
* ~/.solidactions/cache/skills/ (no visible pull step)
|
|
17
17
|
* --target is REQUIRED (no default): a half-remembered command errors instead
|
|
@@ -78,8 +78,8 @@ async function execInSandbox(name, commandParts, options, environment, config) {
|
|
|
78
78
|
const isRole = Boolean(options.role);
|
|
79
79
|
const tool = isRole ? 'roles' : 'skills';
|
|
80
80
|
const args = isRole
|
|
81
|
-
? { action: '
|
|
82
|
-
: { action: '
|
|
81
|
+
? { action: 'sandbox_exec', role: options.role, name, command }
|
|
82
|
+
: { action: 'sandbox_exec', identifier: name, command };
|
|
83
83
|
if (options.environment)
|
|
84
84
|
args.environment = options.environment;
|
|
85
85
|
if (isRole && options.inCrew)
|
|
@@ -12,11 +12,11 @@ exports.skillRun = skillRun;
|
|
|
12
12
|
/**
|
|
13
13
|
* solidactions skill dev <dir> [--crew <c>] [--environment <env>] [--env-file <f>] -- <command...>
|
|
14
14
|
*
|
|
15
|
-
* Local analogue of the crews MCP
|
|
15
|
+
* Local analogue of the crews MCP sandbox_exec: runs <command> with cwd=<dir>
|
|
16
16
|
* (matching the sandbox's cwd=/work/skills/<slug>), with crew variables
|
|
17
17
|
* fetched at runtime from /api/v1/crews/{id}/variables/resolve. Secrets are
|
|
18
18
|
* included only when the API key holds env:reveal; skipped names are printed.
|
|
19
|
-
* DELIBERATE DIVERGENCE from remote
|
|
19
|
+
* DELIBERATE DIVERGENCE from remote sandbox_exec: default environment is `dev`
|
|
20
20
|
* (this is a dev tool); remote defaults to production. Always prints the env.
|
|
21
21
|
*/
|
|
22
22
|
const fs_1 = __importDefault(require("fs"));
|
package/dist/index.js
CHANGED
|
@@ -77,9 +77,9 @@ const skill_delete_1 = require("./commands/skill-delete");
|
|
|
77
77
|
const skill_dev_1 = require("./commands/skill-dev");
|
|
78
78
|
const skill_exec_1 = require("./commands/skill-exec");
|
|
79
79
|
const role_push_1 = require("./commands/role-push");
|
|
80
|
-
const
|
|
81
|
-
const
|
|
82
|
-
const
|
|
80
|
+
const doc_push_1 = require("./commands/doc-push");
|
|
81
|
+
const doc_pull_1 = require("./commands/doc-pull");
|
|
82
|
+
const doc_upload_1 = require("./commands/doc-upload");
|
|
83
83
|
const crew_env_set_1 = require("./commands/crew-env-set");
|
|
84
84
|
const crew_env_list_1 = require("./commands/crew-env-list");
|
|
85
85
|
const crew_env_delete_1 = require("./commands/crew-env-delete");
|
|
@@ -657,10 +657,10 @@ role
|
|
|
657
657
|
await (0, role_push_1.rolePush)(dir, options);
|
|
658
658
|
});
|
|
659
659
|
// =============================================================================
|
|
660
|
-
//
|
|
660
|
+
// doc <subcommand> (SA-Docs surface)
|
|
661
661
|
// =============================================================================
|
|
662
|
-
const
|
|
663
|
-
|
|
662
|
+
const doc = program.command('doc').description('Manage docs in SA-Docs');
|
|
663
|
+
doc
|
|
664
664
|
.command('push')
|
|
665
665
|
.description('Recursively upload a local markdown tree into SA-Docs')
|
|
666
666
|
.argument('<dir>', 'Path to the directory containing markdown files')
|
|
@@ -668,12 +668,12 @@ docs
|
|
|
668
668
|
.option('--type <slug>', 'Doc-type slug to apply to all uploaded docs')
|
|
669
669
|
.option('--folder <base>', 'Nest the whole upload under this base folder path in SA-Docs')
|
|
670
670
|
.option('--dry-run', 'Preview what would be created without writing')
|
|
671
|
-
.option('--force', 'Overwrite tracked docs (from a prior
|
|
671
|
+
.option('--force', 'Overwrite tracked docs (from a prior doc pull) without a base-revision drift guard')
|
|
672
672
|
.option('--json', 'Output result as JSON')
|
|
673
673
|
.action(async (dir, options) => {
|
|
674
|
-
await (0,
|
|
674
|
+
await (0, doc_push_1.docPush)(dir, { onConflict: options.onConflict, type: options.type, folder: options.folder, dryRun: options.dryRun, force: options.force, json: options.json });
|
|
675
675
|
});
|
|
676
|
-
|
|
676
|
+
doc
|
|
677
677
|
.command('pull')
|
|
678
678
|
.description('Download a Docs folder tree to a local directory for editing (inverse of push)')
|
|
679
679
|
.argument('<folder>', 'Docs folder path (or a single doc path)')
|
|
@@ -682,16 +682,16 @@ docs
|
|
|
682
682
|
.option('--overwrite', 'DESTRUCTIVE: discard unpushed local changes (tracked files whose content no longer matches the last pull) and overwrite them; implies --yes')
|
|
683
683
|
.option('--json', 'Machine-readable output')
|
|
684
684
|
.action(async (folder, dest, options) => {
|
|
685
|
-
await (0,
|
|
685
|
+
await (0, doc_pull_1.docPull)(folder, dest, options);
|
|
686
686
|
});
|
|
687
|
-
|
|
687
|
+
doc
|
|
688
688
|
.command('upload <files...>')
|
|
689
689
|
.description('Upload one or more media files to SA-Docs (requires a token with the "docs" ability)')
|
|
690
690
|
.option('--folder <path>', 'Folder path to upload into (auto-created if missing)')
|
|
691
691
|
.option('--title <title>', 'Title for the uploaded doc (only valid with a single file)')
|
|
692
692
|
.option('--replace <doc-id-or-path>', 'replace the bytes of an existing media doc (by id, or by docs path)')
|
|
693
693
|
.action(async (files, options) => {
|
|
694
|
-
await (0,
|
|
694
|
+
await (0, doc_upload_1.docUpload)(files, { folder: options.folder, title: options.title, replace: options.replace });
|
|
695
695
|
});
|
|
696
696
|
program.parseAsync().catch((err) => {
|
|
697
697
|
console.error(chalk_1.default.red(err.message ?? String(err)));
|
package/dist/utils/api.js
CHANGED
|
@@ -199,7 +199,7 @@ async function ensureWorkspaceSelected(config) {
|
|
|
199
199
|
console.log(chalk_1.default.gray(`Auto-selected workspace: ${selected.name}`));
|
|
200
200
|
}
|
|
201
201
|
else {
|
|
202
|
-
console.log(chalk_1.default.blue('\nSelect
|
|
202
|
+
console.log(chalk_1.default.blue('\nSelect your default workspace (change anytime with `solidactions workspace set`):\n'));
|
|
203
203
|
workspaces.forEach((ws, i) => {
|
|
204
204
|
console.log(` ${chalk_1.default.white(`${i + 1}.`)} ${ws.name} ${chalk_1.default.gray(`(${ws.org_name}, ${ws.role})`)}`);
|
|
205
205
|
});
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
/**
|
|
3
|
-
* Sidecar manifest (`.solidactions-docs.json`) shared by `
|
|
4
|
-
* `
|
|
3
|
+
* Sidecar manifest (`.solidactions-docs.json`) shared by `doc pull` and
|
|
4
|
+
* `doc push` to track which local files correspond to which SA-Docs docs,
|
|
5
5
|
* and to detect local/server drift via a body sha256.
|
|
6
6
|
*/
|
|
7
7
|
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
@@ -25,8 +25,8 @@ function sha256Hex(data) {
|
|
|
25
25
|
* Read `<dir>/.solidactions-docs.json`. Absent or unparseable → null,
|
|
26
26
|
* meaning nothing under `dir` is guarded (sidecar convention).
|
|
27
27
|
*
|
|
28
|
-
* `
|
|
29
|
-
* re-create every doc); `
|
|
28
|
+
* `doc push` warns on unparseable JSON (files silently becoming untracked would
|
|
29
|
+
* re-create every doc); `doc pull` stays silent (it is about to rewrite it anyway).
|
|
30
30
|
*/
|
|
31
31
|
function readManifest(dir, opts = {}) {
|
|
32
32
|
const manifestPath = path_1.default.join(dir, exports.DOCS_MANIFEST);
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.sdkRefFromRange = sdkRefFromRange;
|
|
7
|
+
exports.sdkDocsRef = sdkDocsRef;
|
|
8
|
+
const fs_1 = __importDefault(require("fs"));
|
|
9
|
+
const path_1 = __importDefault(require("path"));
|
|
10
|
+
const SDK_PACKAGE = '@solidactions/sdk';
|
|
11
|
+
/**
|
|
12
|
+
* Resolve the git ref used when fetching SDK docs from the solidactions-ts-sdk
|
|
13
|
+
* repo, derived from THIS CLI's own `package.json` declaration of
|
|
14
|
+
* `@solidactions/sdk`.
|
|
15
|
+
*
|
|
16
|
+
* `ai init` used to fetch `docs/sdk-reference.md` from that repo's default
|
|
17
|
+
* branch, so a freshly-scaffolded project got whatever happened to be on SDK
|
|
18
|
+
* `main` — documenting APIs the SDK version this CLI is built against doesn't
|
|
19
|
+
* ship yet. Deriving the ref from our own declared dependency means a future
|
|
20
|
+
* dependency bump moves the docs ref with it; there is no second constant to
|
|
21
|
+
* forget to update.
|
|
22
|
+
*
|
|
23
|
+
* Note this tracks the CLI's own declaration, NOT the SDK version in whatever
|
|
24
|
+
* project `ai init` is run against. Serving docs matched to the target
|
|
25
|
+
* project's installed SDK is a separate concern, tracked separately.
|
|
26
|
+
*
|
|
27
|
+
* The declared range's minimum is used (`^0.7.3` → `v0.7.3`), matching the
|
|
28
|
+
* `vX.Y.Z` tag format the SDK repo publishes.
|
|
29
|
+
*/
|
|
30
|
+
/**
|
|
31
|
+
* Convert a declared semver range into the SDK repo's `vX.Y.Z` tag format,
|
|
32
|
+
* using the range's minimum version (`^0.7.3` → `v0.7.3`).
|
|
33
|
+
*
|
|
34
|
+
* Exported so the conversion — including its rejection of ranges with no
|
|
35
|
+
* explicit minimum — is testable without touching the filesystem.
|
|
36
|
+
*/
|
|
37
|
+
function sdkRefFromRange(declared) {
|
|
38
|
+
// Strip a leading range operator (^, ~, >=, v) to get the minimum version.
|
|
39
|
+
const version = declared.replace(/^[\^~>=<\sv]*/, '');
|
|
40
|
+
if (!/^\d+\.\d+\.\d+/.test(version)) {
|
|
41
|
+
throw new Error(`Cannot derive an SDK docs tag from ${SDK_PACKAGE} range "${declared}" — expected a range with an explicit minimum version (e.g. "^0.7.3").`);
|
|
42
|
+
}
|
|
43
|
+
return `v${version}`;
|
|
44
|
+
}
|
|
45
|
+
function sdkDocsRef() {
|
|
46
|
+
// `__dirname` is <pkg>/src/utils under vitest and <pkg>/dist/utils once
|
|
47
|
+
// built, so `../..` is the package root in both cases — and in a published
|
|
48
|
+
// install, since npm always ships package.json alongside `dist`.
|
|
49
|
+
const packageJsonPath = path_1.default.join(__dirname, '..', '..', 'package.json');
|
|
50
|
+
let declared;
|
|
51
|
+
try {
|
|
52
|
+
const pkg = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf8'));
|
|
53
|
+
declared = pkg.dependencies?.[SDK_PACKAGE] ?? pkg.devDependencies?.[SDK_PACKAGE];
|
|
54
|
+
}
|
|
55
|
+
catch (error) {
|
|
56
|
+
throw new Error(`Could not read ${packageJsonPath} to determine the SDK docs version: ${error.message}`);
|
|
57
|
+
}
|
|
58
|
+
if (!declared) {
|
|
59
|
+
throw new Error(`No ${SDK_PACKAGE} dependency declared in ${packageJsonPath} — cannot determine which SDK docs version to fetch.`);
|
|
60
|
+
}
|
|
61
|
+
return sdkRefFromRange(declared);
|
|
62
|
+
}
|