railcode 0.1.1 → 0.1.5

package/dist/index.js

@@ -8,14 +8,15 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-const VERSION = "0.1.1";
 const CLI_PACKAGE_NAME = "railcode";
 const SKILL_NAME = "create-railcode-app";
 const RAILCODE_HOME = process.env.RAILCODE_HOME || join(homedir(), ".railcode");
 const CONFIG_PATH = join(RAILCODE_HOME, "config.json");
 const CLI_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const DEFAULT_DEV_PORT = "7331";
-const DEFAULT_ASSET_DEV_PORT = "5173";
+const VERSION = readCliPackageVersion();
+const DEFAULT_DEV_PORT = 7331;
+const DEFAULT_ASSET_DEV_PORT = 5173;
+const PORT_SEARCH_LIMIT = 100;
 const CLI_AUTH_CALLBACK_PATH = "/railcode-cli/callback";
 const CLI_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
 const HELP = `railcode ${VERSION}
@@ -23,8 +24,9 @@ const HELP = `railcode ${VERSION}
 Usage:
   railcode dev [--verbose]
   railcode login [--api-url <url>]
-  railcode deploy
-  railcode design-system pull [output.md]
+  railcode deploy [--private | --public]
+  railcode access [public|private|restricted] [--users <a,b>]
+  railcode get design-system
   railcode init <app>
   railcode upgrade
   railcode skill stamp [path]
@@ -54,6 +56,12 @@ async function main() {
         case "deploy":
             await commandDeploy(args);
             return;
+        case "access":
+            await commandAccess(args);
+            return;
+        case "get":
+            await commandGet(args);
+            return;
         case "design-system":
             await commandDesignSystem(args);
             return;
@@ -110,6 +118,14 @@ function parseArgs(argv) {
     }
     return { command, rest, options };
 }
+function readCliPackageVersion() {
+    const packagePath = join(CLI_PACKAGE_ROOT, "package.json");
+    const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+    if (typeof pkg.version !== "string" || !pkg.version) {
+        throw new Error(`Missing CLI package version in ${packagePath}`);
+    }
+    return pkg.version;
+}
 function toCamel(input) {
     return input.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -125,17 +141,9 @@ async function commandDevProxy(args) {
         rmSync(localDevDir(ctx.app), { recursive: true, force: true });
     }
     mkdirSync(localDevDir(ctx.app), { recursive: true });
-    if (ctx.assetCommand) {
+    if (ctx.asset.kind !== "none") {
         await ensureAppDependencies(ctx.root);
     }
-    const assetChild = ctx.assetCommand
-        ? spawn(ctx.assetCommand, {
-            cwd: ctx.root,
-            env: process.env,
-            shell: true,
-            stdio: "inherit",
-        })
-        : null;
     const server = createServer((request, response) => {
         handleDevRequest(ctx, request, response).catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
@@ -148,11 +156,26 @@ async function commandDevProxy(args) {
     server.on("upgrade", (request, socket, head) => {
         proxyWebSocket(ctx, request, socket, head);
     });
-    await new Promise((resolveListen, reject) => {
-        server.once("error", reject);
-        server.listen(Number(ctx.port), "127.0.0.1", resolveListen);
-    });
+    let assetProcess = null;
+    try {
+        ctx.port = await listenOnAvailablePort(server, ctx.portStart, "Railcode dev");
+        assetProcess = await startAssetDevServer(ctx);
+    }
+    catch (error) {
+        if (server.listening)
+            await closeServer(server);
+        assetProcess?.reservation?.release();
+        if (assetProcess?.child && !assetProcess.child.killed)
+            assetProcess.child.kill("SIGTERM");
+        throw error;
+    }
     const localUrl = `http://127.0.0.1:${ctx.port}`;
+    if (ctx.port !== ctx.portStart) {
+        console.log(`Port ${ctx.portStart} was busy; using ${ctx.port}.`);
+    }
+    if (ctx.assetPort && ctx.assetPortStart && ctx.assetPort !== ctx.assetPortStart) {
+        console.log(`Asset port ${ctx.assetPortStart} was busy; using ${ctx.assetPort}.`);
+    }
     printUrlBox(ctx.app, localUrl);
     console.log("");
     // Identity, KV, and files are served locally; LLM and SQL forward to the real
@@ -173,8 +196,11 @@ async function commandDevProxy(args) {
         console.log(`App root:     ${ctx.root}`);
         console.log(`KV/files:     ${localDevDir(ctx.app)}`);
         console.log(`Prod APIs:    ${ctx.apiBase ? `${ctx.apiBase}/v1` : "unconfigured"}`);
+        console.log(`Dev port:     ${ctx.port}`);
         if (ctx.assetCommand)
             console.log(`App command:  ${ctx.assetCommand}`);
+        if (ctx.assetTarget)
+            console.log(`Asset target: ${ctx.assetTarget}`);
     }
     console.log("");
     await new Promise((resolveRun) => {
@@ -186,13 +212,20 @@ async function commandDevProxy(args) {
             if (code !== 0)
                 process.exitCode = code;
             server.close();
-            if (assetChild && !assetChild.killed)
-                assetChild.kill("SIGTERM");
+            assetProcess?.reservation?.release();
+            if (assetProcess?.child && !assetProcess.child.killed)
+                assetProcess.child.kill("SIGTERM");
             resolveRun();
         };
         process.once("SIGINT", () => shutdown());
         process.once("SIGTERM", () => shutdown());
-        assetChild?.once("exit", (code) => {
+        assetProcess?.child.once("error", (error) => {
+            console.error(`App command failed to start: ${error.message}`);
+            shutdown(1);
+        });
+        assetProcess?.child.once("exit", (code) => {
+            if (closed)
+                return;
             if (code && code !== 0)
                 console.error(`App command exited with status ${code}`);
             shutdown(code || 0);
@@ -220,20 +253,21 @@ async function resolveDevContext(args) {
     }
     assertAppName(app);
     const root = resolveAppRoot(cwd, app, manifestInfo);
-    const port = stringOption(args, "port") || DEFAULT_DEV_PORT;
-    const assetPort = String(stringOption(args, "assetPort") || manifest?.dev?.port || DEFAULT_ASSET_DEV_PORT);
-    const assetCommand = stringOption(args, "command") || manifest?.dev?.command || inferAssetDevCommand(root, assetPort);
-    const assetTarget = assetCommand ? `http://127.0.0.1:${assetPort}` : undefined;
+    const portStart = parsePort(stringOption(args, "port") ?? DEFAULT_DEV_PORT, "--port");
+    const assetPortStart = parsePort(stringOption(args, "assetPort") ?? manifest?.dev?.port ?? DEFAULT_ASSET_DEV_PORT, "--asset-port");
+    const explicitAssetCommand = stringOption(args, "command") || manifest?.dev?.command;
+    const asset = resolveAssetDevConfig(root, explicitAssetCommand, assetPortStart);
     const config = loadConfig();
     const apiBase = apiOrigin(config, args);
     return {
         app,
         root,
-        port,
+        port: portStart,
+        portStart,
         apiBase,
         token: process.env.RAILCODE_API_TOKEN || config.apiToken,
-        assetCommand,
-        assetTarget,
+        asset,
+        assetPortStart: asset.kind === "none" ? undefined : assetPortStart,
     };
 }
 function readRailcodeManifest(start) {
@@ -328,18 +362,51 @@ function resolveSdkPath() {
         return sourceTree;
     throw new CliError(`Railcode SDK file not found. Expected ${bundled}`, 1);
 }
-function inferAssetDevCommand(root, port) {
+function resolveAssetDevConfig(root, explicitCommand, targetPort) {
+    if (explicitCommand)
+        return { kind: "custom", command: explicitCommand, targetPort };
     const packagePath = join(root, "package.json");
     if (!existsSync(packagePath))
-        return undefined;
+        return { kind: "none" };
     const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
     if (!pkg.scripts?.dev)
-        return undefined;
+        return { kind: "none" };
     const pm = packageManagerFor(root);
-    if (existsSync(join(root, "vite.config.ts")) || existsSync(join(root, "vite.config.js"))) {
-        return runScriptCommand(pm, "dev", `--host 127.0.0.1 --port ${port} --logLevel warn`);
+    if (isViteProject(root))
+        return { kind: "vite", packageManager: pm, startPort: targetPort };
+    return { kind: "script", command: runScriptCommand(pm, "dev"), targetPort };
+}
+function isViteProject(root) {
+    return existsSync(join(root, "vite.config.ts")) || existsSync(join(root, "vite.config.js"));
+}
+async function startAssetDevServer(ctx) {
+    if (ctx.asset.kind === "none")
+        return null;
+    let reservation;
+    if (ctx.asset.kind === "vite") {
+        reservation = await reserveAvailablePort(ctx.asset.startPort, "asset dev server");
+        ctx.assetPort = reservation.port;
+        ctx.assetCommand = runScriptCommand(ctx.asset.packageManager, "dev", `--host 127.0.0.1 --port ${reservation.port} --strictPort --logLevel warn`);
+    }
+    else {
+        ctx.assetPort = ctx.asset.targetPort;
+        ctx.assetCommand = ctx.asset.command;
     }
-    return runScriptCommand(pm, "dev");
+    ctx.assetTarget = `http://127.0.0.1:${ctx.assetPort}`;
+    return {
+        child: spawn(ctx.assetCommand, {
+            cwd: ctx.root,
+            env: {
+                ...process.env,
+                PORT: String(ctx.assetPort),
+                RAILCODE_DEV_PORT: String(ctx.port),
+                RAILCODE_ASSET_PORT: String(ctx.assetPort),
+            },
+            shell: true,
+            stdio: "inherit",
+        }),
+        reservation,
+    };
 }
 async function ensureAppDependencies(root) {
     if (!existsSync(join(root, "package.json")))
@@ -355,7 +422,7 @@ function dependenciesReady(root) {
     const nodeModules = join(root, "node_modules");
     if (!existsSync(nodeModules) || !statSync(nodeModules).isDirectory())
         return false;
-    if (existsSync(join(root, "vite.config.ts")) || existsSync(join(root, "vite.config.js"))) {
+    if (isViteProject(root)) {
         return existsSync(join(nodeModules, ".bin", process.platform === "win32" ? "vite.cmd" : "vite"));
     }
     return true;
@@ -380,6 +447,140 @@ function runScriptCommand(pm, script, passthrough = "") {
         return `yarn ${script}${suffix}`;
     return `${pm} run ${script}${passthrough ? ` -- ${passthrough}` : ""}`;
 }
+function parsePort(value, label) {
+    const port = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new CliError(`${label} must be a TCP port from 1 to 65535.`, 2);
+    }
+    return port;
+}
+async function listenOnAvailablePort(server, startPort, label) {
+    for (let port = startPort, checked = 0; port <= 65535 && checked < PORT_SEARCH_LIMIT; port += 1, checked += 1) {
+        try {
+            await listenOnPort(server, port);
+            return port;
+        }
+        catch (error) {
+            if (errorCode(error) !== "EADDRINUSE")
+                throw error;
+        }
+    }
+    throw new CliError(`${label} could not find an available port starting at ${startPort}.`, 1);
+}
+async function reserveAvailablePort(startPort, label) {
+    for (let port = startPort, checked = 0; port <= 65535 && checked < PORT_SEARCH_LIMIT; port += 1, checked += 1) {
+        const reservation = reserveRailcodePort(port);
+        if (!reservation)
+            continue;
+        try {
+            const available = await canListenOnPort(port);
+            if (available)
+                return reservation;
+        }
+        catch (error) {
+            reservation.release();
+            throw error;
+        }
+        reservation.release();
+    }
+    throw new CliError(`${label} could not find an available port starting at ${startPort}.`, 1);
+}
+async function canListenOnPort(port) {
+    const server = createServer();
+    try {
+        await listenOnPort(server, port);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "EADDRINUSE")
+            return false;
+        throw error;
+    }
+    finally {
+        if (server.listening)
+            await closeServer(server);
+    }
+}
+async function listenOnPort(server, port) {
+    await new Promise((resolveListen, rejectListen) => {
+        const cleanup = () => {
+            server.off("error", onError);
+            server.off("listening", onListening);
+        };
+        const onError = (error) => {
+            cleanup();
+            rejectListen(error);
+        };
+        const onListening = () => {
+            cleanup();
+            resolveListen();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    });
+}
+function reserveRailcodePort(port) {
+    const dir = localPortLockDir(port);
+    mkdirSync(dirname(dir), { recursive: true });
+    try {
+        mkdirSync(dir);
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST")
+            throw error;
+        if (!removeStalePortLock(dir))
+            return null;
+        try {
+            mkdirSync(dir);
+        }
+        catch (retryError) {
+            if (errorCode(retryError) === "EEXIST")
+                return null;
+            throw retryError;
+        }
+    }
+    writeJsonFile(join(dir, "owner.json"), { pid: process.pid, started_at: nowIso() });
+    let released = false;
+    return {
+        port,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            const owner = readJsonFile(join(dir, "owner.json"), {});
+            if (owner.pid === process.pid)
+                rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}
+function removeStalePortLock(dir) {
+    const owner = readJsonFile(join(dir, "owner.json"), {});
+    if (typeof owner.pid === "number" && processIsRunning(owner.pid))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+function localPortLockDir(port) {
+    return join(RAILCODE_HOME, "dev", ".ports", String(port));
+}
+function processIsRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
 async function handleDevRequest(ctx, request, response) {
     const url = new URL(request.url || "/", "http://127.0.0.1");
     if (url.pathname.startsWith("/_api/")) {
@@ -400,7 +601,11 @@ async function handleLocalApi(ctx, request, response, url) {
         return;
     }
     if (path === "/me") {
-        sendJson(response, 200, { user: "local-dev", app: ctx.app });
+        sendJson(response, 200, {
+            user: "local-dev",
+            display_name: "Local Dev",
+            app: ctx.app,
+        });
         return;
     }
     if (path === "/app-users") {
@@ -1000,13 +1205,22 @@ function escapeHtml(value) {
         .replaceAll('"', "&quot;")
         .replaceAll("'", "&#39;");
 }
+const DEPLOY_HELP = `Usage:
+  railcode deploy [--private | --public]
+
+Run from a Railcode app repo. The first deploy creates the app's access policy:
+public (anyone signed in) by default, or owner-only with --private. You can also
+set it declaratively in railcode.json: { "deploy": { "access": "private" } }.
+Redeploys keep the existing policy; change it later with railcode access.
+`;
 async function commandDeploy(args) {
     if (booleanOption(args, "help")) {
-        console.log("Usage: railcode deploy\n\nRun from a Railcode app repo.");
+        console.log(DEPLOY_HELP);
         return;
     }
     rejectDeployArgs(args);
     const ctx = resolveDeployContext();
+    const access = resolveDeployAccess(args, ctx);
     await buildApp(ctx.appRoot);
     const source = resolveDeploySource(ctx);
     const files = collectDeployFiles(source);
@@ -1015,7 +1229,7 @@ async function commandDeploy(args) {
     const apiUrl = canonicalApiOrigin(authUrl);
     let authedConfig = await ensureApiToken({ ...config, apiUrl: authUrl }, authUrl, "Deploy");
     console.log(`Uploading ${ctx.app} to ${apiUrl}...`);
-    const response = await postDeployBundle(apiUrl, authedConfig, ctx.app, files);
+    const response = await postDeployBundle(apiUrl, authedConfig, ctx.app, files, access);
     if (response.status === 401 && !process.env.RAILCODE_API_TOKEN && process.stdin.isTTY) {
         console.log("Saved login expired. Log in again to continue.");
         const retryConfig = { ...authedConfig, apiUrl: authUrl };
@@ -1024,19 +1238,46 @@ async function commandDeploy(args) {
         delete retryConfig.cookies;
         saveConfig(retryConfig);
         const freshConfig = await ensureApiToken(retryConfig, authUrl, "Deploy");
-        await handleDeployResponse(await postDeployBundle(apiUrl, freshConfig, ctx.app, files), ctx.app, apiUrl);
+        const retry = await postDeployBundle(apiUrl, freshConfig, ctx.app, files, access);
+        await handleDeployResponse(retry, ctx.app, apiUrl, access);
         return;
     }
-    await handleDeployResponse(response, ctx.app, apiUrl);
+    await handleDeployResponse(response, ctx.app, apiUrl, access);
 }
 function rejectDeployArgs(args) {
     if (args.rest.length > 0) {
         throw new CliError("railcode deploy does not take an app argument. Run it from the Railcode app directory.", 2);
     }
-    const options = Object.keys(args.options);
-    if (options.length > 0) {
-        throw new CliError("railcode deploy does not take options. Configure the Railcode URL in railcode.json or RAILCODE_API_URL.", 2);
-    }
+    const allowed = new Set(["private", "public", "help"]);
+    const unknown = Object.keys(args.options).filter((option) => !allowed.has(option));
+    if (unknown.length > 0) {
+        throw new CliError(`Unknown option for deploy: --${unknown[0]}. Configure the Railcode URL in railcode.json or RAILCODE_API_URL.`, 2);
+    }
+}
+// First-deploy access: --private/--public win over railcode.json deploy.access.
+// Returns the canonical policy mode, or undefined to let the server default.
+function resolveDeployAccess(args, ctx) {
+    const wantsPrivate = booleanOption(args, "private");
+    const wantsPublic = booleanOption(args, "public");
+    if (wantsPrivate && wantsPublic) {
+        throw new CliError("Use either --private or --public, not both.", 2);
+    }
+    if (wantsPrivate)
+        return "private";
+    if (wantsPublic)
+        return "workspace";
+    return ctx.access ? normalizeDeployAccess(ctx.access) : undefined;
+}
+function normalizeDeployAccess(value) {
+    const mode = value.trim().toLowerCase();
+    if (mode === "public" || mode === "workspace")
+        return "workspace";
+    if (mode === "private")
+        return "private";
+    if (mode === "restricted") {
+        throw new CliError("deploy.access 'restricted' is not supported at deploy. Deploy, then run railcode access restricted --users <...>.", 2);
+    }
+    throw new CliError(`Invalid deploy.access '${value}'. Use 'public' or 'private'.`, 2);
 }
 function resolveDeployContext() {
     const cwd = process.cwd();
@@ -1054,6 +1295,7 @@ function resolveDeployContext() {
         appRoot,
         workspaceRoot,
         apiUrl: manifest?.deploy?.apiUrl,
+        access: manifest?.deploy?.access,
     };
 }
 async function buildApp(appRoot) {
@@ -1145,7 +1387,7 @@ function collectDeployFiles(root) {
     }
     return files;
 }
-async function postDeployBundle(apiUrl, config, app, files) {
+async function postDeployBundle(apiUrl, config, app, files, access) {
     try {
         return await fetch(`${apiUrl}/v1/apps/${app}/deploy`, {
             method: "POST",
@@ -1153,7 +1395,7 @@ async function postDeployBundle(apiUrl, config, app, files) {
                 Authorization: `Bearer ${config.apiToken}`,
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({ files }),
+            body: JSON.stringify(access ? { files, access } : { files }),
             redirect: "manual",
         });
     }
@@ -1161,14 +1403,19 @@ async function postDeployBundle(apiUrl, config, app, files) {
         throw new CliError(`Could not reach ${apiUrl}. Configure the Railcode URL in railcode.json deploy.apiUrl or RAILCODE_API_URL. ${error instanceof Error ? error.message : String(error)}`, 1);
     }
 }
-async function handleDeployResponse(response, app, apiUrl) {
+async function handleDeployResponse(response, app, apiUrl, requestedAccess) {
     if (response.ok) {
         const body = await response.json();
         console.log(`Deployed ${app}${body.files ? ` (${body.files} files)` : ""}`);
         console.log(body.url || appUrlFromOrigin(app, apiUrl));
         const accessLabel = deployAccessLabel(body.access);
-        if (accessLabel)
+        if (accessLabel) {
             console.log(`Access: ${accessLabel}`);
+        }
+        else if (requestedAccess && body.access === "existing_policy") {
+            const word = requestedAccess === "private" ? "private" : "public";
+            console.log(`Access unchanged (${app} already exists). Run 'railcode access ${word}' to change it.`);
+        }
         return;
     }
     const text = await response.text();
@@ -1183,8 +1430,156 @@ async function handleDeployResponse(response, app, apiUrl) {
 function deployAccessLabel(access) {
     if (access === "workspace_created")
         return "public to signed-in users";
+    if (access === "private_created")
+        return "private (owner only)";
     return undefined;
 }
+const ACCESS_HELP = `Usage:
+  railcode access                                      Show the app's current access
+  railcode access public                               Anyone signed in
+  railcode access private                              Just you (the owner)
+  railcode access restricted --users a@b.com,c@d.com   Named users only
+
+Run from a Railcode app repo. Deploy the app at least once before changing access.
+Only the app owner or an admin can change it. 'public' is an alias for 'workspace'.
+`;
+// Friendly CLI words mapped to the server's canonical policy modes.
+const ACCESS_MODES = {
+    public: "workspace",
+    workspace: "workspace",
+    private: "private",
+    restricted: "restricted",
+};
+async function commandAccess(args) {
+    if (booleanOption(args, "help") || args.rest[0] === "help") {
+        console.log(ACCESS_HELP);
+        return;
+    }
+    const { method, payload } = parseAccessArgs(args);
+    const ctx = resolveDeployContext();
+    const config = loadConfig();
+    const authUrl = await resolveDeployAuthOrigin(config, ctx);
+    const apiUrl = canonicalApiOrigin(authUrl);
+    let authedConfig = await ensureApiToken({ ...config, apiUrl: authUrl }, authUrl, "Access");
+    let response = await sendAccessRequest(apiUrl, authedConfig, ctx.app, method, payload);
+    if (response.status === 401 && !process.env.RAILCODE_API_TOKEN && process.stdin.isTTY) {
+        console.log("Saved login expired. Log in again to continue.");
+        const retryConfig = { ...authedConfig, apiUrl: authUrl };
+        delete retryConfig.apiToken;
+        delete retryConfig.apiTokenPrefix;
+        delete retryConfig.cookies;
+        saveConfig(retryConfig);
+        authedConfig = await ensureApiToken(retryConfig, authUrl, "Access");
+        response = await sendAccessRequest(apiUrl, authedConfig, ctx.app, method, payload);
+    }
+    await handleAccessResponse(response, ctx.app, method);
+}
+function parseAccessArgs(args) {
+    const requested = args.rest[0];
+    if (!requested) {
+        rejectAccessOptions(args, false);
+        return { method: "GET" };
+    }
+    if (args.rest.length > 1) {
+        throw new CliError("railcode access takes a single mode argument.", 2);
+    }
+    const mode = ACCESS_MODES[requested.toLowerCase()];
+    if (!mode) {
+        throw new CliError(`Unknown access mode '${requested}'. Use public, private, or restricted.`, 2);
+    }
+    rejectAccessOptions(args, mode === "restricted");
+    const payload = { mode };
+    if (mode === "restricted") {
+        payload.members = parseMembers(args);
+        if (payload.members.length === 0) {
+            throw new CliError("restricted access needs --users <a@b.com,c@d.com> of existing Railcode users.", 2);
+        }
+    }
+    return { method: "PUT", payload };
+}
+function rejectAccessOptions(args, allowUsers) {
+    const allowed = new Set(["help"]);
+    if (allowUsers)
+        allowed.add("users");
+    const unknown = Object.keys(args.options).filter((option) => !allowed.has(option));
+    if (unknown.length > 0) {
+        const hint = unknown[0] === "users" ? " --users only applies to restricted access." : "";
+        throw new CliError(`Unknown option for access: --${unknown[0]}.${hint}`, 2);
+    }
+}
+function parseMembers(args) {
+    const raw = stringOption(args, "users");
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((member) => member.trim())
+        .filter(Boolean);
+}
+async function sendAccessRequest(apiUrl, config, app, method, payload) {
+    if (!config.apiToken) {
+        throw new CliError("Missing Railcode API token. Run from a terminal once, or set RAILCODE_API_TOKEN.", 1);
+    }
+    const headers = { Authorization: `Bearer ${config.apiToken}` };
+    if (method === "PUT")
+        headers["Content-Type"] = "application/json";
+    try {
+        return await fetch(`${apiUrl}/v1/apps/${app}/access`, {
+            method,
+            headers,
+            body: method === "PUT" ? JSON.stringify(payload) : undefined,
+            redirect: "manual",
+        });
+    }
+    catch (error) {
+        throw new CliError(`Could not reach ${apiUrl}. Configure the Railcode URL in railcode.json deploy.apiUrl or RAILCODE_API_URL. ${error instanceof Error ? error.message : String(error)}`, 1);
+    }
+}
+async function handleAccessResponse(response, app, method) {
+    if (response.ok) {
+        printAccess((await response.json()), method === "PUT");
+        return;
+    }
+    const detail = errorDetail(await response.text());
+    if (response.status === 401) {
+        throw new CliError("Access login was rejected. Run the command again to log in.", 1);
+    }
+    if (response.status === 403) {
+        throw new CliError(`Access change denied for ${app}: ${detail}. Only the app owner or an admin can change access.`, 1);
+    }
+    if (response.status === 404 || response.status === 409) {
+        throw new CliError(detail || `App ${app} not found.`, 1);
+    }
+    throw new CliError(`Access ${method === "PUT" ? "update" : "lookup"} failed (${response.status}): ${detail}`, 1);
+}
+function printAccess(body, changed) {
+    console.log(`${changed ? "Access set:" : "Access:"} ${accessModeLabel(body.mode)}`);
+    if (body.mode === "restricted" && body.members && body.members.length > 0) {
+        console.log(`Allowed: ${body.members.join(", ")}`);
+    }
+    if (body.url)
+        console.log(body.url);
+}
+function accessModeLabel(mode) {
+    if (mode === "workspace")
+        return "public (anyone signed in)";
+    if (mode === "private")
+        return "private (owner only)";
+    if (mode === "restricted")
+        return "restricted (named users only)";
+    return mode || "unknown";
+}
+function errorDetail(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.detail === "string")
+            return parsed.detail;
+    }
+    catch {
+        // Non-JSON error body; fall through to the raw text.
+    }
+    return text;
+}
 function appUrlFromOrigin(app, origin) {
     const url = new URL(origin);
     const [first, ...rest] = url.hostname.split(".");
@@ -1200,17 +1595,31 @@ function appUrlFromOrigin(app, origin) {
     return url.toString();
 }
 const DESIGN_SYSTEM_HELP = `Usage:
-  railcode design-system pull [output.md] [--output output.md]
-  railcode pull design-system [output.md] [--output output.md]
+  railcode get design-system
 
 Options:
   --api-url <url>    Railcode auth/API URL. Defaults to saved config, or prompts if missing.
-  --output <path>   Write markdown to a file instead of stdout.
+
+Compatibility aliases:
+  railcode design-system pull
+  railcode pull design-system
 `;
+async function commandGet(args) {
+    const target = args.rest[0];
+    if (target === "design-system") {
+        await commandDesignSystemGet({ ...args, rest: args.rest.slice(1) });
+        return;
+    }
+    if (!target || target === "help" || booleanOption(args, "help")) {
+        console.log(DESIGN_SYSTEM_HELP);
+        return;
+    }
+    throw new CliError(`Unknown get target: ${target}\n\n${DESIGN_SYSTEM_HELP}`, 2);
+}
 async function commandPull(args) {
     const target = args.rest[0];
     if (target === "design-system") {
-        await commandDesignSystemPull({ ...args, rest: args.rest.slice(1) });
+        await commandDesignSystemGet({ ...args, rest: args.rest.slice(1) });
         return;
     }
     if (!target || target === "help" || booleanOption(args, "help")) {
@@ -1222,7 +1631,11 @@ async function commandPull(args) {
 async function commandDesignSystem(args) {
     const subcommand = args.rest[0];
     if (subcommand === "pull") {
-        await commandDesignSystemPull({ ...args, rest: args.rest.slice(1) });
+        await commandDesignSystemGet({ ...args, rest: args.rest.slice(1) });
+        return;
+    }
+    if (subcommand === "get") {
+        await commandDesignSystemGet({ ...args, rest: args.rest.slice(1) });
         return;
     }
     if (!subcommand || subcommand === "help" || booleanOption(args, "help")) {
@@ -1231,16 +1644,16 @@ async function commandDesignSystem(args) {
     }
     throw new CliError(`Unknown design-system command: ${subcommand}\n\n${DESIGN_SYSTEM_HELP}`, 2);
 }
-async function commandDesignSystemPull(args) {
+async function commandDesignSystemGet(args) {
     if (args.rest[0] === "help" || booleanOption(args, "help")) {
         console.log(DESIGN_SYSTEM_HELP);
         return;
     }
-    rejectDesignSystemPullArgs(args);
+    rejectDesignSystemGetArgs(args);
     const config = loadConfig();
     const authUrl = await resolveDesignSystemAuthOrigin(config, args);
     const apiUrl = canonicalApiOrigin(authUrl);
-    let authedConfig = await ensureApiToken({ ...config, apiUrl: authUrl }, authUrl, "Design system pull");
+    let authedConfig = await ensureApiToken({ ...config, apiUrl: authUrl }, authUrl, "Design system get");
     let response = await getDesignSystem(apiUrl, authedConfig);
     if (response.status === 401 && !process.env.RAILCODE_API_TOKEN && process.stdin.isTTY) {
         console.log("Saved login expired. Log in again to continue.");
@@ -1249,39 +1662,27 @@ async function commandDesignSystemPull(args) {
         delete retryConfig.apiTokenPrefix;
         delete retryConfig.cookies;
         saveConfig(retryConfig);
-        authedConfig = await ensureApiToken(retryConfig, authUrl, "Design system pull");
+        authedConfig = await ensureApiToken(retryConfig, authUrl, "Design system get");
         response = await getDesignSystem(apiUrl, authedConfig);
     }
-    const designSystem = await handleDesignSystemResponse(response);
-    writeDesignSystemMarkdown(designSystem.markdown, designSystemOutput(args));
+    writeDesignSystemMarkdown(await handleDesignSystemResponse(response));
 }
-function rejectDesignSystemPullArgs(args) {
-    const allowedOptions = new Set(["apiUrl", "help", "output"]);
+function rejectDesignSystemGetArgs(args) {
+    const allowedOptions = new Set(["apiUrl", "help"]);
     const unknown = Object.keys(args.options).filter((option) => !allowedOptions.has(option));
     if (unknown.length > 0) {
-        throw new CliError(`Unknown option for design-system pull: --${unknown[0]}`, 2);
-    }
-    if (args.rest.length > 1) {
-        throw new CliError("design-system pull accepts at most one output path.", 2);
+        throw new CliError(`Unknown option for design-system get: --${unknown[0]}`, 2);
     }
-    if (args.rest.length === 1 && typeof args.options.output === "string") {
-        throw new CliError("Pass the output path either positionally or with --output, not both.", 2);
-    }
-    if (args.options.output === true) {
-        throw new CliError("--output requires a file path.", 2);
+    if (args.rest.length > 0) {
+        throw new CliError("railcode get design-system does not accept positional arguments.", 2);
     }
 }
-function designSystemOutput(args) {
-    if (typeof args.options.output === "string")
-        return args.options.output;
-    return args.rest[0];
-}
 async function resolveDesignSystemAuthOrigin(config, args) {
     const manifestApiUrl = readRailcodeManifest(process.cwd())?.manifest.deploy?.apiUrl;
     return resolveRequiredAuthOrigin({
         config,
         args,
-        action: "Design system pull",
+        action: "Design system get",
         fallbackApiUrl: manifestApiUrl,
         missingUrlHint: "Pass --api-url <url>, set deploy.apiUrl in railcode.json, or set RAILCODE_API_URL.",
     });
@@ -1302,35 +1703,30 @@ async function getDesignSystem(apiUrl, config) {
 }
 async function handleDesignSystemResponse(response) {
     if (response.ok) {
-        const body = (await response.json());
-        if (typeof body.markdown !== "string") {
-            throw new CliError("Design system response did not include markdown.", 1);
+        const text = await response.text();
+        const contentType = response.headers.get("content-type") || "";
+        if (contentType.includes("application/json")) {
+            const body = JSON.parse(text);
+            if (typeof body.markdown !== "string") {
+                throw new CliError("Design system response did not include markdown.", 1);
+            }
+            return body.markdown;
         }
-        return {
-            markdown: body.markdown,
-            updated_at: body.updated_at ?? null,
-        };
+        return text;
     }
     const text = await response.text();
     if (response.status === 401) {
-        throw new CliError("Design system pull login was rejected. Run the command again to log in.", 1);
+        throw new CliError("Design system get login was rejected. Run the command again to log in.", 1);
     }
     if (response.status === 403) {
-        throw new CliError(`Design system pull denied: ${text}`, 1);
+        throw new CliError(`Design system get denied: ${text}`, 1);
     }
-    throw new CliError(`Design system pull failed (${response.status}): ${text}`, 1);
+    throw new CliError(`Design system get failed (${response.status}): ${text}`, 1);
 }
-function writeDesignSystemMarkdown(markdown, output) {
-    if (!output || output === "-") {
-        process.stdout.write(markdown);
-        if (markdown && !markdown.endsWith("\n"))
-            process.stdout.write("\n");
-        return;
-    }
-    const path = resolve(output);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, markdown);
-    console.log(`Wrote ${relativeLabel(process.cwd(), path)}`);
+function writeDesignSystemMarkdown(markdown) {
+    process.stdout.write(markdown);
+    if (markdown && !markdown.endsWith("\n"))
+        process.stdout.write("\n");
 }
 async function commandInit(args) {
     const app = args.rest[0];