@dreamlake/ml-dash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ge Yang, Tom Tao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# ml-dash
+
+ML experiment tracking from the command line. Authenticate, inspect projects
+and experiments, and move experiment data to and from an ML-Dash server.
+
+## Install
+
+**macOS / Linux** — one self-contained binary, no Node or Python needed:
+
+```sh
+curl -fsSL https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.sh | sh
+```
+
+**Windows** (PowerShell):
+
+```powershell
+irm https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.ps1 | iex
+```
+
+**With Node ≥ 20.19 already installed:**
+
+```sh
+npm install -g @dreamlake/ml-dash
+```
+
+The command is still `ml-dash`. The package is scoped because the unscoped
+name is not claimable — npm refuses `ml-dash` as too similar to the existing
+`mldash`.
+
+*Not published yet:* the npm channel is built and tested on every release run,
+but no version has reached the registry. Until one does, use the installers
+above. `docs/RELEASE.md` tracks what is outstanding.
+
+Both channels run the same code — the binaries are `src/index.ts` compiled
+ahead of time, the npm package is the same source compiled to `dist/`.
+
+### Pinning a version
+
+```sh
+curl -fsSL https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.sh | sh -s -- --version 0.1.0
+```
+
+```powershell
+& ([scriptblock]::Create((irm https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.ps1))) -Version 0.1.0
+```
+
+An installer always downloads from the host it was itself served from — that
+base URL is compiled into it at build time — so piping one host's installer
+into a shell never fetches binaries from somewhere else. `--base-url` /
+`-BaseUrl` overrides it for testing against a staging bucket.
+
+The installers verify every download against the sha256 in that release's
+manifest before writing anything, so a pinned version installs identical bytes
+on every machine. They install into `~/.local/bin` (`%LOCALAPPDATA%\ml-dash\bin`
+on Windows) — override with `--install-dir` / `-InstallDir` — and they never
+remove or overwrite an `ml-dash` installed by npm or pip; a conflict on PATH is
+reported and left for you to resolve with the tool that owns it. If the
+install path is already occupied by a file this installer did not write — a
+symlink, a pipx shim, anything without its receipt — it stops instead of
+overwriting; `--force` / `-Force` takes over deliberately.
+
+## Usage
+
+```sh
+ml-dash --help
+ml-dash login
+ml-dash list projects
+ml-dash upload  <local-path> <remote-path>
+ml-dash download <remote-path> <local-path>
+```
+
+Run `ml-dash <command> --help` for the flags of any command.
+
+## Supported platforms
+
+macOS (arm64, x64), Linux (x64, arm64; glibc and musl), Windows (x64, arm64).
+
+The binaries bundle their own runtime, so no Node and no Python is needed.
+They are not statically linked, though: the musl builds link against
+`libstdc++.so.6` and `libgcc_s.so.1`, which a bare Alpine image does not
+ship. On Alpine, install them once:
+
+```sh
+apk add --no-cache libstdc++
+```
+
+`install.sh` runs the downloaded binary before installing it, so a missing
+system library is reported at install time with nothing written, rather
+than at your next `ml-dash` command.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Same terms and copyright as the Python `ml-dash`
+package this CLI talks to.
+
+## Releasing
+
+See [docs/RELEASE.md](docs/RELEASE.md).

package/bin/ml-dash.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// npm channel entry point. The R2 channel compiles src/index.ts into a
+// single-file binary with `bun build --compile` instead; both run the same
+// TypeScript, so there is no second implementation to drift.
+import "../dist/index.js";

package/dist/auth/device-flow.js

@@ -0,0 +1,131 @@
+/**
+ * OAuth 2.0 device authorization against vuer-auth, then token exchange with
+ * the ml-dash server.
+ *
+ * This is a variant of RFC 8628, not the RFC itself: the poll request carries
+ * `client_id` + `device_secret_hash` and no `device_code`. Sending a standard
+ * poll body instead gets `authorization_pending` forever.
+ */
+import { hashDeviceSecret } from "./device-secret.js";
+export const VUER_AUTH_URL = "https://auth.vuer.ai";
+export const CLIENT_ID = "ml-dash-client";
+export const DEFAULT_SCOPE = "openid profile email";
+export class DeviceCodeExpiredError extends Error {
+}
+export class AuthorizationDeniedError extends Error {
+}
+export class TokenExchangeError extends Error {
+}
+export class AuthorizationTimeoutError extends Error {
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class DeviceFlowClient {
+    deviceSecret;
+    dashUrl;
+    authUrl;
+    constructor(deviceSecret, dashUrl, authUrl = VUER_AUTH_URL) {
+        this.deviceSecret = deviceSecret;
+        this.dashUrl = dashUrl;
+        this.authUrl = authUrl;
+        this.dashUrl = dashUrl.replace(/\/+$/, "");
+        this.authUrl = authUrl.replace(/\/+$/, "");
+    }
+    async startDeviceFlow(scope = DEFAULT_SCOPE) {
+        const res = await fetch(`${this.authUrl}/api/device/start`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                client_id: CLIENT_ID,
+                scope,
+                device_secret_hash: hashDeviceSecret(this.deviceSecret),
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            throw new Error(`Device flow start failed: ${res.status} ${await res.text()}`);
+        const data = await res.json();
+        const uri = data.verification_uri;
+        const userCode = data.user_code;
+        return {
+            userCode,
+            deviceCode: data.device_code ?? "",
+            verificationUri: uri,
+            verificationUriComplete: data.verification_uri_complete ?? `${uri}?code=${userCode.replace(/-/g, "")}`,
+            expiresIn: data.expires_in ?? 600,
+            interval: data.interval ?? 5,
+        };
+    }
+    /** Poll until authorized. 120 attempts at 5 s is the Python CLI's 10-minute budget. */
+    async pollForToken(maxAttempts = 120, onProgress) {
+        const hash = hashDeviceSecret(this.deviceSecret);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            onProgress?.(attempt * 5);
+            let res;
+            try {
+                res = await fetch(`${this.authUrl}/api/device/poll`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ client_id: CLIENT_ID, device_secret_hash: hash }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            catch {
+                // Transient network trouble mid-flow should not end the login.
+                await sleep(5_000);
+                continue;
+            }
+            if (res.status === 200)
+                return (await res.json()).access_token;
+            let error;
+            try {
+                error = (await res.json()).error;
+            }
+            catch {
+                error = undefined;
+            }
+            if (error === "authorization_pending") {
+                await sleep(5_000);
+                continue;
+            }
+            if (error === "slow_down") {
+                await sleep(10_000);
+                continue;
+            }
+            if (error === "expired_token") {
+                throw new DeviceCodeExpiredError("Device code expired. Please run 'ml-dash login' again.");
+            }
+            if (error === "access_denied") {
+                throw new AuthorizationDeniedError("User denied authorization request.");
+            }
+            throw new TokenExchangeError(`Device flow error: ${error ?? res.status}`);
+        }
+        throw new AuthorizationTimeoutError("Authorization timed out after 10 minutes. Please run 'ml-dash login' again.");
+    }
+    /** Trade the short-lived vuer-auth JWT for a permanent ml-dash token. */
+    async exchangeToken(vuerAuthToken) {
+        let res;
+        try {
+            res = await fetch(`${this.dashUrl}/api/auth/exchange`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${vuerAuthToken}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch (e) {
+            throw new TokenExchangeError(`Network error during token exchange: ${e}`);
+        }
+        if (res.status === 401) {
+            throw new TokenExchangeError("Vuer-auth token invalid or expired. Please try logging in again.");
+        }
+        if (res.status === 404) {
+            throw new TokenExchangeError("Token exchange endpoint not found. Please ensure ml-dash server is up to date.");
+        }
+        if (!res.ok) {
+            throw new TokenExchangeError(`Token exchange failed: ${res.status} ${await res.text()}`);
+        }
+        const token = (await res.json()).ml_dash_token;
+        if (!token)
+            throw new TokenExchangeError("Server response missing ml_dash_token field");
+        return token;
+    }
+}

package/dist/auth/device-secret.js

@@ -0,0 +1,20 @@
+/**
+ * Device identity for the authorization flow.
+ *
+ * vuer-auth's device endpoints identify this client by the SHA-256 of a
+ * locally generated secret rather than by a server-issued device_code, so the
+ * hash has to be computed the same way the Python CLI computed it or polling
+ * never matches the pending authorization.
+ */
+import { createHash, randomBytes } from "node:crypto";
+/** 32 bytes of entropy, hex-encoded — the shape `secrets.token_hex(32)` produced. */
+export const generateDeviceSecret = () => randomBytes(32).toString("hex");
+export const hashDeviceSecret = (secret) => createHash("sha256").update(secret, "utf8").digest("hex");
+export function getOrCreateDeviceSecret(config) {
+    const existing = config.deviceSecret;
+    if (existing)
+        return existing;
+    const secret = generateDeviceSecret();
+    config.set("device_secret", secret);
+    return secret;
+}

package/dist/auth/fernet.js

@@ -0,0 +1,98 @@
+/**
+ * Fernet (symmetric encryption) over Node's crypto.
+ *
+ * The Python CLI stored fallback tokens with `cryptography.fernet.Fernet` in
+ * ~/.dash/tokens.encrypted, keyed by ~/.dash/encryption.key. Reusing those
+ * credentials means reproducing the wire format exactly, so this implements
+ * the published spec rather than "some AES":
+ *
+ *   token = base64url( 0x80 ‖ timestamp(8, big-endian) ‖ IV(16)
+ *                      ‖ AES-128-CBC(PKCS7(plaintext)) ‖ HMAC-SHA256(32) )
+ *
+ * The key is base64url of 32 bytes: the first 16 are the signing key, the last
+ * 16 the encryption key. The HMAC covers everything before it.
+ *
+ * Nothing here is verified by construction — a plausible-looking but wrong
+ * implementation still produces tokens that decrypt fine against itself. It is
+ * checked instead against a fixture that Python's own Fernet produced; see
+ * test/fernet-interop.test.ts.
+ */
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+const VERSION = 0x80;
+const b64urlDecode = (s) => Buffer.from(s, "base64url");
+/**
+ * Fernet's base64 is padded. Node's "base64url" encoding strips the `=`, and
+ * Python's `base64.urlsafe_b64decode` — which `cryptography.fernet` calls on
+ * both the key and the token — raises on a stripped one. Unpadded output would
+ * therefore round-trip perfectly here and be unreadable by the Python CLI, so
+ * the padding is restored on the way out.
+ */
+const b64urlEncode = (b) => {
+    const s = b.toString("base64url");
+    return s + "=".repeat((4 - (s.length % 4)) % 4);
+};
+export class InvalidFernetToken extends Error {
+}
+export function parseKey(key) {
+    const raw = typeof key === "string" ? b64urlDecode(key.trim()) : key;
+    if (raw.length !== 32) {
+        throw new InvalidFernetToken(`Fernet key must decode to 32 bytes, got ${raw.length}. ` +
+            "~/.dash/encryption.key is not a Fernet key.");
+    }
+    return { signingKey: raw.subarray(0, 16), encryptionKey: raw.subarray(16, 32) };
+}
+/**
+ * A new key, in the exact text form Python's `Fernet.generate_key()` emits:
+ * url-safe base64 *with* padding. `base64.urlsafe_b64decode` rejects a
+ * stripped `=`, so an unpadded key would be written fine here and then be
+ * unreadable by the Python CLI sharing the same ~/.dash directory.
+ */
+export function generateKey() {
+    return b64urlEncode(randomBytes(32));
+}
+export function encrypt(key, plaintext, opts = {}) {
+    const { signingKey, encryptionKey } = parseKey(key);
+    const iv = opts.iv ?? randomBytes(16);
+    if (iv.length !== 16)
+        throw new InvalidFernetToken("IV must be 16 bytes");
+    const ts = Buffer.alloc(8);
+    ts.writeBigUInt64BE(BigInt(opts.timestamp ?? Math.floor(Date.now() / 1000)));
+    const cipher = createCipheriv("aes-128-cbc", encryptionKey, iv);
+    // Node applies PKCS#7 padding by default, which is what Fernet specifies.
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const body = Buffer.concat([Buffer.from([VERSION]), ts, iv, ciphertext]);
+    const hmac = createHmac("sha256", signingKey).update(body).digest();
+    return b64urlEncode(Buffer.concat([body, hmac]));
+}
+export function decrypt(key, token) {
+    const { signingKey, encryptionKey } = parseKey(key);
+    const raw = b64urlDecode(token.trim());
+    // 1 version + 8 timestamp + 16 IV + at least one 16-byte block + 32 HMAC.
+    if (raw.length < 73)
+        throw new InvalidFernetToken("Fernet token is too short");
+    if (raw[0] !== VERSION) {
+        throw new InvalidFernetToken(`Unsupported Fernet version byte 0x${raw[0].toString(16)}`);
+    }
+    const body = raw.subarray(0, raw.length - 32);
+    const mac = raw.subarray(raw.length - 32);
+    const expected = createHmac("sha256", signingKey).update(body).digest();
+    // Reject before decrypting: a wrong key must fail as a signature error, not
+    // as a padding error, which is the whole point of Fernet's encrypt-then-MAC.
+    if (mac.length !== expected.length || !timingSafeEqual(mac, expected)) {
+        throw new InvalidFernetToken("Fernet signature does not verify — wrong key or corrupt token");
+    }
+    const iv = body.subarray(9, 25);
+    const ciphertext = body.subarray(25);
+    if (ciphertext.length === 0 || ciphertext.length % 16 !== 0) {
+        throw new InvalidFernetToken("Fernet ciphertext is not a whole number of AES blocks");
+    }
+    const decipher = createDecipheriv("aes-128-cbc", encryptionKey, iv);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/** Seconds-since-epoch the token records. Present for parity; unused by the CLI. */
+export function tokenTimestamp(token) {
+    const raw = b64urlDecode(token.trim());
+    if (raw.length < 9)
+        throw new InvalidFernetToken("Fernet token is too short");
+    return Number(raw.readBigUInt64BE(1));
+}

package/dist/auth/jwt.js

@@ -0,0 +1,12 @@
+/** Decode a JWT payload without verifying it — for display only, as the Python CLI did. */
+export function decodeJwtPayload(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return {};
+        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/auth/token-storage.js

@@ -0,0 +1,217 @@
+/**
+ * Where the ml-dash token lives, and how this CLI reaches credentials the
+ * Python CLI wrote.
+ *
+ * The Python CLI tried, in order: the OS keyring (service "ml-dash", account
+ * "ml-dash-token"), then a Fernet-encrypted file, then plaintext. This keeps
+ * the same order and the same on-disk formats, so an existing login keeps
+ * working rather than silently appearing logged-out.
+ *
+ * A compiled single-file binary has no Python `keyring` to call, so the OS
+ * keychain is reached through the platform's own tool: `security` on macOS,
+ * `secret-tool` on Linux. Both are read WITHOUT putting the secret on a
+ * command line — reads print to stdout, and the macOS write feeds the value
+ * over stdin — so the token never appears in `ps` output.
+ *
+ * Windows Credential Manager has no comparable tool that ships with the OS.
+ * Rather than pretend, `unreadableKeychainReason` reports it and the caller
+ * tells the user to run `ml-dash login` again. A missing credential must never
+ * read as an empty success.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { decrypt, encrypt, generateKey } from "./fernet.js";
+export const SERVICE_NAME = "ml-dash";
+export const TOKEN_KEY = "ml-dash-token";
+const has = (cmd) => spawnSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" }).status === 0;
+const macKeychain = {
+    load(key) {
+        const r = spawnSync("security", ["find-generic-password", "-s", SERVICE_NAME, "-a", key, "-w"], {
+            encoding: "utf8",
+        });
+        // 44 is `security`'s "item not found". Anything else non-zero is a real
+        // failure (a denied keychain prompt, a locked keychain) and must not be
+        // flattened into "no token".
+        if (r.status === 0)
+            return r.stdout.replace(/\n$/, "");
+        if (r.status === 44)
+            return null;
+        throw new Error(`macOS keychain read failed (exit ${r.status}): ${(r.stderr || "").trim()}`);
+    },
+    store(key, value) {
+        // `-w` with no value makes `security` read the password from stdin twice,
+        // which keeps it out of argv.
+        const r = spawnSync("security", ["add-generic-password", "-U", "-s", SERVICE_NAME, "-a", key, "-w"], {
+            input: `${value}\n${value}\n`,
+            encoding: "utf8",
+        });
+        if (r.status !== 0)
+            throw new Error(`macOS keychain write failed: ${(r.stderr || "").trim()}`);
+    },
+    delete(key) {
+        spawnSync("security", ["delete-generic-password", "-s", SERVICE_NAME, "-a", key], { stdio: "ignore" });
+    },
+};
+const secretToolKeychain = {
+    load(key) {
+        const r = spawnSync("secret-tool", ["lookup", "service", SERVICE_NAME, "username", key], {
+            encoding: "utf8",
+        });
+        if (r.status === 0 && r.stdout !== "")
+            return r.stdout.replace(/\n$/, "");
+        return null;
+    },
+    store(key, value) {
+        const r = spawnSync("secret-tool", ["store", "--label", `${SERVICE_NAME} ${key}`, "service", SERVICE_NAME, "username", key], { input: value, encoding: "utf8" });
+        if (r.status !== 0)
+            throw new Error(`secret-tool write failed: ${(r.stderr || "").trim()}`);
+    },
+    delete(key) {
+        spawnSync("secret-tool", ["clear", "service", SERVICE_NAME, "username", key], { stdio: "ignore" });
+    },
+};
+function keychain() {
+    if (process.env.ML_DASH_NO_KEYCHAIN === "1")
+        return null;
+    if (process.platform === "darwin" && has("security"))
+        return macKeychain;
+    if (process.platform === "linux" && has("secret-tool"))
+        return secretToolKeychain;
+    return null;
+}
+/**
+ * Why the keychain could not be consulted, when that is worth telling the user.
+ * Returns null when there is nothing unusual to report.
+ */
+export function unreadableKeychainReason() {
+    if (process.env.ML_DASH_NO_KEYCHAIN === "1")
+        return null;
+    if (process.platform === "win32") {
+        return ("Windows Credential Manager cannot be read by this build. If you previously " +
+            "logged in with the Python ml-dash CLI, that token is not reachable here.");
+    }
+    if (process.platform === "linux" && !has("secret-tool")) {
+        return ("`secret-tool` is not installed, so the GNOME keyring cannot be read. " +
+            "If you previously logged in with the Python ml-dash CLI, that token is not reachable here.");
+    }
+    if (process.platform === "darwin" && !has("security")) {
+        return "`security` is not on PATH, so the macOS Keychain cannot be read.";
+    }
+    return null;
+}
+// ── file backends ────────────────────────────────────────────────────────────
+export class TokenStore {
+    configDir;
+    encFile;
+    keyFile;
+    plainFile;
+    constructor(configDir) {
+        this.configDir = configDir ?? process.env.ML_DASH_CONFIG_DIR ?? path.join(homedir(), ".dash");
+        this.encFile = path.join(this.configDir, "tokens.encrypted");
+        this.keyFile = path.join(this.configDir, "encryption.key");
+        this.plainFile = path.join(this.configDir, "tokens.json");
+    }
+    readEncrypted() {
+        if (!existsSync(this.encFile) || !existsSync(this.keyFile))
+            return {};
+        const key = readFileSync(this.keyFile, "utf8");
+        return JSON.parse(decrypt(key, readFileSync(this.encFile, "utf8")).toString("utf8"));
+    }
+    writeEncrypted(all) {
+        mkdirSync(this.configDir, { recursive: true });
+        if (!existsSync(this.keyFile)) {
+            writeFileSync(this.keyFile, generateKey());
+            chmodSync(this.keyFile, 0o600);
+        }
+        writeFileSync(this.encFile, 
+        // The key file stores base64 text (Python's format), not raw bytes.
+        encrypt(readFileSync(this.keyFile, "utf8"), Buffer.from(JSON.stringify(all), "utf8")));
+        chmodSync(this.encFile, 0o600);
+    }
+    readPlain() {
+        if (!existsSync(this.plainFile))
+            return {};
+        try {
+            return JSON.parse(readFileSync(this.plainFile, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Resolve a token, reporting which backend answered. Keychain first, so a
+     * Python-era login is found before any file this CLI wrote.
+     */
+    load(key = TOKEN_KEY) {
+        const kc = keychain();
+        if (kc) {
+            const v = kc.load(key);
+            if (v)
+                return { token: v, source: "keychain" };
+        }
+        if (existsSync(this.encFile)) {
+            // A decrypt failure here is load-bearing: the file exists, so the user
+            // does have a stored credential, and swallowing the error would present
+            // a corrupt keyfile as "never logged in".
+            const v = this.readEncrypted()[key];
+            if (v)
+                return { token: v, source: "encrypted-file" };
+        }
+        const p = this.readPlain()[key];
+        if (p)
+            return { token: p, source: "plaintext-file" };
+        return { token: null, source: null, unreadableReason: unreadableKeychainReason() ?? undefined };
+    }
+    /** Write to the keychain when one is reachable, otherwise the encrypted file. */
+    store(value, key = TOKEN_KEY) {
+        const kc = keychain();
+        if (kc) {
+            try {
+                kc.store(key, value);
+                return "keychain";
+            }
+            catch {
+                // Fall through — an unavailable keychain should not fail a login.
+            }
+        }
+        const all = existsSync(this.encFile) ? this.readEncrypted() : {};
+        all[key] = value;
+        this.writeEncrypted(all);
+        return "encrypted-file";
+    }
+    /** Clear every backend: logging out of one but not the others is not a logout. */
+    delete(key = TOKEN_KEY) {
+        const kc = keychain();
+        if (kc) {
+            try {
+                kc.delete(key);
+            }
+            catch {
+                /* already absent */
+            }
+        }
+        if (existsSync(this.encFile)) {
+            try {
+                const all = this.readEncrypted();
+                if (key in all) {
+                    delete all[key];
+                    this.writeEncrypted(all);
+                }
+            }
+            catch {
+                // Undecryptable file: remove it rather than leave a credential behind.
+                unlinkSync(this.encFile);
+            }
+        }
+        if (existsSync(this.plainFile)) {
+            const all = this.readPlain();
+            if (key in all) {
+                delete all[key];
+                writeFileSync(this.plainFile, JSON.stringify(all, null, 2));
+                chmodSync(this.plainFile, 0o600);
+            }
+        }
+    }
+}

package/dist/cli/context.js

@@ -0,0 +1,34 @@
+/**
+ * Shared command setup: which server to talk to, and with which credential.
+ *
+ * Resolution order matches the Python CLI: an explicit `--dash-url` beats
+ * ~/.dash/config.json's `remote_url`, which beats the built-in default; and an
+ * `api_key` written into the config beats the stored login token, so a
+ * service-account config keeps working without a keychain.
+ */
+import { RemoteClient } from "../client.js";
+import { Config, DEFAULT_API_URL } from "../config.js";
+import { TokenStore } from "../auth/token-storage.js";
+export function resolveContext(args) {
+    const config = new Config();
+    const remoteUrl = (typeof args.dash_url === "string" ? args.dash_url : undefined) ||
+        config.remoteUrl ||
+        DEFAULT_API_URL;
+    if (config.apiKey)
+        return { config, remoteUrl, apiKey: config.apiKey };
+    const loaded = new TokenStore(config.configDir).load();
+    return {
+        config,
+        remoteUrl,
+        apiKey: loaded.token ?? undefined,
+        unreadableReason: loaded.unreadableReason,
+    };
+}
+export function makeClient(ctx, namespace) {
+    return new RemoteClient(ctx.remoteUrl, namespace, ctx.apiKey);
+}
+/** The single message every command uses when there is no usable credential. */
+export function notAuthenticatedMessage(ctx) {
+    const base = "Not authenticated. Run 'ml-dash login' to authenticate.";
+    return ctx.unreadableReason ? `${base}\n\n${ctx.unreadableReason}` : base;
+}