@cyberxon/xon 0.1.0 → 0.2.1

package/dist/cli.js

@@ -1,12 +1,25 @@
 #!/usr/bin/env node
+import path from "node:path";
 import { Command, CommanderError } from "commander";
 import { ApiClient, ApiError } from "./api-client.js";
-import { createProject } from "./project.js";
+import { createProject, readProject } from "./project.js";
 import { updateCli } from "./update.js";
+import { cancelDeploy, previewDeploy, quickDeploy, reportDeploy, resumeDeploy, startDeploy } from "./deploy.js";
+import { previewRetrieve, resumeRetrieve, startRetrieve } from "./retrieve.js";
+import { collectSourceFiles, writeSourceFiles } from "./source.js";
+import { displayOrg, loginAccessToken, loginJwt, loginSfdxUrl, loginWeb, logoutOrg, openInBrowser, openOrg } from "./org.js";
+import { clearOrgs, listOrgs } from "./org-store.js";
 const program = new Command();
 function output(value) {
     console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
 function apiClient(options) {
     const baseUrl = options.baseUrl ?? process.env.XON_BASE_URL;
     if (!baseUrl) {
@@ -14,6 +27,27 @@ function apiClient(options) {
     }
     return new ApiClient({ baseUrl, token: options.token ?? process.env.XON_TOKEN });
 }
+async function requireProjectRoot() {
+    try {
+        await readProject(".");
+    }
+    catch {
+        throw new Error("Not in a xon project directory (missing .xon/project.json). Run this inside a project created with 'xon project create'.");
+    }
+}
+async function waitForDeploy(client, status, waitSeconds) {
+    if (waitSeconds > 0 && !status.done) {
+        return resumeDeploy(client, status.id, waitSeconds);
+    }
+    return status;
+}
+const parseWait = (value) => {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        throw new Error("--wait must be a non-negative number of seconds");
+    }
+    return parsed;
+};
 program
     .name("xon")
     .description("Manage Xon projects and deployments")
@@ -28,6 +62,248 @@ project
     const root = await createProject(options.directory, name);
     console.log(`Created project ${name} in ${root}`);
 });
+const projectDeploy = project.command("deploy").description("Deploy metadata between your project and an org");
+projectDeploy
+    .command("start")
+    .description("Deploy metadata to an org from your local project")
+    .option("-d, --source-dir <dir>", "Directory of source to deploy", "src")
+    .option("-o, --target-org <org>", "Org to deploy to")
+    .option("-c, --dry-run", "Validate the deploy without applying it", false)
+    .option("-w, --wait <seconds>", "Seconds to wait for the deploy to finish (0 = don't wait)", parseWait, 0)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    await requireProjectRoot();
+    const client = apiClient(options);
+    const status = await startDeploy(client, path.resolve(options.sourceDir), {
+        targetOrg: options.targetOrg,
+        checkOnly: options.dryRun,
+    });
+    output(await waitForDeploy(client, status, options.wait));
+});
+projectDeploy
+    .command("validate")
+    .description("Validate a metadata deployment without actually executing it")
+    .option("-d, --source-dir <dir>", "Directory of source to validate", "src")
+    .option("-o, --target-org <org>", "Org to validate against")
+    .option("-w, --wait <seconds>", "Seconds to wait for validation to finish (0 = don't wait)", parseWait, 0)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    await requireProjectRoot();
+    const client = apiClient(options);
+    const status = await startDeploy(client, path.resolve(options.sourceDir), {
+        targetOrg: options.targetOrg,
+        checkOnly: true,
+    });
+    output(await waitForDeploy(client, status, options.wait));
+});
+projectDeploy
+    .command("quick")
+    .description("Quickly deploy a validated deployment to an org")
+    .requiredOption("-i, --job-id <id>", "Id of the validated deploy to promote")
+    .option("-w, --wait <seconds>", "Seconds to wait for the deploy to finish (0 = don't wait)", parseWait, 0)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const client = apiClient(options);
+    const status = await quickDeploy(client, options.jobId);
+    output(await waitForDeploy(client, status, options.wait));
+});
+projectDeploy
+    .command("report")
+    .description("Check or poll for the status of a deploy operation")
+    .requiredOption("-i, --job-id <id>", "Id of the deploy to check")
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    output(await reportDeploy(apiClient(options), options.jobId));
+});
+projectDeploy
+    .command("resume")
+    .description("Resume watching a deployment until it finishes")
+    .requiredOption("-i, --job-id <id>", "Id of the deploy to resume watching")
+    .option("-w, --wait <seconds>", "Seconds to wait for the deploy to finish", parseWait, 60)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    output(await resumeDeploy(apiClient(options), options.jobId, options.wait));
+});
+projectDeploy
+    .command("cancel")
+    .description("Cancel a deploy operation")
+    .requiredOption("-i, --job-id <id>", "Id of the deploy to cancel")
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    output(await cancelDeploy(apiClient(options), options.jobId));
+});
+projectDeploy
+    .command("preview")
+    .description("Preview deployment details for the local project source")
+    .option("-d, --source-dir <dir>", "Directory of source to preview", "src")
+    .action(async (options) => {
+    await requireProjectRoot();
+    const files = await collectSourceFiles(path.resolve(options.sourceDir));
+    console.table(previewDeploy(files));
+});
+const projectRetrieve = project.command("retrieve").description("Retrieve metadata from an org into your project");
+projectRetrieve
+    .command("start")
+    .description("Retrieve metadata from an org to your local project")
+    .option("-d, --source-dir <dir>", "Directory to write retrieved source into", "src")
+    .option("-o, --target-org <org>", "Org to retrieve from")
+    .option("-w, --wait <seconds>", "Seconds to wait for the retrieve to finish", parseWait, 60)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    await requireProjectRoot();
+    const client = apiClient(options);
+    let result = await startRetrieve(client, options.targetOrg);
+    if (options.wait > 0 && !result.done) {
+        result = await resumeRetrieve(client, result.id, options.wait);
+    }
+    if (result.success && result.files) {
+        await writeSourceFiles(path.resolve(options.sourceDir), result.files);
+        console.log(`Retrieved ${result.files.length} file(s) into ${options.sourceDir}`);
+    }
+    const { files, ...summary } = result;
+    output(summary);
+});
+projectRetrieve
+    .command("preview")
+    .description("Preview retrieval details including potential conflicts")
+    .option("-o, --target-org <org>", "Org to preview retrieval from")
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const rows = await previewRetrieve(apiClient(options), options.targetOrg);
+    console.table(rows);
+});
+const org = program.command("org").description("Manage your Salesforce org connections");
+const orgLogin = org.command("login").description("Log in to a Salesforce org");
+orgLogin
+    .command("web")
+    .description("Log in to an org using the web server flow")
+    .option("-r, --instance-url <url>", "Login/instance URL (use https://test.salesforce.com for sandboxes, or a My Domain URL)", "https://login.salesforce.com")
+    .option("-a, --alias <alias>", "Alias to save this org connection under")
+    .option("-d, --set-default", "Set this org as the default", false)
+    .option("-w, --wait <seconds>", "Seconds to wait for the browser login to complete", parseWait, 300)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const record = await loginWeb(apiClient(options), {
+        alias: options.alias,
+        setDefault: options.setDefault,
+        waitSeconds: options.wait,
+        instanceUrl: options.instanceUrl,
+    });
+    console.log(`Logged in to ${record.instanceUrl} as ${record.username} (alias: ${record.alias})`);
+});
+orgLogin
+    .command("jwt")
+    .description("Log in to an org using a JSON web token (JWT)")
+    .requiredOption("-u, --username <username>", "Username of the org")
+    .requiredOption("-i, --client-id <id>", "Connected app consumer key")
+    .requiredOption("-f, --jwt-key-file <path>", "Path to the JWT private key file")
+    .option("-r, --instance-url <url>", "Login/instance URL", "https://login.salesforce.com")
+    .option("-a, --alias <alias>", "Alias to save this org connection under")
+    .option("-d, --set-default", "Set this org as the default", false)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const record = await loginJwt(apiClient(options), options);
+    console.log(`Logged in to ${record.instanceUrl} as ${record.username} (alias: ${record.alias})`);
+});
+orgLogin
+    .command("sfdx-url")
+    .description("Authorize an org using a Salesforce DX authorization URL")
+    .option("-f, --sfdx-url-file <path>", "File containing the sfdx auth URL")
+    .option("--sfdx-url-stdin", "Read the sfdx auth URL from stdin", false)
+    .option("-a, --alias <alias>", "Alias to save this org connection under")
+    .option("-d, --set-default", "Set this org as the default", false)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const sfdxAuthUrl = options.sfdxUrlStdin
+        ? await readStdin()
+        : options.sfdxUrlFile
+            ? (await (await import("node:fs/promises")).readFile(options.sfdxUrlFile, "utf8")).trim()
+            : (() => {
+                throw new Error("Pass --sfdx-url-file <path> or --sfdx-url-stdin.");
+            })();
+    const record = await loginSfdxUrl(apiClient(options), { sfdxAuthUrl, alias: options.alias, setDefault: options.setDefault });
+    console.log(`Logged in to ${record.instanceUrl} as ${record.username} (alias: ${record.alias})`);
+});
+orgLogin
+    .command("access-token")
+    .description("Authorize an org using an existing Salesforce access token")
+    .requiredOption("-r, --instance-url <url>", "Instance URL of the org")
+    .option("-a, --alias <alias>", "Alias to save this org connection under")
+    .option("-d, --set-default", "Set this org as the default", false)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const accessToken = await readStdin();
+    if (!accessToken) {
+        throw new Error("Pipe the access token via stdin, e.g. echo $TOKEN | xon org login access-token -r <url>.");
+    }
+    const record = await loginAccessToken(apiClient(options), {
+        instanceUrl: options.instanceUrl,
+        accessToken,
+        alias: options.alias,
+        setDefault: options.setDefault,
+    });
+    console.log(`Logged in to ${record.instanceUrl} as ${record.username} (alias: ${record.alias})`);
+});
+org
+    .command("logout")
+    .description("Log out of a Salesforce org")
+    .option("-o, --target-org <org>", "Alias of the org to log out of")
+    .option("-a, --all", "Log out of all connected orgs", false)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const client = apiClient(options);
+    if (options.all) {
+        const { orgs } = await listOrgs();
+        for (const record of orgs) {
+            await logoutOrg(client, record.alias);
+            console.log(`Logged out of ${record.alias}`);
+        }
+        await clearOrgs();
+        return;
+    }
+    const record = await logoutOrg(client, options.targetOrg);
+    console.log(`Logged out of ${record.alias}`);
+});
+org
+    .command("display")
+    .description("Display information about an org")
+    .option("-o, --target-org <org>", "Alias of the org to display")
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    output(await displayOrg(apiClient(options), options.targetOrg));
+});
+org
+    .command("open")
+    .description("Open your default org, or another specified org, in a browser")
+    .option("-o, --target-org <org>", "Alias of the org to open")
+    .option("-p, --path <path>", "Path to navigate to after login")
+    .option("-r, --url-only", "Print the URL instead of opening a browser", false)
+    .option("-b, --base-url <url>", "API base URL")
+    .option("-t, --token <token>", "Bearer token")
+    .action(async (options) => {
+    const { url, org: record } = await openOrg(apiClient(options), { alias: options.targetOrg, path: options.path });
+    if (options.urlOnly) {
+        console.log(url);
+    }
+    else {
+        openInBrowser(url);
+        console.log(`Opening ${record.alias} (${record.instanceUrl})`);
+    }
+});
 program
     .command("update")
     .description("Update xon to the latest version")

package/dist/deploy.js

@@ -0,0 +1,25 @@
+import { pollJob } from "./polling.js";
+import { collectSourceFiles } from "./source.js";
+export async function startDeploy(client, sourceDir, options) {
+    const source = await collectSourceFiles(sourceDir);
+    return client.post("/deployRequests", {
+        source,
+        targetOrg: options.targetOrg,
+        checkOnly: options.checkOnly ?? false,
+    });
+}
+export async function reportDeploy(client, id) {
+    return client.get(`/deployRequests/${encodeURIComponent(id)}`);
+}
+export async function resumeDeploy(client, id, waitSeconds) {
+    return pollJob(client, `/deployRequests/${encodeURIComponent(id)}`, { waitSeconds });
+}
+export async function cancelDeploy(client, id) {
+    return client.post(`/deployRequests/${encodeURIComponent(id)}/cancel`, undefined);
+}
+export async function quickDeploy(client, id) {
+    return client.post(`/deployRequests/${encodeURIComponent(id)}/quickDeploy`, undefined);
+}
+export function previewDeploy(files) {
+    return files.map((file) => ({ path: file.path, action: "Add" }));
+}

package/dist/org-store.js

@@ -0,0 +1,56 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const storeDir = path.join(os.homedir(), ".xon");
+const storePath = path.join(storeDir, "orgs.json");
+async function readStore() {
+    try {
+        const contents = await readFile(storePath, "utf8");
+        return JSON.parse(contents);
+    }
+    catch {
+        return { orgs: {} };
+    }
+}
+async function writeStore(data) {
+    await mkdir(storeDir, { recursive: true });
+    await writeFile(storePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+export async function saveOrg(record, setDefault) {
+    const data = await readStore();
+    data.orgs[record.alias] = record;
+    if (setDefault || !data.defaultOrg) {
+        data.defaultOrg = record.alias;
+    }
+    await writeStore(data);
+}
+export async function removeOrg(alias) {
+    const data = await readStore();
+    delete data.orgs[alias];
+    if (data.defaultOrg === alias) {
+        delete data.defaultOrg;
+    }
+    await writeStore(data);
+}
+export async function clearOrgs() {
+    const data = await readStore();
+    const removed = Object.values(data.orgs);
+    await writeStore({ orgs: {} });
+    return removed;
+}
+export async function getOrg(alias) {
+    const data = await readStore();
+    const key = alias ?? data.defaultOrg;
+    if (!key) {
+        throw new Error("No target org specified and no default org is set. Pass -o/--target-org or run 'xon org login' with --set-default.");
+    }
+    const record = data.orgs[key];
+    if (!record) {
+        throw new Error(`No org connection found for '${key}'. Run 'xon org login' to connect it.`);
+    }
+    return record;
+}
+export async function listOrgs() {
+    const data = await readStore();
+    return { orgs: Object.values(data.orgs), defaultOrg: data.defaultOrg };
+}

package/dist/org.js

@@ -0,0 +1,78 @@
+import { exec } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { getOrg, removeOrg, saveOrg } from "./org-store.js";
+export function openInBrowser(url) {
+    const command = process.platform === "darwin"
+        ? `open "${url}"`
+        : process.platform === "win32"
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    exec(command);
+}
+async function finishLogin(response, alias, setDefault) {
+    const record = {
+        alias: alias ?? response.username,
+        orgId: response.orgId,
+        username: response.username,
+        instanceUrl: response.instanceUrl,
+        connectedAt: new Date().toISOString(),
+    };
+    await saveOrg(record, setDefault);
+    return record;
+}
+export async function loginWeb(client, options) {
+    const { loginId, authUrl } = await client.post("/orgs/login/web", {
+        instanceUrl: options.instanceUrl,
+    });
+    openInBrowser(authUrl);
+    console.log(`Opening browser to complete login. If it didn't open, visit:\n${authUrl}`);
+    const deadline = Date.now() + options.waitSeconds * 1000;
+    let result = await client.get(`/orgs/login/${encodeURIComponent(loginId)}`);
+    while (!result.done && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        result = await client.get(`/orgs/login/${encodeURIComponent(loginId)}`);
+    }
+    if (!result.done || !result.orgId || !result.username || !result.instanceUrl) {
+        throw new Error("Timed out waiting for the browser login to complete.");
+    }
+    return finishLogin(result, options.alias, options.setDefault);
+}
+export async function loginJwt(client, options) {
+    const privateKey = await readFile(options.jwtKeyFile, "utf8");
+    const response = await client.post("/orgs/login/jwt", {
+        username: options.username,
+        clientId: options.clientId,
+        instanceUrl: options.instanceUrl,
+        privateKey,
+    });
+    return finishLogin(response, options.alias, options.setDefault);
+}
+export async function loginSfdxUrl(client, options) {
+    const response = await client.post("/orgs/login/sfdx-url", { sfdxAuthUrl: options.sfdxAuthUrl });
+    return finishLogin(response, options.alias, options.setDefault);
+}
+export async function loginAccessToken(client, options) {
+    const response = await client.post("/orgs/login/access-token", {
+        instanceUrl: options.instanceUrl,
+        accessToken: options.accessToken,
+    });
+    return finishLogin(response, options.alias, options.setDefault);
+}
+export async function logoutOrg(client, alias) {
+    const record = await getOrg(alias);
+    await client.post(`/orgs/${encodeURIComponent(record.alias)}/logout`, undefined);
+    await removeOrg(record.alias);
+    return record;
+}
+export async function displayOrg(client, alias) {
+    const record = await getOrg(alias);
+    const remote = await client.get(`/orgs/${encodeURIComponent(record.alias)}`);
+    return { ...record, ...remote };
+}
+export async function openOrg(client, options) {
+    const record = await getOrg(options.alias);
+    const { url } = await client.post(`/orgs/${encodeURIComponent(record.alias)}/frontDoorUrl`, {
+        path: options.path,
+    });
+    return { url, org: record };
+}

package/dist/polling.js

@@ -0,0 +1,10 @@
+export async function pollJob(client, path, options) {
+    const interval = options.intervalMs ?? 2000;
+    const deadline = Date.now() + options.waitSeconds * 1000;
+    let status = await client.get(path);
+    while (!status.done && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        status = await client.get(path);
+    }
+    return status;
+}

package/dist/retrieve.js

@@ -0,0 +1,11 @@
+import { pollJob } from "./polling.js";
+export async function startRetrieve(client, targetOrg) {
+    return client.post("/retrieveRequests", { targetOrg });
+}
+export async function resumeRetrieve(client, id, waitSeconds) {
+    return pollJob(client, `/retrieveRequests/${encodeURIComponent(id)}`, { waitSeconds });
+}
+export async function previewRetrieve(client, targetOrg) {
+    const query = targetOrg ? `?targetOrg=${encodeURIComponent(targetOrg)}` : "";
+    return client.get(`/retrieveRequests/preview${query}`);
+}

package/dist/source.js

@@ -0,0 +1,28 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function collectSourceFiles(sourceDir) {
+    const files = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const relative = path.relative(sourceDir, fullPath).split(path.sep).join("/");
+                const content = await readFile(fullPath);
+                files.push({ path: relative, content: content.toString("base64") });
+            }
+        }
+    }
+    await walk(sourceDir);
+    return files;
+}
+export async function writeSourceFiles(sourceDir, files) {
+    for (const file of files) {
+        const target = path.join(sourceDir, ...file.path.split("/"));
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, Buffer.from(file.content, "base64"));
+    }
+}

package/dist/update.js

@@ -1,10 +1,16 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 function packageRoot() {
     const dist = path.dirname(fileURLToPath(import.meta.url));
     return path.dirname(dist);
 }
+async function packageName(root) {
+    const contents = await readFile(path.join(root, "package.json"), "utf8");
+    return JSON.parse(contents).name;
+}
 function run(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: "inherit" });
@@ -35,14 +41,14 @@ function captureOutput(command, args, cwd) {
 }
 export async function updateCli() {
     const root = packageRoot();
-    let status;
-    try {
-        status = await captureOutput("git", ["status", "--porcelain"], root);
-    }
-    catch {
-        throw new Error(`xon isn't installed from a git checkout at ${root}, so it can't self-update. ` +
-            "Reinstall following the README instructions.");
+    if (!existsSync(path.join(root, ".git"))) {
+        const name = await packageName(root);
+        console.log(`Updating ${name} via npm...`);
+        await run("npm", ["install", "-g", `${name}@latest`], root);
+        console.log(`${name} is up to date.`);
+        return;
     }
+    const status = await captureOutput("git", ["status", "--porcelain"], root);
     if (status.trim().length > 0) {
         throw new Error(`xon has local changes in ${root}. Commit or stash them before updating.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberxon/xon",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A CLI for Xon projects and deployments",
   "type": "module",
   "license": "UNLICENSED",