@userland.fun/cli 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# Userland CLI
+
+This directory is the source for the public `@userland.fun/cli` npm package.
+
+Docs:
+
+- https://docs.userland.fun/llms.txt
+- https://docs.userland.fun/reference/cli
+- https://docs.userland.fun/guides/troubleshooting
+
+Install globally:
+
+```sh
+npm install -g @userland.fun/cli
+```
+
+Then run:
+
+```sh
+userland signup --username <username>
+userland login --username <username>
+userland auth status
+userland auth save-key --username <username> --api-key <api-key>
+userland apps publish examples/<example-slug>
+userland apps list
+userland apps releases <app-id>
+userland apps rollback <app-id> <release-id>
+userland apps secrets set <app-id> <NAME> --value <value>
+userland apps events <app-id>
+```
+
+From this repo, the same commands can be run from source:
+
+```sh
+npm run userland -- signup --username <username>
+npm run userland -- login --username <username>
+npm run userland -- auth status
+npm run userland -- auth save-key --username <username> --api-key <api-key>
+npm run userland -- apps publish examples/<example-slug>
+npm run userland -- apps list
+npm run userland -- apps releases <app-id>
+npm run userland -- apps rollback <app-id> <release-id>
+npm run userland -- apps secrets set <app-id> <NAME> --value <value>
+npm run userland -- apps events <app-id>
+```
+
+`signup`, `login`, and `auth save-key` save the API key to `~/.userland/credentials.json` with `0600` permissions. Account username and password are stored in the OS keychain: macOS Keychain, Windows Credential Manager, or Linux Secret Service through `secret-tool`. App commands prefer `USERLAND_API_KEY` when it is set, then fall back to the saved API key.
+
+## Validation
+
+Build and inspect the publish tarball:
+
+```sh
+npm run cli:build
+npm run cli:pack
+```
+
+Run command-level CLI tests against a mocked API:
+
+```sh
+npm run cli:test
+```
+
+Run the full public repo validation suite:
+
+```sh
+npm run typecheck
+npm test
+```
+
+## Sync and release policy
+
+For launch, this `cli/` directory is the public CLI source of truth for agents and publishes as `@userland.fun/cli`. When changing the CLI:
+
+1. Update `cli/src/index.ts`, this README, and `https://docs.userland.fun/reference/cli` together.
+2. Add or update mocked command tests in `cli/tests`.
+3. Run `npm run typecheck`, `npm run cli:test`, and `npm test`.
+4. Update the public repo changelog and the docs changelog.
+
+Compatibility:
+
+| CLI package | API version | Distribution |
+|---|---|---|
+| `@userland.fun/cli` | Userland API v0 | `npm install -g @userland.fun/cli` |
+
+Do not commit API keys or app secrets.

package/dist/index.js

@@ -0,0 +1,927 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+const DEFAULT_API_BASE_URL = "https://api.userland.fun";
+const KEYCHAIN_SERVICE = "fun.userland.cli";
+const KEYCHAIN_ACCOUNT = "default";
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (command === "apps") {
+        await appsCommand(args);
+        return;
+    }
+    if (command === "auth") {
+        await authCommand(args);
+        return;
+    }
+    if (command === "signup") {
+        await signupCommand(args);
+        return;
+    }
+    if (command === "login") {
+        await loginCommand(args);
+        return;
+    }
+    if (command === "publish") {
+        await publishCommand(args);
+        return;
+    }
+    if (command === "releases" || command === "versions") {
+        await releasesCommand(args);
+        return;
+    }
+    usage(1);
+}
+async function appsCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "publish") {
+        await publishCommand(rest);
+        return;
+    }
+    if (subcommand === "list") {
+        await listAppsCommand();
+        return;
+    }
+    if (subcommand === "releases") {
+        await releasesCommand(rest);
+        return;
+    }
+    if (subcommand === "rollback") {
+        await rollbackCommand(rest);
+        return;
+    }
+    if (subcommand === "secrets" && rest[0] === "set") {
+        await setSecretCommand(rest.slice(1));
+        return;
+    }
+    if (subcommand === "events") {
+        await eventsCommand(rest);
+        return;
+    }
+    usage(1);
+}
+async function authCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "signup") {
+        await signupCommand(rest);
+        return;
+    }
+    if (subcommand === "login") {
+        await loginCommand(rest);
+        return;
+    }
+    if (subcommand === "status") {
+        await authStatusCommand();
+        return;
+    }
+    if (subcommand === "save-key") {
+        await saveKeyCommand(rest);
+        return;
+    }
+    usage(1);
+}
+async function signupCommand(args) {
+    const options = parseAuthOptions(args);
+    const username = options.username ?? (await promptRequired("Username: "));
+    const password = options.password ?? (await promptPassword("Password: "));
+    const body = { username, password };
+    if (options.email) {
+        body.email = options.email;
+    }
+    const response = await unauthenticatedApiFetch("/v0/accounts", {
+        method: "POST",
+        body: JSON.stringify(body)
+    });
+    if (options.save !== false) {
+        await saveAccountCredentials({ username: response.username, password });
+        const filePath = await saveCredentials({
+            api_key: response.api_key,
+            api_base_url: await apiBaseUrl()
+        });
+        console.log(`Created Userland account ${response.username}`);
+        console.log(`Saved API key to ${filePath}`);
+        console.log(`Saved account login to ${accountCredentialStoreLabel()}`);
+        return;
+    }
+    console.log(`Created Userland account ${response.username}`);
+    console.log(`api_key=${response.api_key}`);
+}
+async function loginCommand(args) {
+    const options = parseAuthOptions(args);
+    const storedAccount = await readAccountCredentials();
+    const username = options.username ?? storedAccount?.username ?? (await promptRequired("Username: "));
+    const password = options.password ?? storedAccount?.password ?? (await promptPassword("Password: "));
+    const response = await unauthenticatedApiFetch("/v0/auth/token", {
+        method: "POST",
+        body: JSON.stringify({ username, password })
+    });
+    if (options.save !== false) {
+        await saveAccountCredentials({ username, password });
+        const filePath = await saveCredentials({
+            api_key: response.api_key,
+            api_base_url: await apiBaseUrl()
+        });
+        console.log(`Saved API key to ${filePath}`);
+        console.log(`Saved account login to ${accountCredentialStoreLabel()}`);
+        return;
+    }
+    console.log(`api_key=${response.api_key}`);
+}
+async function authStatusCommand() {
+    const credentials = await readCredentials();
+    const account = await readAccountCredentials();
+    const filePath = credentialsPath();
+    const apiKeySource = process.env.USERLAND_API_KEY ? "env" : credentials?.api_key ? "file" : "missing";
+    console.log(`api_base_url=${await apiBaseUrl(credentials)}`);
+    console.log(`api_key=${apiKeySource}`);
+    console.log(`credentials_file=${filePath}`);
+    console.log(`account=${account ? "keychain" : "missing"}`);
+    if (account?.username) {
+        console.log(`username=${account.username}`);
+    }
+}
+async function saveKeyCommand(args) {
+    const options = parseAuthOptions(args);
+    const username = options.username ?? (await promptRequired("Username: "));
+    const apiKey = options.apiKey ?? (await promptRequired("API key: "));
+    await saveAccountCredentials({ username, password: options.password });
+    const filePath = await saveCredentials({
+        api_key: apiKey,
+        api_base_url: await apiBaseUrl()
+    });
+    console.log(`Saved API key to ${filePath}`);
+    console.log(`Saved account login to ${accountCredentialStoreLabel()}`);
+}
+async function publishCommand(args) {
+    const dir = args[0];
+    const options = parseOptions(args.slice(1));
+    if (!dir) {
+        usage(1);
+    }
+    const body = await readPublishDirectory(dir, options);
+    const response = await apiFetch(options.app ? `/v0/apps/${options.app}` : "/v0/apps", {
+        method: "PUT",
+        body: JSON.stringify(body)
+    });
+    console.log(`Published ${response.origin}`);
+    console.log(`app_id=${response.app_id}`);
+    console.log(`release_id=${response.release_id}`);
+    console.log(`previous_release_id=${response.previous_release_id ?? ""}`);
+    console.log(`activation_status=${response.activation.status}`);
+    if (response.activation.reasons.length > 0) {
+        console.log(`activation_reasons=${response.activation.reasons.join("; ")}`);
+    }
+}
+async function listAppsCommand() {
+    const response = await apiFetch("/v0/apps", {
+        method: "GET"
+    });
+    for (const app of response.apps) {
+        console.log(`${app.app_id}\t${app.live_release_id ?? ""}\t${app.updated_at}\t${app.name}\t${app.origin}`);
+    }
+}
+async function releasesCommand(args) {
+    const appId = args[0];
+    if (!appId) {
+        usage(1);
+    }
+    const response = await apiFetch(`/v0/apps/${appId}/releases`, {
+        method: "GET"
+    });
+    for (const release of response.releases) {
+        const live = release.is_live ? " live" : "";
+        console.log(`${release.release_id}${live}\t${release.activation_status}\t${release.created_at}\t${release.message ?? ""}`);
+    }
+}
+async function rollbackCommand(args) {
+    const [appId, releaseId] = args;
+    if (!appId || !releaseId) {
+        usage(1);
+    }
+    const response = await apiFetch(`/v0/apps/${appId}/rollback`, {
+        method: "POST",
+        body: JSON.stringify({ release_id: releaseId })
+    });
+    console.log(`Rolled back ${response.origin}`);
+    console.log(`app_id=${response.app_id}`);
+    console.log(`release_id=${response.release_id}`);
+    console.log(`previous_release_id=${response.previous_release_id ?? ""}`);
+    console.log(`status=${response.status}`);
+}
+async function setSecretCommand(args) {
+    const [appId, name, ...optionArgs] = args;
+    if (!appId || !name) {
+        usage(1);
+    }
+    const options = parseSecretSetOptions(optionArgs);
+    const value = options.value ?? (await readStdin()).trimEnd();
+    if (!value) {
+        throw new Error("Secret value is required on stdin or with --value.");
+    }
+    const response = await apiFetch(`/v0/apps/${appId}/secrets/${name}`, {
+        method: "PUT",
+        body: JSON.stringify({ value })
+    });
+    console.log(`secret=${response.name}`);
+    console.log(`present=${response.present}`);
+    console.log(`updated_at=${response.updated_at}`);
+}
+async function eventsCommand(args) {
+    const appId = args[0];
+    if (!appId) {
+        usage(1);
+    }
+    const options = parseEventsOptions(args.slice(1));
+    const params = new URLSearchParams();
+    if (options.type)
+        params.set("type", options.type);
+    if (options.severity)
+        params.set("severity", options.severity);
+    if (options.releaseId)
+        params.set("release_id", options.releaseId);
+    if (options.limit)
+        params.set("limit", options.limit);
+    const suffix = params.toString() ? `?${params.toString()}` : "";
+    const response = await apiFetch(`/v0/apps/${appId}/events${suffix}`, {
+        method: "GET"
+    });
+    for (const event of response.events) {
+        console.log(`${event.created_at}\t${event.severity}\t${event.type}\t${event.release_id ?? ""}\t${event.message}`);
+    }
+    if (response.cursor) {
+        console.log(`cursor=${response.cursor}`);
+    }
+}
+async function readPublishDirectory(rootDir, options) {
+    const absoluteRoot = path.resolve(rootDir);
+    const stat = await fs.stat(absoluteRoot).catch(() => null);
+    if (!stat?.isDirectory()) {
+        throw new Error(`Directory not found: ${rootDir}`);
+    }
+    const manifest = await readManifest(absoluteRoot);
+    const files = await readReleaseFiles(absoluteRoot, manifest);
+    const app = objectValue(manifest.app) ?? {
+        name: path.basename(absoluteRoot)
+    };
+    const runtime = objectValue(manifest.runtime) ?? {
+        static_root: "public",
+        fallback: "index.html"
+    };
+    const resources = objectValue(manifest.resources) ?? {};
+    const provenance = objectValue(manifest.provenance) ?? {};
+    return {
+        app,
+        runtime,
+        resources,
+        files,
+        message: options.message ?? stringValue(manifest.message),
+        provenance
+    };
+}
+async function readReleaseFiles(rootDir, manifest) {
+    const manifestFiles = Array.isArray(manifest.files) ? manifest.files : null;
+    const publishFiles = manifestFiles && manifestFiles.length > 0
+        ? manifestFiles.map(async (entry) => {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                throw new Error("manifest.userland.json files entries must be objects.");
+            }
+            const file = entry;
+            if (typeof file.path !== "string") {
+                throw new Error("manifest.userland.json files entries require path.");
+            }
+            const contents = await fs.readFile(path.join(rootDir, file.path));
+            return {
+                path: file.path,
+                content_type: typeof file.content_type === "string" ? file.content_type : contentTypeForPath(file.path),
+                content_base64: contents.toString("base64")
+            };
+        })
+        : (await walk(rootDir))
+            .filter((filePath) => !isManifestFile(filePath))
+            .sort()
+            .map(async (filePath) => {
+            const relativePath = path.relative(rootDir, filePath).split(path.sep).join("/");
+            const contents = await fs.readFile(filePath);
+            return {
+                path: relativePath,
+                content_type: contentTypeForPath(relativePath),
+                content_base64: contents.toString("base64")
+            };
+        });
+    const files = await Promise.all(publishFiles);
+    if (files.length === 0) {
+        throw new Error("Publish directory must contain at least one file.");
+    }
+    return files;
+}
+async function readManifest(rootDir) {
+    const userlandManifestPath = path.join(rootDir, "manifest.userland.json");
+    const legacyManifestPath = path.join(rootDir, "manifest.json");
+    let manifestPath = userlandManifestPath;
+    let contents = await fs.readFile(manifestPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    });
+    if (!contents) {
+        manifestPath = legacyManifestPath;
+        contents = await fs.readFile(manifestPath, "utf8").catch((error) => {
+            if (error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        });
+    }
+    if (!contents) {
+        return {};
+    }
+    const parsed = JSON.parse(contents);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("manifest.json must contain a JSON object.");
+    }
+    return parsed;
+}
+function isManifestFile(filePath) {
+    const basename = path.basename(filePath);
+    return basename === "manifest.userland.json" || basename === "manifest.json";
+}
+async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            return await walk(entryPath);
+        }
+        if (entry.isFile()) {
+            return [entryPath];
+        }
+        return [];
+    }));
+    return files.flat();
+}
+async function apiFetch(apiPath, init) {
+    const credentials = await readCredentials();
+    const apiKey = process.env.USERLAND_API_KEY ?? credentials?.api_key;
+    if (!apiKey) {
+        throw new Error("USERLAND_API_KEY is required. Run `userland signup` or `userland login` to save credentials.");
+    }
+    const baseUrl = await apiBaseUrl(credentials);
+    return await requestJson(baseUrl, apiPath, {
+        ...init,
+        headers: {
+            authorization: `Bearer ${apiKey}`,
+            ...init.headers
+        }
+    });
+}
+async function unauthenticatedApiFetch(apiPath, init) {
+    return await requestJson(await apiBaseUrl(), apiPath, init);
+}
+async function requestJson(baseUrl, apiPath, init) {
+    const response = await fetch(`${baseUrl.replace(/\/$/u, "")}${apiPath}`, {
+        ...init,
+        headers: {
+            "content-type": "application/json",
+            ...init.headers
+        }
+    });
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : undefined;
+    if (!response.ok) {
+        const message = errorMessage(body) ?? response.statusText;
+        throw new Error(`API ${response.status}: ${message}`);
+    }
+    return body;
+}
+async function apiBaseUrl(credentials) {
+    return process.env.USERLAND_API_BASE_URL ?? credentials?.api_base_url ?? (await readCredentials())?.api_base_url ?? DEFAULT_API_BASE_URL;
+}
+function credentialsPath() {
+    return process.env.USERLAND_CREDENTIALS_FILE ?? path.join(os.homedir(), ".userland", "credentials.json");
+}
+async function readCredentials() {
+    const filePath = credentialsPath();
+    const contents = await fs.readFile(filePath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    });
+    if (!contents) {
+        return undefined;
+    }
+    const parsed = JSON.parse(contents);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Credentials file must contain a JSON object: ${filePath}`);
+    }
+    const credentials = parsed;
+    return {
+        api_base_url: stringValue(credentials.api_base_url),
+        api_key: stringValue(credentials.api_key),
+        updated_at: stringValue(credentials.updated_at)
+    };
+}
+async function saveCredentials(update) {
+    const filePath = credentialsPath();
+    const existing = (await readCredentials()) ?? {};
+    const sanitizedUpdate = Object.fromEntries(Object.entries(update).filter(([, value]) => value !== undefined));
+    const credentials = {
+        ...existing,
+        ...sanitizedUpdate,
+        updated_at: new Date().toISOString()
+    };
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700).catch(() => undefined);
+    await fs.writeFile(filePath, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    await fs.chmod(filePath, 0o600).catch(() => undefined);
+    return filePath;
+}
+async function readAccountCredentials() {
+    const raw = await keychainGetSecret().catch((error) => {
+        if (error instanceof KeychainUnavailableError) {
+            return undefined;
+        }
+        throw error;
+    });
+    if (!raw) {
+        return undefined;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Stored Userland account credentials are malformed.");
+    }
+    const credentials = parsed;
+    const username = stringValue(credentials.username);
+    const password = stringValue(credentials.password);
+    return username || password ? { username, password } : undefined;
+}
+async function saveAccountCredentials(update) {
+    const existing = (await readAccountCredentials()) ?? {};
+    const sanitizedUpdate = Object.fromEntries(Object.entries(update).filter(([, value]) => value !== undefined));
+    const credentials = {
+        ...existing,
+        ...sanitizedUpdate
+    };
+    if (!credentials.username && !credentials.password) {
+        return;
+    }
+    await keychainSetSecret(JSON.stringify(credentials));
+}
+function accountCredentialStoreLabel() {
+    return process.env.USERLAND_KEYCHAIN_FILE ? "test keychain" : "OS keychain";
+}
+class KeychainUnavailableError extends Error {
+}
+async function keychainGetSecret() {
+    const testKeychainFile = process.env.USERLAND_KEYCHAIN_FILE;
+    if (testKeychainFile) {
+        return await fileKeychainGet(testKeychainFile);
+    }
+    if (process.platform === "darwin") {
+        const result = await runCommand("security", ["find-generic-password", "-a", KEYCHAIN_ACCOUNT, "-s", KEYCHAIN_SERVICE, "-w"]);
+        if (result.code === 44) {
+            return undefined;
+        }
+        assertCommandOk("security", result);
+        return result.stdout.trimEnd();
+    }
+    if (process.platform === "linux") {
+        const result = await runCommand("secret-tool", ["lookup", "service", KEYCHAIN_SERVICE, "account", KEYCHAIN_ACCOUNT]);
+        if (result.code === 1) {
+            return undefined;
+        }
+        assertCommandOk("secret-tool", result);
+        return result.stdout.trimEnd();
+    }
+    if (process.platform === "win32") {
+        const result = await runPowerShell(windowsCredentialReadScript());
+        if (result.code === 2) {
+            return undefined;
+        }
+        assertCommandOk("powershell", result);
+        return result.stdout.trimEnd();
+    }
+    throw new KeychainUnavailableError(`OS keychain is not supported on ${process.platform}.`);
+}
+async function keychainSetSecret(secret) {
+    const testKeychainFile = process.env.USERLAND_KEYCHAIN_FILE;
+    if (testKeychainFile) {
+        await fileKeychainSet(testKeychainFile, secret);
+        return;
+    }
+    if (process.platform === "darwin") {
+        assertCommandOk("security", await runCommand("security", ["add-generic-password", "-U", "-a", KEYCHAIN_ACCOUNT, "-s", KEYCHAIN_SERVICE, "-w", secret]));
+        return;
+    }
+    if (process.platform === "linux") {
+        assertCommandOk("secret-tool", await runCommand("secret-tool", ["store", "--label", "Userland CLI", "service", KEYCHAIN_SERVICE, "account", KEYCHAIN_ACCOUNT], secret));
+        return;
+    }
+    if (process.platform === "win32") {
+        assertCommandOk("powershell", await runPowerShell(windowsCredentialWriteScript(), secret));
+        return;
+    }
+    throw new KeychainUnavailableError(`OS keychain is not supported on ${process.platform}.`);
+}
+async function fileKeychainGet(filePath) {
+    const contents = await fs.readFile(filePath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    });
+    if (!contents) {
+        return undefined;
+    }
+    const parsed = JSON.parse(contents);
+    return parsed[`${KEYCHAIN_SERVICE}:${KEYCHAIN_ACCOUNT}`];
+}
+async function fileKeychainSet(filePath, secret) {
+    const existing = await fs.readFile(filePath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return "{}";
+        }
+        throw error;
+    });
+    const parsed = JSON.parse(existing);
+    parsed[`${KEYCHAIN_SERVICE}:${KEYCHAIN_ACCOUNT}`] = secret;
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    await fs.writeFile(filePath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    await fs.chmod(filePath, 0o600).catch(() => undefined);
+}
+async function runCommand(command, args, stdin, env) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { env: env ? { ...process.env, ...env } : process.env, stdio: ["pipe", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            if (error.code === "ENOENT") {
+                reject(new KeychainUnavailableError(`${command} is required for OS keychain access.`));
+                return;
+            }
+            reject(error);
+        });
+        child.on("close", (code) => {
+            resolve({
+                code,
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8")
+            });
+        });
+        child.stdin.end(stdin ?? "");
+    });
+}
+async function runPowerShell(script, stdin) {
+    const env = stdin === undefined ? undefined : { USERLAND_KEYCHAIN_SECRET: stdin };
+    return await runCommand("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "-"], scriptWithInput(script), env);
+}
+function scriptWithInput(script) {
+    return `$ErrorActionPreference = "Stop"\n${script}`;
+}
+function assertCommandOk(command, result) {
+    if (result.code !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.code ?? "unknown"}`;
+        throw new Error(`${command} failed while accessing the OS keychain: ${detail}`);
+    }
+}
+function windowsCredentialWriteScript() {
+    return `
+Add-Type -TypeDefinition @"
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class UserlandCredential {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct Credential {
+    public UInt32 Flags;
+    public UInt32 Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public UInt32 CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public UInt32 Persist;
+    public UInt32 AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+
+  [DllImport("Advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  private static extern bool CredWrite(ref Credential credential, UInt32 flags);
+
+  public static void Write(string target, string username, string secret) {
+    byte[] bytes = Encoding.Unicode.GetBytes(secret);
+    IntPtr blob = Marshal.AllocCoTaskMem(bytes.Length);
+    try {
+      Marshal.Copy(bytes, 0, blob, bytes.Length);
+      Credential credential = new Credential();
+      credential.Type = 1;
+      credential.TargetName = target;
+      credential.UserName = username;
+      credential.CredentialBlob = blob;
+      credential.CredentialBlobSize = (UInt32)bytes.Length;
+      credential.Persist = 2;
+      if (!CredWrite(ref credential, 0)) {
+        throw new Win32Exception(Marshal.GetLastWin32Error());
+      }
+    } finally {
+      Marshal.FreeCoTaskMem(blob);
+    }
+  }
+}
+"@
+$secret = [Environment]::GetEnvironmentVariable("USERLAND_KEYCHAIN_SECRET")
+[UserlandCredential]::Write(${JSON.stringify(KEYCHAIN_SERVICE)}, ${JSON.stringify(KEYCHAIN_ACCOUNT)}, $secret)
+`;
+}
+function windowsCredentialReadScript() {
+    return `
+Add-Type -TypeDefinition @"
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+public static class UserlandCredential {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct Credential {
+    public UInt32 Flags;
+    public UInt32 Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public UInt32 CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public UInt32 Persist;
+    public UInt32 AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+
+  [DllImport("Advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  private static extern bool CredRead(string target, UInt32 type, UInt32 reservedFlag, out IntPtr credentialPtr);
+
+  [DllImport("Advapi32.dll", SetLastError = true)]
+  private static extern void CredFree(IntPtr buffer);
+
+  public static string Read(string target) {
+    IntPtr credentialPtr;
+    if (!CredRead(target, 1, 0, out credentialPtr)) {
+      int error = Marshal.GetLastWin32Error();
+      if (error == 1168) {
+        Environment.Exit(2);
+      }
+      throw new Win32Exception(error);
+    }
+
+    try {
+      Credential credential = (Credential)Marshal.PtrToStructure(credentialPtr, typeof(Credential));
+      return Marshal.PtrToStringUni(credential.CredentialBlob, (int)credential.CredentialBlobSize / 2);
+    } finally {
+      CredFree(credentialPtr);
+    }
+  }
+}
+"@
+[Console]::Out.Write([UserlandCredential]::Read(${JSON.stringify(KEYCHAIN_SERVICE)}))
+`;
+}
+function parseOptions(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--app") {
+            options.app = args[++index];
+        }
+        else if (arg === "--message") {
+            options.message = args[++index];
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseAuthOptions(args) {
+    const options = { save: true };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--username") {
+            options.username = args[++index];
+        }
+        else if (arg === "--password") {
+            options.password = args[++index];
+        }
+        else if (arg === "--email") {
+            options.email = args[++index];
+        }
+        else if (arg === "--api-key") {
+            options.apiKey = args[++index];
+        }
+        else if (arg === "--no-save") {
+            options.save = false;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseSecretSetOptions(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--value") {
+            options.value = args[++index];
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseEventsOptions(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--type") {
+            options.type = args[++index];
+        }
+        else if (arg === "--severity") {
+            options.severity = args[++index];
+        }
+        else if (arg === "--release") {
+            options.releaseId = args[++index];
+        }
+        else if (arg === "--limit") {
+            options.limit = args[++index];
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+async function readStdin() {
+    if (process.stdin.isTTY) {
+        return "";
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function promptRequired(prompt) {
+    const value = await promptLine(prompt);
+    if (!value) {
+        throw new Error(`${prompt.replace(/:\s*$/u, "")} is required.`);
+    }
+    return value;
+}
+async function promptLine(prompt) {
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await readline.question(prompt)).trim();
+    }
+    finally {
+        readline.close();
+    }
+}
+async function promptPassword(prompt) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return await promptRequired(prompt);
+    }
+    process.stdout.write(prompt);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    return await new Promise((resolve, reject) => {
+        let value = "";
+        const cleanup = () => {
+            process.stdin.setRawMode(false);
+            process.stdin.off("data", onData);
+        };
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === "\u0003") {
+                    cleanup();
+                    process.stdout.write("\n");
+                    reject(new Error("Interrupted."));
+                    return;
+                }
+                if (char === "\r" || char === "\n" || char === "\u0004") {
+                    cleanup();
+                    process.stdout.write("\n");
+                    if (!value) {
+                        reject(new Error("Password is required."));
+                        return;
+                    }
+                    resolve(value);
+                    return;
+                }
+                if (char === "\u007f") {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += char;
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
+function objectValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function contentTypeForPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const types = {
+        ".html": "text/html; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".js": "application/javascript; charset=utf-8",
+        ".json": "application/json; charset=utf-8",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".txt": "text/plain; charset=utf-8"
+    };
+    return types[ext] ?? "application/octet-stream";
+}
+function errorMessage(body) {
+    if (typeof body !== "object" || body === null || !("error" in body)) {
+        return undefined;
+    }
+    const error = body.error;
+    if (typeof error !== "object" || error === null || !("message" in error)) {
+        return undefined;
+    }
+    const typedError = error;
+    const message = typeof typedError.message === "string" ? typedError.message : undefined;
+    const code = typeof typedError.code === "string" ? typedError.code : undefined;
+    if (code && message) {
+        return `${code}: ${message}`;
+    }
+    return message ?? code;
+}
+function usage(exitCode) {
+    console.error(`Usage:
+  userland signup [--username <username>] [--password <password>] [--email <email>] [--no-save]
+  userland login [--username <username>] [--password <password>] [--no-save]
+  userland auth status
+  userland auth save-key --username <username> --api-key <api-key> [--password <password>]
+  userland apps publish <dir> [--app <app-id>] [--message <message>]
+  userland apps list
+  userland apps releases <app-id>
+  userland apps rollback <app-id> <release-id>
+  userland apps secrets set <app-id> <NAME> [--value <value>]
+  userland apps events <app-id> [--type <event-type>] [--severity <level>] [--release <release-id>] [--limit <n>]
+
+Aliases:
+  userland auth signup [--username <username>] [--password <password>] [--email <email>] [--no-save]
+  userland auth login [--username <username>] [--password <password>] [--no-save]
+  userland publish <dir> [--app <app-id>] [--message <message>]
+  userland releases <app-id>
+
+Credentials:
+  Commands use USERLAND_API_KEY first, then ~/.userland/credentials.json for API keys.
+  Account username and password are stored in the OS keychain.
+
+Docs:
+  https://docs.userland.fun/reference/cli
+  https://docs.userland.fun/guides/troubleshooting`);
+    process.exit(exitCode);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    console.error(`Docs: ${docsUrlForError(message)}`);
+    process.exit(1);
+});
+function docsUrlForError(message) {
+    if (message.includes("USERLAND_API_KEY") || message.includes("credentials")) {
+        return "https://docs.userland.fun/reference/cli";
+    }
+    if (message.includes("secrets") || message.includes("pending_secrets")) {
+        return "https://docs.userland.fun/guides/secrets";
+    }
+    if (message.includes("rollback")) {
+        return "https://docs.userland.fun/guides/rollback";
+    }
+    return "https://docs.userland.fun/guides/troubleshooting";
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@userland.fun/cli",
+  "version": "0.1.0",
+  "description": "Userland command-line tools for publishing and operating apps.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "userland": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "cd .. && npm run cli:build",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dwrtz/userland-public.git",
+    "directory": "cli"
+  },
+  "homepage": "https://docs.userland.fun/reference/cli",
+  "bugs": {
+    "url": "https://github.com/dwrtz/userland-public/issues"
+  }
+}