runcloud 0.1.121 → 0.1.123

package/dist/api.js

@@ -168,11 +168,12 @@ export class ApiClient {
         const contentType_ = res.headers.get('content-type') ?? '';
         return contentType_.includes('application/json') ? res.json() : res;
     }
-    async uploadForm(path, form) {
+    async uploadForm(path, form, headers = {}) {
         const res = await fetch(`${this.baseUrl}${path}`, {
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${this.token}`,
+                ...headers,
             },
             body: form,
         });

package/dist/commands/run-cloud.js

@@ -1305,13 +1305,15 @@ async function action(fn, opts = {}) {
 }
 function configureMachineReadableParseErrors(program) {
     const output = program.configureOutput();
+    const writeErrorLine = output.outputError ??
+        ((value, destination) => destination(value));
     program.configureOutput({
         ...output,
         outputError: (message, write) => {
             const rawArgs = program.rawArgs ?? [];
             const argumentsSeen = [...process.argv, ...rawArgs, ...program.args];
             if (!argumentsSeen.includes('--json')) {
-                (output.outputError ?? ((value, destination) => destination(value)))(message, write);
+                writeErrorLine(message, write);
                 return;
             }
             write(`${JSON.stringify({

package/dist/commands/sandbox.js

@@ -8,7 +8,7 @@ import { runSandboxCommand, shellCommand } from '../sandboxExec.js';
 import { runSandboxShell } from '../shellSession.js';
 import { printJson, StatusLine, style } from '../terminal.js';
 import { noteDeprecated, registerAccessCommands } from './boxAccess.js';
-import { renderSandbox, renderSandboxList, } from './sandboxOutput.js';
+import { renderHeldSecrets, renderSandbox, renderSandboxList, } from './sandboxOutput.js';
 const MAX_SANDBOX_DISK_GIB = 2048;
 const DEFAULT_SANDBOX_TIMEOUT_SECONDS = 300;
 const DEFAULT_BOX_CPU_CORES = 2;
@@ -260,6 +260,15 @@ function secretSelector(opts) {
         out.env = env;
     return out;
 }
+async function replaceSandboxSecrets(id, opts) {
+    const body = secretSelector(opts);
+    await runCloudApi().put(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`, body);
+    if (opts.json) {
+        printJson({ id, revoked: opts.noSecrets === true, ...body });
+        return;
+    }
+    console.log(opts.noSecrets ? `${id}: all secrets revoked` : `${id}: secrets replaced`);
+}
 function collectRepeatable(value, previous) {
     return [...previous, value];
 }
@@ -472,17 +481,38 @@ export function registerSandbox(program) {
             await new Promise((resolveDelay) => setTimeout(resolveDelay, opts.interval * 1_000));
         }
     }));
-    withOutput(sandbox
+    const secrets = withOutput(sandbox
         .command('secrets')
-        .description('Replace the secrets a running sandbox holds (a full replacement, not a merge)')
+        .description('Show what secrets a sandbox holds (names and origins, never values)')
+        .argument('[id]', 'sandbox id'))
+        .showHelpAfterError("hint: `runcloud sandbox secrets set <id> …` changes what a sandbox holds; the bare form only reads it");
+    const wantsJson = (opts) => Boolean(secrets.opts().json) || Boolean(opts.json);
+    secrets.action((id, opts) => run(async () => {
+        if (!id)
+            throw new Error('which sandbox? usage: runcloud sandbox secrets <id>');
+        const { held } = (await runCloudApi().get(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`));
+        if (opts.json) {
+            printJson({ held });
+            return;
+        }
+        console.log(renderHeldSecrets(id, held));
+    }));
+    withOutput(secrets
+        .command('set')
+        .description('Replace what a sandbox holds (a full replacement, not a merge)')
         .argument('<id>', 'sandbox id')
         .option('--secret-group <group>', 'attach a secret group; repeatable and ORDER MATTERS (a later group wins on a name collision)', collectRepeatable, [])
         .option('--secret <group/name>', 'attach one secret out of a group; repeatable, same ordering', collectRepeatable, [])
         .option('--env <NAME=VALUE>', 'literal value; applied last, so it wins; repeatable', collectRepeatable, [])).action((id, opts) => run(async () => {
-        const body = secretSelector(opts);
-        await runCloudApi().put(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`, body);
-        console.log(`${id}: secrets replaced`);
+        if (!opts.secretGroup.length && !opts.secret.length && !opts.env.length) {
+            throw new Error('name what the sandbox should hold with --secret-group/--secret/--env, or run `runcloud sandbox secrets revoke <id>` to take everything back');
+        }
+        await replaceSandboxSecrets(id, { ...opts, json: wantsJson(opts) });
     }));
+    withOutput(secrets
+        .command('revoke')
+        .description('Take every secret back from a sandbox')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(() => replaceSandboxSecrets(id, { noSecrets: true, json: wantsJson(opts) })));
     withOutput(sandbox
         .command('expose')
         .description('Publish a sandbox guest port at a stable hostname, or change the published port')

package/dist/commands/sandboxOutput.js

@@ -1,4 +1,24 @@
 import { formatAge, formatCpu, formatMib, formatSeconds, formatState, renderDetails, renderTable, shortDigest, style, } from '../terminal.js';
+export function renderHeldSecrets(id, held) {
+    const heading = `Secrets held by ${id}`;
+    if (held === null) {
+        return `${style.bold(heading)}\n\nUnknown — nothing was recorded for this sandbox, so what it\nholds cannot be answered from here.\n\n${style.dim('Check the environment inside it, or run `runcloud sandbox secrets set`,')}\n${style.dim('which records what it pushes.')}`;
+    }
+    if (held.length === 0) {
+        return `${style.bold(heading)}\n\nNothing. This sandbox holds no secrets.\n\n${style.dim('Attach some:')}  runcloud sandbox secrets set ${id} --secret-group <group>`;
+    }
+    return renderTable(`${heading} (${held.length})`, [
+        { key: 'name', label: 'NAME', maxWidth: 32 },
+        { key: 'kind', label: 'KIND' },
+        { key: 'source', label: 'FROM', maxWidth: 28 },
+        { key: 'digest', label: 'DIGEST' },
+    ], held.map((secret) => ({
+        name: secret.name,
+        kind: secret.kind,
+        source: secret.source,
+        digest: secret.digest,
+    })));
+}
 function resources(record) {
     const memory = formatMib(record.mem_mb);
     const disk = formatMib(record.disk_mb);

package/dist/commands/xcode.js

@@ -0,0 +1,490 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, copyFile, lstat, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+import { create as createTar } from 'tar';
+import { ApiClient, ApiError, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+const MAX_SOURCE_ARCHIVE_BYTES = 100 * 1024 * 1024;
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+function transientError(error) {
+    if (error instanceof ApiError) {
+        return error.status === 408 || error.status === 429 || error.status >= 500;
+    }
+    const cause = error?.cause ?? error;
+    const nested = typeof cause === 'object' && cause !== null && Array.isArray(cause.errors)
+        ? cause.errors[0]
+        : cause;
+    const code = nested?.code;
+    return typeof code === 'string' && [
+        'ECONNREFUSED',
+        'ECONNRESET',
+        'ENETUNREACH',
+        'EAI_AGAIN',
+        'ETIMEDOUT',
+    ].includes(code);
+}
+async function retryXcodeRequest(operation) {
+    let lastError;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (!transientError(error) || attempt === 3)
+                throw error;
+            await new Promise((resolvePromise) => setTimeout(resolvePromise, 250 * 2 ** attempt));
+        }
+    }
+    throw lastError;
+}
+function api() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
+}
+function print(value, json = false) {
+    if (json) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (!value || typeof value !== 'object') {
+        console.log(String(value));
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined && item !== null)
+            console.log(`${key}: ${typeof item === 'object' ? JSON.stringify(item) : item}`);
+    }
+}
+async function action(work) {
+    try {
+        await work();
+    }
+    catch (error) {
+        console.error(friendlyApiError(error));
+        process.exitCode = 1;
+    }
+}
+function integerFlag(value, name, minimum, maximum, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return parsed;
+}
+function repeated(value, previous) {
+    return [...previous, value];
+}
+function buildSettings(values = []) {
+    const result = {};
+    for (const value of values) {
+        const separator = value.indexOf('=');
+        if (separator < 1)
+            throw new Error(`Invalid --build-setting ${value}; expected KEY=VALUE`);
+        const key = value.slice(0, separator).trim();
+        if (Object.prototype.hasOwnProperty.call(result, key))
+            throw new Error(`Duplicate --build-setting ${key}`);
+        result[key] = value.slice(separator + 1);
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+async function base64File(path, flag) {
+    try {
+        return (await readFile(resolve(path))).toString('base64');
+    }
+    catch (error) {
+        throw new Error(`Could not read ${flag} at ${path}: ${error instanceof Error ? error.message : error}`);
+    }
+}
+function defaultExcluded(relativePath) {
+    const normalized = relativePath.replace(/\/$/, '');
+    const parts = normalized.split('/').filter(Boolean);
+    const name = parts.at(-1) ?? '';
+    if (!parts.length)
+        return false;
+    if (name === '.DS_Store' || name.endsWith('.dSYM'))
+        return true;
+    if (parts.includes('.git') || parts.includes('.runcloud-home') || parts.includes('xcuserdata'))
+        return true;
+    if (['build', '.build', 'DerivedData', 'Index.noindex', 'ModuleCache.noindex', '.index-build', '.swiftpm', 'Pods'].some((item) => parts.includes(item)))
+        return true;
+    return parts.some((part, index) => part === 'Carthage' && parts[index + 1] === 'Build');
+}
+function compilePatterns(patterns = [], flag) {
+    return patterns.map((pattern) => {
+        try {
+            return new RegExp(pattern);
+        }
+        catch (error) {
+            throw new Error(`Invalid ${flag} regular expression ${pattern}: ${error instanceof Error ? error.message : error}`);
+        }
+    });
+}
+function matches(patterns, value) {
+    return patterns.some((pattern) => {
+        pattern.lastIndex = 0;
+        return pattern.test(value);
+    });
+}
+function additionalFile(value) {
+    const separator = value.indexOf('=');
+    if (separator < 1 || separator === value.length - 1) {
+        throw new Error(`Invalid --additional-file ${value}; expected localPath=remotePath`);
+    }
+    return { localPath: value.slice(0, separator), remotePath: value.slice(separator + 1) };
+}
+function remoteAdditionalPath(value) {
+    const normalized = value.replaceAll('\\', '/');
+    const home = normalized.startsWith('~/');
+    const path = home ? normalized.slice(2) : normalized.replace(/^\.\//, '');
+    if (!path || path.startsWith('/') || /^[A-Za-z]:\//.test(path) || path.split('/').some((part) => part === '..' || !part)) {
+        throw new Error(`Additional file destination must stay inside the source or ~/ directory: ${value}`);
+    }
+    if (!home && path.split('/')[0] === '.runcloud-home') {
+        throw new Error('.runcloud-home is reserved for additional files targeting ~/');
+    }
+    return { home, path };
+}
+export async function packSource(sourcePath, flags) {
+    const root = resolve(sourcePath);
+    const rootStat = await stat(root).catch(() => null);
+    if (!rootStat?.isDirectory())
+        throw new Error(`Xcode source path is not a directory: ${sourcePath}`);
+    const temporary = await mkdtemp(join(tmpdir(), 'runcloud-xcode-'));
+    const workspace = join(temporary, 'workspace');
+    const archivePath = join(temporary, 'source.tar.gz');
+    try {
+        const gitignore = ignore();
+        const gitignoreText = await readFile(join(root, '.gitignore'), 'utf8').catch(() => '');
+        if (gitignoreText)
+            gitignore.add(gitignoreText);
+        const ignored = compilePatterns(flags.ignore, '--ignore');
+        const included = compilePatterns(flags.include, '--include');
+        await cp(root, workspace, {
+            recursive: true,
+            dereference: false,
+            preserveTimestamps: true,
+            filter: async (source) => {
+                if (source === root)
+                    return true;
+                const info = await lstat(source);
+                const relativePath = relative(root, source).split(sep).join('/');
+                const candidate = info.isDirectory() ? `${relativePath}/` : relativePath;
+                const forced = relativePath.endsWith('.xcconfig') || matches(included, candidate);
+                if (!forced && (defaultExcluded(candidate) || gitignore.ignores(candidate) || matches(ignored, candidate)))
+                    return false;
+                if (info.isSymbolicLink())
+                    throw new Error(`Xcode source archives do not follow symbolic links: ${relativePath}`);
+                return true;
+            },
+        });
+        for (const raw of flags.additionalFile ?? []) {
+            const entry = additionalFile(raw);
+            const localPath = resolve(entry.localPath);
+            const info = await stat(localPath).catch(() => null);
+            if (!info?.isFile())
+                throw new Error(`Additional file is not a regular file: ${entry.localPath}`);
+            const remote = remoteAdditionalPath(entry.remotePath);
+            const destinationRoot = resolve(workspace, remote.home ? '.runcloud-home' : '.');
+            const destination = resolve(destinationRoot, remote.path);
+            if (!destination.startsWith(`${destinationRoot}${sep}`))
+                throw new Error(`Unsafe additional file destination: ${entry.remotePath}`);
+            await mkdir(dirname(destination), { recursive: true });
+            await copyFile(localPath, destination);
+        }
+        await createTar({ cwd: workspace, file: archivePath, gzip: true, portable: true, noMtime: true }, ['.']);
+        const body = await readFile(archivePath);
+        if (body.length > MAX_SOURCE_ARCHIVE_BYTES)
+            throw new Error('Xcode source archive exceeds the 100 MiB compressed limit');
+        return {
+            body: new Uint8Array(body),
+            filename: `${basename(root) || 'source'}.tar.gz`,
+            sha256: createHash('sha256').update(body).digest('hex'),
+        };
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export async function requestFor(flags) {
+    if (flags.workspace && flags.project)
+        throw new Error('Use either --workspace or --project, not both');
+    if (flags.upload && flags.signedUploadUrl)
+        throw new Error('Use either --upload or --signed-upload-url, not both');
+    if (flags.devServerUrl && flags.configuration === 'Release')
+        throw new Error('--dev-server-url is only supported for Debug builds');
+    if ((flags.xcodegenSpec || flags.xcodegenProject || flags.xcodegenProjectRoot) &&
+        (flags.devServerUrl || flags.expoAppDir)) {
+        throw new Error('XcodeGen options cannot be combined with Expo or React Native options');
+    }
+    const manualValues = [flags.certificateP12, flags.certificatePassword, ...(flags.provisioningProfile ?? [])];
+    const hasManual = manualValues.some(Boolean);
+    if (hasManual && (!flags.certificateP12 || !flags.certificatePassword || !(flags.provisioningProfile?.length))) {
+        throw new Error('--certificate-p12, --certificate-password, and at least one --provisioning-profile are required together');
+    }
+    const hasCloud = Boolean(flags.signingMethod || flags.teamId);
+    if (hasCloud && (!flags.signingMethod || !flags.teamId || !flags.ascKeyId || !flags.ascIssuerId || !flags.ascKey)) {
+        throw new Error('--signing-method requires --team-id, --asc-key-id, --asc-issuer-id, and --asc-key');
+    }
+    if (hasManual && hasCloud)
+        throw new Error('Manual certificate signing and --signing-method are mutually exclusive');
+    const hasAscCredentials = Boolean(flags.ascKeyId || flags.ascIssuerId || flags.ascKey);
+    if (!flags.uploadToAppstore && !hasCloud && hasAscCredentials) {
+        throw new Error('App Store Connect credential flags require --signing-method or --upload-to-appstore');
+    }
+    if (!flags.uploadToAppstore && (flags.ascWaitTimeout !== undefined || flags.autoBuildNumber)) {
+        throw new Error('--asc-wait-timeout and --auto-build-number require --upload-to-appstore');
+    }
+    if (flags.uploadToAppstore && (!flags.ascKeyId || !flags.ascKey || (!hasManual && !hasCloud))) {
+        throw new Error('--upload-to-appstore requires signing plus --asc-key-id and --asc-key');
+    }
+    let sdk = flags.sdk;
+    if ((hasManual || hasCloud) && !sdk)
+        sdk = 'iphoneos';
+    if (hasManual && sdk && !['iphoneos', 'watchos'].includes(sdk))
+        throw new Error('Manual signing requires --sdk iphoneos or --sdk watchos');
+    if (hasCloud && sdk !== 'iphoneos')
+        throw new Error('Cloud signing requires --sdk iphoneos');
+    if (flags.uploadToAppstore && sdk !== 'iphoneos')
+        throw new Error('--upload-to-appstore requires --sdk iphoneos');
+    const ascPrivateKey = flags.ascKey ? await base64File(flags.ascKey, '--asc-key') : undefined;
+    const waitTimeoutSeconds = integerFlag(flags.ascWaitTimeout, '--asc-wait-timeout', 0, 1800, 0);
+    const timeoutSeconds = integerFlag(flags.timeoutSeconds, '--timeout-seconds', 1, 21600, 3600);
+    const parsedBuildSettings = buildSettings(flags.buildSetting);
+    return {
+        ...(flags.orgId ? { orgId: flags.orgId } : {}),
+        ...(flags.workspace ? { workspace: flags.workspace } : {}),
+        ...(flags.project ? { project: flags.project } : {}),
+        ...(flags.scheme ? { scheme: flags.scheme } : {}),
+        ...(sdk ? { sdk } : {}),
+        ...(flags.configuration ? { configuration: flags.configuration } : {}),
+        ...((flags.xcodegenSpec || flags.xcodegenProject || flags.xcodegenProjectRoot)
+            ? { xcodegen: {
+                    ...(flags.xcodegenSpec ? { spec: flags.xcodegenSpec } : {}),
+                    ...(flags.xcodegenProject ? { project: flags.xcodegenProject } : {}),
+                    ...(flags.xcodegenProjectRoot ? { projectRoot: flags.xcodegenProjectRoot } : {}),
+                } }
+            : {}),
+        ...((flags.devServerUrl || flags.expoAppDir)
+            ? { reactNative: {
+                    ...(flags.devServerUrl ? { devServerUrl: flags.devServerUrl } : {}),
+                    ...(flags.expoAppDir ? { expoAppDir: flags.expoAppDir } : {}),
+                } }
+            : {}),
+        ...(parsedBuildSettings ? { buildSettings: parsedBuildSettings } : {}),
+        ...(flags.gitInit ? { gitInit: true } : {}),
+        ...(hasManual
+            ? { signing: {
+                    certificateP12Base64: await base64File(flags.certificateP12, '--certificate-p12'),
+                    certificatePassword: flags.certificatePassword,
+                    provisioningProfilesBase64: await Promise.all(flags.provisioningProfile.map((file) => base64File(file, '--provisioning-profile'))),
+                } }
+            : {}),
+        ...(hasCloud
+            ? { cloudSigning: {
+                    method: flags.signingMethod,
+                    teamId: flags.teamId,
+                    apiKeyId: flags.ascKeyId,
+                    apiIssuerId: flags.ascIssuerId,
+                    apiPrivateKeyBase64: ascPrivateKey,
+                } }
+            : {}),
+        ...(flags.uploadToAppstore
+            ? { appStore: {
+                    enabled: true,
+                    apiKeyId: flags.ascKeyId,
+                    ...(flags.ascIssuerId ? { apiIssuerId: flags.ascIssuerId } : {}),
+                    apiPrivateKeyBase64: ascPrivateKey,
+                    waitTimeoutSeconds,
+                    autoIncrementBuildNumber: flags.autoBuildNumber === true,
+                } }
+            : {}),
+        ...(flags.upload ? { upload: { assetName: flags.upload } } : {}),
+        ...(flags.signedUploadUrl ? { upload: { signedUploadUrl: flags.signedUploadUrl } } : {}),
+        timeoutSeconds,
+    };
+}
+async function logChunk(client, id, offset) {
+    return await retryXcodeRequest(async () => await client.get(`/run-cloud/xcode/builds/${encodeURIComponent(id)}/logs?offset=${offset}`));
+}
+async function waitForBuild(client, id, flags) {
+    const timeout = integerFlag(flags.waitTimeout, '--wait-timeout', 1, 23400, 22500);
+    const deadline = Date.now() + timeout * 1000;
+    let offset = 0;
+    for (;;) {
+        const build = await retryXcodeRequest(async () => await client.get(`/run-cloud/xcode/builds/${encodeURIComponent(id)}`));
+        if (build.logs.available || build.status === 'queued' || build.status === 'running') {
+            const chunk = await logChunk(client, id, offset);
+            if (chunk.text)
+                (flags.json ? process.stderr : process.stdout).write(chunk.text);
+            offset = chunk.nextOffset;
+            if (TERMINAL.has(build.status) && chunk.complete)
+                return build;
+        }
+        else if (TERMINAL.has(build.status)) {
+            return build;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for Xcode build ${id}; it may still be running. Check it with runcloud xcode get ${id}.`);
+        }
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 1000));
+    }
+}
+async function downloadArtifact(client, build, output, force = false) {
+    if (!build.artifact.available)
+        throw new Error(`Artifact for Xcode build ${build.id} is not available`);
+    const target = resolve(output ?? build.artifact.filename);
+    if (existsSync(target) && !force)
+        throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+    const bytes = await retryXcodeRequest(async () => await client.getBinary(`/run-cloud/xcode/builds/${encodeURIComponent(build.id)}/artifact`));
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, bytes);
+    return target;
+}
+export function registerXcode(program) {
+    const xcode = program.command('xcode').description('Build Xcode projects on the run.cloud macOS fleet');
+    xcode
+        .command('build')
+        .description('Upload a local source tree, stream xcodebuild logs, and download its artifact')
+        .argument('[path]', 'local source directory', '.')
+        .option('--scheme <name>', 'Xcode scheme')
+        .option('--workspace <path>', 'relative .xcworkspace path')
+        .option('--project <path>', 'relative .xcodeproj path')
+        .option('--sdk <sdk>', 'iphonesimulator, iphoneos, watchsimulator, or watchos')
+        .option('--configuration <name>', 'Debug or Release')
+        .option('--xcodegen-spec <path>', 'relative XcodeGen spec path')
+        .option('--xcodegen-project <path>', 'relative XcodeGen output directory')
+        .option('--xcodegen-project-root <path>', 'relative XcodeGen project root')
+        .option('--git-init', 'initialize Git before project generation', false)
+        .option('--dev-server-url <url>', 'Debug React Native or Expo development-server URL')
+        .option('--expo-app-dir <path>', 'relative Expo app directory in a monorepo')
+        .option('--build-setting <KEY=VALUE>', 'safe Xcode build setting; repeatable', repeated, [])
+        .option('--certificate-p12 <path>', 'PKCS#12 signing certificate')
+        .option('--certificate-password <password>', 'PKCS#12 certificate password')
+        .option('--provisioning-profile <path>', 'provisioning profile; repeatable', repeated, [])
+        .option('--signing-method <method>', 'app-store-connect, release-testing, or debugging')
+        .option('--team-id <id>', 'Apple Developer team ID for cloud signing')
+        .option('--upload <filename>', 'filename for the retained run.cloud artifact')
+        .option('--signed-upload-url <url>', 'also PUT the artifact to this presigned HTTPS URL')
+        .option('--upload-to-appstore', 'upload the signed IPA to App Store Connect', false)
+        .option('--asc-key-id <id>', 'App Store Connect API key ID')
+        .option('--asc-issuer-id <id>', 'App Store Connect API issuer ID')
+        .option('--asc-key <path>', 'App Store Connect API private key (.p8)')
+        .option('--asc-wait-timeout <seconds>', 'upload acceptance compatibility value, 0 to 1800')
+        .option('--auto-build-number', 'increment the Xcode project build number before upload', false)
+        .option('--ignore <regex>', 'exclude source paths matching a regular expression; repeatable', repeated, [])
+        .option('--include <regex>', 'force-include matching source paths; repeatable', repeated, [])
+        .option('--additional-file <local=remote>', 'include an extra file; repeatable', repeated, [])
+        .option('--org-id <id>', 'organization to own the build')
+        .option('--idempotency-key <key>', 'stable key for retry-safe submission')
+        .option('--timeout-seconds <seconds>', 'remote xcodebuild timeout, max 21600', '3600')
+        .option('--wait-timeout <seconds>', 'client wait timeout, max 23400', '22500')
+        .option('--no-wait', 'return after the control plane accepts the build')
+        .option('--detach', 'alias for --no-wait; terminal state remains queryable', false)
+        .option('-o, --output <path>', 'download the artifact here after a successful build')
+        .option('--force', 'overwrite --output if it exists', false)
+        .option('--json', 'print the build record as JSON; streamed logs go to stderr', false)
+        .action((sourcePath, flags) => action(async () => {
+        const request = await requestFor(flags);
+        const source = await packSource(sourcePath, flags);
+        const archiveBuffer = new ArrayBuffer(source.body.byteLength);
+        new Uint8Array(archiveBuffer).set(source.body);
+        const form = new FormData();
+        form.append('request', JSON.stringify(request));
+        form.append('source', new Blob([archiveBuffer], { type: 'application/gzip' }), source.filename);
+        const client = api();
+        const idempotencyKey = flags.idempotencyKey ?? `xcode_${randomUUID()}`;
+        let build = await retryXcodeRequest(async () => await client.uploadForm('/run-cloud/xcode/builds', form, { 'Idempotency-Key': idempotencyKey }));
+        if (flags.detach || flags.wait === false) {
+            print(build, flags.json);
+            return;
+        }
+        if (!flags.json)
+            console.error(`Build ${build.id} accepted; streaming remote logs.`);
+        build = await waitForBuild(client, build.id, flags);
+        let artifactPath;
+        if (flags.output && build.artifact.available)
+            artifactPath = await downloadArtifact(client, build, flags.output, flags.force);
+        if (flags.json) {
+            print({ ...build, ...(artifactPath ? { artifactPath } : {}) }, true);
+        }
+        else if (build.status === 'succeeded') {
+            console.log(`Build ${build.id} succeeded (exit code ${build.result?.exitCode ?? 0}).`);
+            console.log(artifactPath
+                ? `Artifact: ${artifactPath}`
+                : `Download: runcloud xcode artifact ${build.id}`);
+        }
+        if (build.status !== 'succeeded') {
+            const reason = build.failure?.reason ?? `Remote build ended with ${build.status}`;
+            const next = build.failure?.action ?? `Inspect logs with runcloud xcode logs ${build.id}`;
+            throw new Error(`${reason}\n${next}\nBuild ID: ${build.id}`);
+        }
+    }));
+    xcode
+        .command('get')
+        .description('Show product-visible Xcode build state')
+        .argument('<id>')
+        .option('--json', 'print JSON', false)
+        .action((id, flags) => action(async () => {
+        print(await retryXcodeRequest(async () => await api().get(`/run-cloud/xcode/builds/${encodeURIComponent(id)}`)), flags.json);
+    }));
+    xcode
+        .command('list')
+        .description('List Xcode builds in an organization')
+        .option('--org-id <id>', 'organization ID')
+        .option('--limit <count>', 'maximum builds, 1 to 100', '50')
+        .option('--json', 'print JSON', false)
+        .action((flags) => action(async () => {
+        const limit = integerFlag(flags.limit, '--limit', 1, 100, 50);
+        const query = new URLSearchParams({ limit: String(limit) });
+        if (flags.orgId)
+            query.set('orgId', flags.orgId);
+        const result = await retryXcodeRequest(async () => await api().get(`/run-cloud/xcode/builds?${query}`));
+        print(flags.json ? result : result.items, flags.json);
+    }));
+    xcode
+        .command('logs')
+        .description('Read the sanitized live or retained Xcode build log')
+        .argument('<id>')
+        .option('--follow', 'wait for terminal state', false)
+        .option('--json', 'emit one JSON object per chunk', false)
+        .action((id, flags) => action(async () => {
+        const client = api();
+        let offset = 0;
+        for (;;) {
+            const chunk = await logChunk(client, id, offset);
+            if (flags.json)
+                console.log(JSON.stringify(chunk));
+            else if (chunk.text)
+                process.stdout.write(chunk.text);
+            offset = chunk.nextOffset;
+            if (!flags.follow || chunk.complete)
+                return;
+            await new Promise((resolvePromise) => setTimeout(resolvePromise, 1000));
+        }
+    }));
+    xcode
+        .command('artifact')
+        .description('Download an Xcode build artifact through the authenticated control plane')
+        .argument('<id>')
+        .option('-o, --output <path>', 'destination path')
+        .option('--force', 'overwrite an existing destination', false)
+        .action((id, flags) => action(async () => {
+        const client = api();
+        const build = await retryXcodeRequest(async () => await client.get(`/run-cloud/xcode/builds/${encodeURIComponent(id)}`));
+        console.log(await downloadArtifact(client, build, flags.output, flags.force));
+    }));
+    xcode
+        .command('cancel')
+        .description('Cancel a queued or running Xcode build')
+        .argument('<id>')
+        .option('--json', 'print JSON', false)
+        .action((id, flags) => action(async () => {
+        print(await retryXcodeRequest(async () => await api().post(`/run-cloud/xcode/builds/${encodeURIComponent(id)}/cancel`, {})), flags.json);
+    }));
+}

package/dist/run-cloud.js

@@ -6,6 +6,7 @@ import { registerRunCloud } from './commands/run-cloud.js';
 import { registerSandbox } from './commands/sandbox.js';
 import { registerSecrets } from './commands/secrets.js';
 import { registerToken } from './commands/token.js';
+import { registerXcode } from './commands/xcode.js';
 import { CLI_VERSION } from './version.js';
 const program = new Command('runcloud')
     .description('Create and control remote mobile simulators and microVM sandboxes')
@@ -15,5 +16,6 @@ registerRunCloud(program);
 registerSandbox(program);
 registerSecrets(program);
 registerToken(program);
+registerXcode(program);
 registerImage(program);
 await program.parseAsync(process.argv);

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.121';
+export const CLI_VERSION = '0.1.123';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.121",
+  "version": "0.1.123",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [
@@ -45,6 +45,8 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
+    "ignore": "^7.0.5",
+    "tar": "^7.4.3",
     "ws": "^8.21.0"
   }
 }

package/skills/run-cloud-sandboxes/SKILL.md

@@ -190,9 +190,20 @@ immediately.
 - Attach only the required groups or names with repeatable `--secret-group` and
   `--secret`. Later selectors win on name collisions; `--env` is applied last.
 - Use `--no-secrets` to state explicitly that a new sandbox needs none.
-- Treat `runcloud sandbox secrets <id> ...` as full replacement, not a merge.
-- Remember that values cannot be read back and snapshots do not contain
-  secrets.
+- Three verbs, because two of them change things:
+  - `runcloud sandbox secrets <id>` reads. Names, where each one resolved from,
+    and a digest of its value.
+  - `runcloud sandbox secrets set <id> ...` replaces. It is a
+    full replacement, not a merge: the sandbox ends up holding exactly what
+    that one command names.
+  - `runcloud sandbox secrets revoke <id>` takes everything back.
+- A listing of `Unknown` is not `Nothing`. The inventory is recorded when a
+  delivery is accepted, so a sandbox created before inventories existed has no
+  record — its secrets still work. Only `Nothing` means the sandbox is empty.
+- Values never come back, from any command. The digest exists so you can tell
+  whether the value in a sandbox is still the one its group holds; it is not
+  reversible and there is no masked form.
+- Snapshots do not contain secrets, so a restored sandbox starts with none.
 
 Inspect `runcloud secret-group --help` and `runcloud secrets --help` for the
 current non-plaintext input forms.
@@ -350,6 +361,7 @@ warm-parked and resumable is the most expensive mistake available here.
 | `pause` `resume` `stop` `archive` `restore` | as asked | a caller requested exactly this |
 | `api` `api-force` | destroyed | a caller destroyed it. `api-force` bypassed a wedged guest |
 | `health-sweep` | interrupted | the platform judged it unhealthy |
+| `host-state-reconcile` | paused | the host had already parked it and the control plane caught up. The pause happened earlier than this event says |
 | `host-reconcile` `reap-sweep` | destroyed | the platform reclaimed it |
 | `boot-failure` `placement-timeout` `request-timeout` `scheduler` | never ran | capacity or image, not the workload |
 | `image-built` `image-build-failure` | varies | an async image build finished or failed |