@scarn/cli 0.0.0-stage → 0.0.0

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 CHANGED
@@ -1,3 +1,28 @@
1
- # Temporary Holding Version
1
+ # @scarn/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Scarn runs AI agents over your backlog, on your machines. This CLI links your
4
+ repo, designs pipelines with an agent, and runs the workers that execute them.
5
+
6
+ ## Install
7
+
8
+ ```sh
9
+ npm i -g @scarn/cli
10
+ ```
11
+
12
+ ## Use
13
+
14
+ ```sh
15
+ scarn init # sign in and link this repo to a Scarn project
16
+ scarn pipelines design # pick a work item; an agent interviews you and writes the pipeline
17
+ scarn work # run a worker that executes your pipeline's steps
18
+ ```
19
+
20
+ The designer connects to an AI provider once, the first time it starts. The
21
+ Quickstart says
22
+ [which option to pick for your tool](https://scarn-io.github.io/scarn/getting-started/quickstart/#connect-your-ai-tool).
23
+
24
+ ## Docs
25
+
26
+ - [Quickstart](https://scarn-io.github.io/scarn/getting-started/quickstart/) — ten minutes to a running pipeline.
27
+ - [CLI reference](https://scarn-io.github.io/scarn/reference/cli/) — every command and flag.
28
+ - [Observability](https://scarn-io.github.io/scarn/reference/observability/) — what the CLI reports and how to opt out.
@@ -0,0 +1,249 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Runs as @scarn/cli's own "postinstall" lifecycle script (see
5
+ * script/publish.ts's prepareMainPackage, which wires this up and copies this
6
+ * file into the published package verbatim — like bin/scarn, this is plain
7
+ * CommonJS, not compiled, so it can't import script/targets.ts at runtime).
8
+ *
9
+ * Why this exists: the platform binary (@scarn/cli-<platform>-<arch>) is an
10
+ * npm optionalDependency of the main package (see targets.ts / publish.ts's
11
+ * module doc for why). optionalDependencies are, by design, allowed to fail
12
+ * npm's install without failing the overall `npm install` command — that's
13
+ * the whole point of the "optional" in the name. That's fine for a package
14
+ * providing a nice-to-have; it is NOT fine here, because the platform binary
15
+ * is the entire CLI. A single dropped connection fetching that ~90MB package
16
+ * (far more likely on a fresh CI runner or a flaky network than a checksum
17
+ * mismatch) used to leave `npm install -g @scarn/cli` reporting success —
18
+ * exit code 0 — with a broken install, and the user finding out only when
19
+ * they ran `scarn` and hit bin/scarn's "Missing compiled binary" error,
20
+ * possibly minutes or commits later.
21
+ *
22
+ * This script closes that gap: it verifies the platform package actually
23
+ * resolves right after install, and if it doesn't, downloads the tarball
24
+ * directly from the registry (bypassing npm — no child `npm install`, so this
25
+ * can't recurse into another lifecycle run) and extracts just the compiled
26
+ * binary into dist/, the same monolithic-layout path bin/scarn already
27
+ * falls back to. If that recovery also fails (registry unreachable, disk
28
+ * full, etc.) this script exits non-zero, which — unlike a skipped
29
+ * optionalDependency — DOES fail `npm install`, immediately and loudly,
30
+ * instead of deferring the failure to first run.
31
+ *
32
+ * Skipped entirely (exit 0, no network call) when SCARN_DIST_DIR is set
33
+ * (dev build) or the platform/arch has no compiled target at all (unsupported
34
+ * platform — bin/scarn already reports that clearly when actually run).
35
+ */
36
+
37
+ const { mkdirSync, renameSync, writeFileSync, chmodSync } = require("node:fs");
38
+ const { resolve } = require("node:path");
39
+ const { gunzipSync } = require("node:zlib");
40
+ const http = require("node:http");
41
+ const https = require("node:https");
42
+
43
+ const cliName = "scarn";
44
+ const projectRoot = resolve(__dirname, "..");
45
+ const distDirectory = resolve(projectRoot, "dist");
46
+
47
+ // Keep in sync with apps/cli/script/targets.ts (CLI_BUILD_TARGETS) and
48
+ // bin/scarn's own copies of these two maps.
49
+ const binaryNames = {
50
+ "darwin:arm64": `${cliName}-darwin-arm64`,
51
+ "darwin:x64": `${cliName}-darwin-x64`,
52
+ "linux:arm64": `${cliName}-linux-arm64`,
53
+ "linux:x64": `${cliName}-linux-x64`,
54
+ "win32:x64": `${cliName}-windows-x64.exe`,
55
+ };
56
+ const platformPackageNames = {
57
+ "darwin:arm64": "@scarn/cli-darwin-arm64",
58
+ "darwin:x64": "@scarn/cli-darwin-x64",
59
+ "linux:arm64": "@scarn/cli-linux-arm64",
60
+ "linux:x64": "@scarn/cli-linux-x64",
61
+ "win32:x64": "@scarn/cli-win32-x64",
62
+ };
63
+
64
+ const MAX_DOWNLOAD_ATTEMPTS = 3;
65
+ const DEFAULT_RETRY_DELAY_MS = 1000;
66
+ const RETRY_DELAY_MS = retryDelayMs();
67
+ const REQUEST_TIMEOUT_MS = 60_000;
68
+ const MAX_REDIRECTS = 5;
69
+
70
+ /** Base retry delay; SCARN_POSTINSTALL_RETRY_DELAY_MS overrides it (tests set 0). */
71
+ function retryDelayMs() {
72
+ const raw = process.env["SCARN_POSTINSTALL_RETRY_DELAY_MS"];
73
+ if (raw === undefined || !/^\d+$/.test(raw.trim()))
74
+ return DEFAULT_RETRY_DELAY_MS;
75
+ const parsed = Number(raw.trim());
76
+ return Number.isSafeInteger(parsed) ? parsed : DEFAULT_RETRY_DELAY_MS;
77
+ }
78
+
79
+ function registryBaseUrl() {
80
+ const configured = process.env["npm_config_registry"];
81
+ const raw = configured && configured.length > 0 ? configured : "https://registry.npmjs.org/";
82
+ return raw.endsWith("/") ? raw : `${raw}/`;
83
+ }
84
+
85
+ /**
86
+ * GET `url` and resolve with the full response body as a Buffer. Picks
87
+ * node:http or node:https based on the URL's own scheme (rather than always
88
+ * using https) so this also works against a plain-http private registry
89
+ * mirror, same as npm's own registry client does.
90
+ */
91
+ function get(url, redirectsLeft) {
92
+ const client = new URL(url).protocol === "http:" ? http : https;
93
+ return new Promise((promiseResolve, promiseReject) => {
94
+ const request = client.get(url, { timeout: REQUEST_TIMEOUT_MS }, (response) => {
95
+ const { statusCode = 0, headers } = response;
96
+
97
+ if (statusCode >= 300 && statusCode < 400 && headers.location) {
98
+ response.resume(); // discard body
99
+ if (redirectsLeft <= 0) {
100
+ promiseReject(new Error(`Too many redirects fetching ${url}`));
101
+ return;
102
+ }
103
+ promiseResolve(get(new URL(headers.location, url).toString(), redirectsLeft - 1));
104
+ return;
105
+ }
106
+
107
+ if (statusCode < 200 || statusCode >= 300) {
108
+ response.resume(); // discard body
109
+ promiseReject(new Error(`Unexpected status ${statusCode} fetching ${url}`));
110
+ return;
111
+ }
112
+
113
+ /** @type {Buffer[]} */
114
+ const chunks = [];
115
+ response.on("data", (chunk) => chunks.push(chunk));
116
+ response.on("end", () => promiseResolve(Buffer.concat(chunks)));
117
+ response.on("error", promiseReject);
118
+ });
119
+
120
+ request.on("timeout", () => request.destroy(new Error(`Timed out fetching ${url}`)));
121
+ request.on("error", promiseReject);
122
+ });
123
+ }
124
+
125
+ async function getWithRetry(url) {
126
+ let lastError;
127
+ for (let attempt = 1; attempt <= MAX_DOWNLOAD_ATTEMPTS; attempt += 1) {
128
+ try {
129
+ return await get(url, MAX_REDIRECTS);
130
+ } catch (error) {
131
+ lastError = error;
132
+ if (attempt < MAX_DOWNLOAD_ATTEMPTS) {
133
+ await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * attempt));
134
+ }
135
+ }
136
+ }
137
+ throw lastError;
138
+ }
139
+
140
+ /**
141
+ * Extract a single file's contents from an uncompressed USTAR/GNU tar
142
+ * archive. Good enough here because the platform packages this fetches are
143
+ * two files (package.json + the one binary) with short (<100 byte) names —
144
+ * no pax/long-name extension headers to worry about — and pulling in a tar
145
+ * library just for this one-file rescue path isn't worth the extra
146
+ * dependency in a script that has to work with zero installed deps.
147
+ */
148
+ function extractTarEntry(tarBuffer, entryName) {
149
+ let offset = 0;
150
+ while (offset + 512 <= tarBuffer.length) {
151
+ const header = tarBuffer.subarray(offset, offset + 512);
152
+ if (header.every((byte) => byte === 0)) break; // end-of-archive marker
153
+
154
+ const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/su, "");
155
+ const sizeField = header.subarray(124, 136).toString("utf8").replace(/\0.*$/su, "").trim();
156
+ const size = Number.parseInt(sizeField, 8) || 0;
157
+ const dataStart = offset + 512;
158
+
159
+ if (name === entryName) {
160
+ return tarBuffer.subarray(dataStart, dataStart + size);
161
+ }
162
+
163
+ offset = dataStart + Math.ceil(size / 512) * 512;
164
+ }
165
+ return undefined;
166
+ }
167
+
168
+ /**
169
+ * Fetch `packageName@version`'s tarball directly from the registry and pull
170
+ * just `bin/<binaryName>` out of it, writing the result to
171
+ * `distDirectory/<binaryName>` — the same path bin/scarn's monolithic-dist
172
+ * fallback layout already checks, so no change to bin/scarn is needed to
173
+ * pick this up.
174
+ */
175
+ async function downloadPlatformBinary(packageName, binaryName, version) {
176
+ const metadataUrl = `${registryBaseUrl()}${packageName}/${version}`;
177
+ const metadataJson = await getWithRetry(metadataUrl);
178
+ const metadata = JSON.parse(metadataJson.toString("utf8"));
179
+ const tarballUrl = metadata?.dist?.tarball;
180
+
181
+ if (typeof tarballUrl !== "string" || tarballUrl.length === 0) {
182
+ throw new Error(`Registry response for ${packageName}@${version} had no dist.tarball`);
183
+ }
184
+
185
+ const tarballGz = await getWithRetry(tarballUrl);
186
+ const tarBuffer = gunzipSync(tarballGz);
187
+ const binaryContents = extractTarEntry(tarBuffer, `package/bin/${binaryName}`);
188
+
189
+ if (binaryContents === undefined) {
190
+ throw new Error(`package/bin/${binaryName} not found in ${tarballUrl}`);
191
+ }
192
+
193
+ mkdirSync(distDirectory, { recursive: true });
194
+ // Write-then-rename so a process interrupted mid-write can never leave a
195
+ // truncated binary at the final path — the one failure mode this whole
196
+ // script exists to close off.
197
+ const finalPath = resolve(distDirectory, binaryName);
198
+ const tempPath = `${finalPath}.download-${String(process.pid)}`;
199
+ writeFileSync(tempPath, binaryContents);
200
+ chmodSync(tempPath, 0o755);
201
+ renameSync(tempPath, finalPath);
202
+ return finalPath;
203
+ }
204
+
205
+ async function main() {
206
+ if (process.env["SCARN_DIST_DIR"]) {
207
+ return; // Dev build / explicit override — nothing to verify.
208
+ }
209
+
210
+ const platform = process.env["SCARN_PLATFORM"] ?? process.platform;
211
+ const arch = process.env["SCARN_ARCH"] ?? process.arch;
212
+ const targetKey = `${platform}:${arch}`;
213
+ const binaryName = binaryNames[targetKey];
214
+ const packageName = platformPackageNames[targetKey];
215
+
216
+ if (binaryName === undefined || packageName === undefined) {
217
+ return; // Unsupported platform — bin/scarn reports this clearly at run time.
218
+ }
219
+
220
+ try {
221
+ require.resolve(`${packageName}/bin/${binaryName}`);
222
+ return; // Optional platform dependency installed cleanly — nothing to do.
223
+ } catch {
224
+ // Fall through to the rescue download below.
225
+ }
226
+
227
+ process.stdout.write(
228
+ `@scarn/cli: optional dependency ${packageName} did not install (this can happen after ` +
229
+ "a network blip); downloading its binary directly as a fallback...\n",
230
+ );
231
+
232
+ const version = require("../package.json").version;
233
+
234
+ try {
235
+ await downloadPlatformBinary(packageName, binaryName, version);
236
+ process.stdout.write(`@scarn/cli: recovered — ${binaryName} downloaded successfully.\n`);
237
+ } catch (error) {
238
+ const message = error instanceof Error ? error.message : String(error);
239
+ process.stderr.write(
240
+ `@scarn/cli: failed to install the ${platform}/${arch} binary (${packageName}), and ` +
241
+ `the fallback download also failed: ${message}\n` +
242
+ "Try again — e.g. `npm install -g @scarn/cli --force` — once you have a stable " +
243
+ "network connection.\n",
244
+ );
245
+ process.exitCode = 1;
246
+ }
247
+ }
248
+
249
+ void main();
package/bin/scarn ADDED
@@ -0,0 +1,163 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { spawnSync } = require("node:child_process");
4
+ const { existsSync, readFileSync } = require("node:fs");
5
+ const { resolve } = require("node:path");
6
+ const pino = require("pino");
7
+ const PinoPretty = require("pino-pretty");
8
+
9
+ const cliName = "scarn";
10
+ const projectRoot = resolve(__dirname, "..");
11
+ const distDirectory = process.env.SCARN_DIST_DIR ?? resolve(projectRoot, "dist");
12
+ const platform = process.env.SCARN_PLATFORM ?? process.platform;
13
+ const arch = process.env.SCARN_ARCH ?? process.arch;
14
+ const transport = process.stdout.isTTY
15
+ ? PinoPretty({
16
+ colorize: true,
17
+ translateTime: "SYS:standard",
18
+ destination: 1,
19
+ ignore: "pid,hostname",
20
+ })
21
+ : undefined;
22
+ const logger = pino(
23
+ {
24
+ name: "@scarn/cli-wrapper",
25
+ level: process.env.SCARN_LOG_LEVEL ?? "info",
26
+ scope: "wrapper",
27
+ },
28
+ transport,
29
+ );
30
+
31
+ // Keep in sync with apps/cli/script/targets.ts (CLI_BUILD_TARGETS) and this
32
+ // package's bin/postinstall.js — see the doc comment in targets.ts. This
33
+ // file is plain CommonJS (not compiled), so it can't import that module at
34
+ // runtime.
35
+ const binaryNames = {
36
+ "darwin:arm64": `${cliName}-darwin-arm64`,
37
+ "darwin:x64": `${cliName}-darwin-x64`,
38
+ "linux:arm64": `${cliName}-linux-arm64`,
39
+ "linux:x64": `${cliName}-linux-x64`,
40
+ "win32:x64": `${cliName}-windows-x64.exe`,
41
+ };
42
+
43
+ // The published @scarn/cli package ships no binaries itself — each
44
+ // platform's binary lives in its own optionalDependency package, installed
45
+ // by npm only when it matches the current machine (see script/publish.ts).
46
+ // This keeps a normal `npm install -g @scarn/cli` from downloading and
47
+ // extracting all 5 platforms' binaries (~170MB combined) every time, which
48
+ // made large-package extraction interruptions (network blips, disk
49
+ // pressure, concurrent installs) far more likely to leave a corrupted,
50
+ // partially-extracted install behind.
51
+ const platformPackageNames = {
52
+ "darwin:arm64": "@scarn/cli-darwin-arm64",
53
+ "darwin:x64": "@scarn/cli-darwin-x64",
54
+ "linux:arm64": "@scarn/cli-linux-arm64",
55
+ "linux:x64": "@scarn/cli-linux-x64",
56
+ "win32:x64": "@scarn/cli-win32-x64",
57
+ };
58
+
59
+ const reinstallHint =
60
+ "Try reinstalling: `npm install -g @scarn/cli --force` " +
61
+ "(or `npm cache clean --force && npm install -g @scarn/cli`).";
62
+
63
+ function fail(message) {
64
+ logger.error({ message }, "CLI wrapper failed");
65
+ process.exit(1);
66
+ }
67
+
68
+ const targetKey = `${platform}:${arch}`;
69
+ const binaryName = binaryNames[targetKey];
70
+
71
+ if (binaryName === undefined) {
72
+ fail(`Unsupported platform or architecture: ${platform}/${arch}.`);
73
+ }
74
+
75
+ const distOverride = process.env.SCARN_DIST_DIR;
76
+
77
+ // Resolve the compiled binary. Two supported layouts:
78
+ // 1. Dev build / explicit override (SCARN_DIST_DIR, or a local
79
+ // `bun run build`): a single dist/ next to this file holding every
80
+ // platform's binary. bin/postinstall.js's rescue download (see its
81
+ // module doc) also lands here, so a repaired install resolves through
82
+ // this same branch.
83
+ // 2. Published npm install: this package carries no binaries; the current
84
+ // platform's binary comes from its optionalDependency package. Falls
85
+ // back to the monolithic dist/ layout if that package isn't resolvable
86
+ // (npm failed to install it — e.g. a dropped connection — and
87
+ // bin/postinstall.js's rescue download either hasn't run yet or itself
88
+ // failed; see reinstallHint below).
89
+ function resolveBinaryPath() {
90
+ if (distOverride) {
91
+ return resolve(distOverride, binaryName);
92
+ }
93
+ const packageName = platformPackageNames[targetKey];
94
+ if (packageName !== undefined) {
95
+ try {
96
+ return require.resolve(`${packageName}/bin/${binaryName}`);
97
+ } catch {
98
+ // Fall through — see layout 1 above.
99
+ }
100
+ }
101
+ return resolve(distDirectory, binaryName);
102
+ }
103
+
104
+ const binaryPath = resolveBinaryPath();
105
+ const devFilePath = resolve(distDirectory, ".dev");
106
+ const isDevBuild = existsSync(devFilePath);
107
+ const devSdkArtifactPath = isDevBuild ? readFileSync(devFilePath, "utf8").trim() : "";
108
+
109
+ if (!existsSync(binaryPath)) {
110
+ fail(
111
+ `Missing compiled binary for ${platform}/${arch} (looked for ${binaryPath}). ` +
112
+ `Your ${cliName} install looks incomplete or corrupted. ${reinstallHint}`,
113
+ );
114
+ }
115
+
116
+ // Resolve *and verify* the devcontainer CLI bundle up front. This bundle
117
+ // always lives alongside this shim (dist/devcontainer/..., not split per
118
+ // platform, since it's plain cross-platform JS) regardless of which layout
119
+ // the binary above came from. Checking existence here — rather than trusting
120
+ // the path and letting a missing file surface deep inside a worker run —
121
+ // turns a corrupted/partial install into an immediate, actionable error
122
+ // instead of a cryptic "devcontainer CLI exited with a non-zero exit code"
123
+ // several seconds into a `scarn work` session (the CLI bundle's own
124
+ // structured JSON error format never gets a chance to run if the file is
125
+ // missing, so the worker's error parser has nothing to extract a summary
126
+ // from — see extractDevcontainerErrorSummary's fallback string).
127
+ const devcontainerScriptOverride = process.env["SCARN_DEVCONTAINER_SCRIPT"];
128
+ const devcontainerScriptPath =
129
+ devcontainerScriptOverride ??
130
+ resolve(distDirectory, "devcontainer", "dist", "spec-node", "devcontainers-cli.js");
131
+
132
+ if (!devcontainerScriptOverride && !existsSync(devcontainerScriptPath)) {
133
+ fail(
134
+ `Missing devcontainer CLI bundle (looked for ${devcontainerScriptPath}). ` +
135
+ `Your ${cliName} install looks incomplete or corrupted. ${reinstallHint}`,
136
+ );
137
+ }
138
+
139
+ const extraEnv = {
140
+ // Pass the devcontainer CLI bundle path so the worker can invoke it using
141
+ // the compiled binary as the JS runtime (no separate node/bun required).
142
+ // build.ts nests this bundle under dist/devcontainer/dist/spec-node/ so the
143
+ // CLI's extensionPath (join(__dirname, "..", "..")) resolves to
144
+ // dist/devcontainer/, where build.ts also places scripts/updateUID.Dockerfile
145
+ // (used on Linux when remapping the container user's UID/GID).
146
+ SCARN_DEVCONTAINER_SCRIPT: devcontainerScriptPath,
147
+ };
148
+ if (devSdkArtifactPath) extraEnv["SCARN_SDK_ARTIFACT_PATH"] = devSdkArtifactPath;
149
+
150
+ const result = spawnSync(binaryPath, process.argv.slice(2), {
151
+ stdio: "inherit",
152
+ env: { ...process.env, ...extraEnv },
153
+ });
154
+
155
+ if (result.error instanceof Error) {
156
+ fail(result.error.message);
157
+ }
158
+
159
+ if (typeof result.status === "number") {
160
+ process.exit(result.status);
161
+ }
162
+
163
+ process.exit(1);