hotcodepush 0.0.1 → 0.1.0

package/dist/config/consts.js

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+// Each SDK is installed from the pkg.pr.new build of one commit until its package is published.
+export const CAPACITOR_PACKAGE_NAME = '@hotcodepush/capacitor-live-updates';
+export const CAPACITOR_PACKAGE_SPEC = 'https://pkg.pr.new/hotcodepush-team/capacitor-live-updates/@hotcodepush/capacitor-live-updates@a97c157';
+export const CLI_CLIENT_ID = 'hotcodepush-cli';
+export const CORDOVA_PACKAGE_NAME = '@hotcodepush/cordova-code-push';
+export const CORDOVA_PACKAGE_SPEC = 'https://pkg.pr.new/hotcodepush-team/cordova-code-push/@hotcodepush/cordova-code-push@087f83e';
+export const CLIENT_HEADER_NAME = 'X-HotCodePush-Client';
+// The build writes the completion scripts to dist/completion, beside dist/config.
+export const COMPLETION_DIRECTORY_PATH = fileURLToPath(new URL('../completion/', import.meta.url));
+export const CONFIG_DIRECTORY_NAME = 'hotcodepush';
+export const CONFIG_FILE_NAME = 'config.json';
+export const DEFAULT_API_URL = 'https://api.hotcodepush.com';
+export const DOCS_URL = 'https://hotcodepush.com/docs';
+export const ERRORS_DOCS_URL = 'https://hotcodepush.com/docs/cli/errors';
+export const EXPO_PACKAGE_NAME = '@hotcodepush/expo-ota-updates';
+export const EXPO_PACKAGE_SPEC = 'https://pkg.pr.new/hotcodepush-team/expo-ota-updates/@hotcodepush/expo-ota-updates@0219169';
+export const INIT_MANUAL_STEP = 'Run "hotcodepush init".';
+export const ISSUES_URL = 'https://github.com/hotcodepush-team/cli/issues';
+export const KEYRING_ACCOUNT_NAME = 'token';
+export const KEYRING_SERVICE_NAME = 'hotcodepush-cli';
+export const PACKAGE_JSON = createRequire(import.meta.url)('../../package.json');
+// Our reverse proxy to the PostHog EU host.
+export const POSTHOG_HOST = 'https://hotcodepush.com/ingest';
+export const POSTHOG_PROJECT_KEY = PACKAGE_JSON.telemetry?.posthogProjectKey ?? '';
+export const PROJECT_CONFIG_FILE_NAME = 'hotcodepush.json';
+export const REACT_NATIVE_PACKAGE_NAME = '@hotcodepush/react-native-code-push';
+export const REACT_NATIVE_PACKAGE_SPEC = 'https://pkg.pr.new/hotcodepush-team/react-native-code-push/@hotcodepush/react-native-code-push@56112dd';
+export const SENTRY_DSN = PACKAGE_JSON.telemetry?.sentryDsn ?? '';
+export const SIGNING_PRIVATE_KEY_FILE_NAME = 'hotcodepush-private-key.pem';
+export const USER_AGENT = `hotcodepush-cli/${PACKAGE_JSON.version}`;

package/dist/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { PACKAGE_JSON } from './config/consts.js';
+import { commandRegistry } from './registry.js';
+import { runCli } from './utils/cli.js';
+process.exitCode = await runCli(commandRegistry, process.argv.slice(2), PACKAGE_JSON);

package/dist/registry.js

@@ -0,0 +1,83 @@
+// Lazy imports, so a command line loads only the module it runs.
+export const commandRegistry = {
+    'app create': () => import('./commands/app/create.js'),
+    'app delete': () => import('./commands/app/delete.js'),
+    'app get': () => import('./commands/app/get.js'),
+    'app list': () => import('./commands/app/list.js'),
+    'app transfer': () => import('./commands/app/transfer.js'),
+    'app update': () => import('./commands/app/update.js'),
+    'audience get': () => import('./commands/audience/get.js'),
+    'audit-log list': () => import('./commands/audit-log/list.js'),
+    'binary create': () => import('./commands/binary/create.js'),
+    'binary get': () => import('./commands/binary/get.js'),
+    'binary list': () => import('./commands/binary/list.js'),
+    'bundle delete': () => import('./commands/bundle/delete.js'),
+    'bundle get': () => import('./commands/bundle/get.js'),
+    'bundle list': () => import('./commands/bundle/list.js'),
+    'bundle upload': () => import('./commands/bundle/upload.js'),
+    'channel create': () => import('./commands/channel/create.js'),
+    'channel delete': () => import('./commands/channel/delete.js'),
+    'channel get': () => import('./commands/channel/get.js'),
+    'channel list': () => import('./commands/channel/list.js'),
+    'channel pause': () => import('./commands/channel/pause.js'),
+    'channel resume': () => import('./commands/channel/resume.js'),
+    'channel update': () => import('./commands/channel/update.js'),
+    'checkout create': () => import('./commands/checkout/create.js'),
+    'completion': () => import('./commands/completion.js'),
+    'customer-portal-session create': () => import('./commands/customer-portal-session/create.js'),
+    'device delete': () => import('./commands/device/delete.js'),
+    'device get': () => import('./commands/device/get.js'),
+    'device list': () => import('./commands/device/list.js'),
+    'device probe': () => import('./commands/device/probe.js'),
+    'doctor': () => import('./commands/doctor.js'),
+    'fingerprint': () => import('./commands/fingerprint.js'),
+    'fingerprint diff': () => import('./commands/fingerprint/diff.js'),
+    'init': () => import('./commands/init.js'),
+    'invitation accept': () => import('./commands/invitation/accept.js'),
+    'invitation create': () => import('./commands/invitation/create.js'),
+    'invitation delete': () => import('./commands/invitation/delete.js'),
+    'invitation list': () => import('./commands/invitation/list.js'),
+    'limit list': () => import('./commands/limit/list.js'),
+    'login': () => import('./commands/login.js'),
+    'logout': () => import('./commands/logout.js'),
+    'member delete': () => import('./commands/member/delete.js'),
+    'member get': () => import('./commands/member/get.js'),
+    'member list': () => import('./commands/member/list.js'),
+    'member update': () => import('./commands/member/update.js'),
+    'open': () => import('./commands/open.js'),
+    'organization create': () => import('./commands/organization/create.js'),
+    'organization delete': () => import('./commands/organization/delete.js'),
+    'organization get': () => import('./commands/organization/get.js'),
+    'organization list': () => import('./commands/organization/list.js'),
+    'organization update': () => import('./commands/organization/update.js'),
+    'release create': () => import('./commands/release/create.js'),
+    'release get': () => import('./commands/release/get.js'),
+    'release list': () => import('./commands/release/list.js'),
+    'release pause': () => import('./commands/release/pause.js'),
+    'release resume': () => import('./commands/release/resume.js'),
+    'release revoke': () => import('./commands/release/revoke.js'),
+    'release rollback': () => import('./commands/release/rollback.js'),
+    'release rollout': () => import('./commands/release/rollout.js'),
+    'release update': () => import('./commands/release/update.js'),
+    'resource-file write': () => import('./commands/resource-file/write.js'),
+    'signing-key add': () => import('./commands/signing-key/add.js'),
+    'signing-key create': () => import('./commands/signing-key/create.js'),
+    'signing-key delete': () => import('./commands/signing-key/delete.js'),
+    'signing-key list': () => import('./commands/signing-key/list.js'),
+    'sso-provider delete': () => import('./commands/sso-provider/delete.js'),
+    'sso-provider get': () => import('./commands/sso-provider/get.js'),
+    'sso-provider set': () => import('./commands/sso-provider/set.js'),
+    'sso-provider verify': () => import('./commands/sso-provider/verify.js'),
+    'statistics get': () => import('./commands/statistics/get.js'),
+    'usage get': () => import('./commands/usage/get.js'),
+    'usage list': () => import('./commands/usage/list.js'),
+    'webhook create': () => import('./commands/webhook/create.js'),
+    'webhook delete': () => import('./commands/webhook/delete.js'),
+    'webhook get': () => import('./commands/webhook/get.js'),
+    'webhook list': () => import('./commands/webhook/list.js'),
+    'webhook test': () => import('./commands/webhook/test.js'),
+    'webhook update': () => import('./commands/webhook/update.js'),
+    'webhook-delivery list': () => import('./commands/webhook-delivery/list.js'),
+    'webhook-delivery redeliver': () => import('./commands/webhook-delivery/redeliver.js'),
+    'whoami': () => import('./commands/whoami.js'),
+};

package/dist/utils/api-client.js

@@ -0,0 +1,17 @@
+import { HotCodePush } from '@hotcodepush/node';
+import { PACKAGE_JSON, USER_AGENT } from '../config/consts.js';
+import { NotLoggedInError } from './errors.js';
+import { readToken } from './token-store.js';
+import { readApiUrl } from './user-config.js';
+export function createApiClient() {
+    const token = readToken();
+    if (token === undefined) {
+        throw new NotLoggedInError();
+    }
+    return new HotCodePush({
+        baseUrl: readApiUrl(),
+        client: `cli/${PACKAGE_JSON.version}`,
+        token,
+        userAgent: USER_AGENT,
+    });
+}

package/dist/utils/audience.js

@@ -0,0 +1,9 @@
+export function resolveAudienceText(audience, channelName, rolloutPercent) {
+    const reachText = `reaches ${resolveCountText(audience.reachedDeviceCount)} of ${resolveCountText(audience.deviceCount)} active devices in ${channelName}`;
+    return rolloutPercent === 100
+        ? reachText
+        : `${reachText}; about ${resolveCountText(audience.estimatedDeviceCount)} at a ${rolloutPercent} percent rollout`;
+}
+function resolveCountText(count) {
+    return count.toLocaleString('en-US');
+}

package/dist/utils/auth-client.js

@@ -0,0 +1,35 @@
+import { createAuthClient } from 'better-auth/client';
+import { deviceAuthorizationClient } from 'better-auth/client/plugins';
+import { CLIENT_HEADER_NAME, PACKAGE_JSON, USER_AGENT, } from '../config/consts.js';
+import { resolveApiError } from './error-mapping.js';
+import { NotLoggedInError } from './errors.js';
+import { readApiUrl } from './user-config.js';
+// The bearer is sent only when given, since a stale stored token would fail the login that replaces it.
+// The User-Agent names the CLI because the session row keeps that header, not the client header.
+export function createApiAuthClient(token) {
+    return createAuthClient({
+        baseURL: `${readApiUrl()}/v1/auth`,
+        fetchOptions: {
+            auth: token === undefined ? undefined : { token, type: 'Bearer' },
+            headers: {
+                'User-Agent': USER_AGENT,
+                [CLIENT_HEADER_NAME]: `cli/${PACKAGE_JSON.version}`,
+            },
+        },
+        plugins: [deviceAuthorizationClient()],
+    });
+}
+// An API token has no session, so it counts as not logged in.
+export async function fetchSession(authClient) {
+    const session = resolveResponseData(await authClient.getSession());
+    if (session === null) {
+        throw new NotLoggedInError();
+    }
+    return session;
+}
+export function resolveResponseData(response) {
+    if (response.error !== null) {
+        throw resolveApiError(response.error);
+    }
+    return response.data;
+}

package/dist/utils/boolean-flag.js

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+// A bare flag arrives as true and `--protected false` as a string, so both forms are accepted.
+export const booleanFlagSchema = z.union([z.boolean(), z.stringbool()]);

package/dist/utils/browser.js

@@ -0,0 +1,6 @@
+import open from 'open';
+// Failures are ignored, since the command always prints the URL too.
+// A headless machine or a missing `xdg-open` opens no browser.
+export async function openBrowser(url) {
+    await open(url).catch(() => undefined);
+}

package/dist/utils/build-step.js

@@ -0,0 +1,104 @@
+import { resolve } from 'node:path';
+import { HotCodePushError } from '@hotcodepush/node';
+import { z } from 'zod';
+import { PROJECT_CONFIG_FILE_NAME } from '../config/consts.js';
+import { collectBundleFiles } from './bundle-files.js';
+import { isOfflineBuild } from './environment.js';
+import { InvalidParameterError } from './errors.js';
+import { readFingerprint } from './fingerprint.js';
+import { assertMissingParameter, detectFramework, resolveInputDirectoryPath, } from './framework.js';
+import { resolveFrameworkModule } from './frameworks/index.js';
+import { omitNativeGlue } from './frameworks/native-glue.js';
+import { resolveDeviceHosts } from './hosts.js';
+import { assertProjectConfigAppId, ID_SCHEMA, locateProjectConfig, resolveProjectChannel, } from './project-config.js';
+import { promptSelect } from './prompts.js';
+import { buildResourceFile, writeResourceFile } from './resource-file.js';
+import { fetchChannels, fetchResourceId } from './resource-resolution.js';
+import { readToken } from './token-store.js';
+import { readApiUrl } from './user-config.js';
+const PLATFORMS = ['android', 'ios'];
+export const buildStepShape = {
+    embeddedBundlePath: z
+        .string()
+        .optional()
+        .describe("The directory of the embedded bundle, the files the build puts into the app; the framework's build output by default."),
+    platform: z
+        .enum(PLATFORMS)
+        .optional()
+        .describe('The platform being built, ios or android.'),
+    resourceFilePath: z
+        .string()
+        .optional()
+        .describe('Where the resource file goes, in the app the build makes.'),
+};
+// Read in the order a failure should name them.
+// The embedded bundle leaves out the native glue, so its manifest matches a release of the same web build.
+export async function readBuildStep(options) {
+    const { directoryPath, projectConfig } = locateProjectConfig(options.config);
+    const completeProjectConfig = assertProjectConfig(projectConfig);
+    const platform = options.platform ??
+        (await promptSelect('--platform', 'Which platform?', PLATFORMS.map(platform => ({ label: platform, value: platform })), options));
+    const framework = resolveFrameworkModule(detectFramework(directoryPath));
+    const embeddedBundlePath = await resolveInputDirectoryPath({ ...options, path: options.embeddedBundlePath }, '--embedded-bundle-path', directoryPath, framework);
+    const embeddedFiles = framework.collectEmbeddedFiles === undefined
+        ? omitNativeGlue(await collectBundleFiles(embeddedBundlePath), framework.nativeGluePaths ?? [])
+        : await framework.collectEmbeddedFiles(platform, embeddedBundlePath);
+    const resourceFilePath = resolve(assertMissingParameter(options.resourceFilePath, '--resource-file-path'));
+    return {
+        channelReference: resolveChannelReference(completeProjectConfig),
+        embeddedFiles,
+        fingerprint: await readFingerprint(directoryPath, completeProjectConfig.extraFingerprintPaths ?? []),
+        platform,
+        projectConfig: completeProjectConfig,
+        resourceFilePath,
+    };
+}
+// An id needs no API, but only the API can resolve a name.
+export function resolveChannelIdByShape(channelReference) {
+    return ID_SCHEMA.safeParse(channelReference.reference).success
+        ? channelReference.reference
+        : null;
+}
+export function fetchChannelId(hotCodePush, { channelReference, projectConfig }) {
+    return fetchResourceId('channel', channelReference.reference, () => fetchChannels(hotCodePush, projectConfig.appId), channelReference.source);
+}
+export function resolveOfflineCause() {
+    if (isOfflineBuild()) {
+        return 'offline-switch';
+    }
+    return readToken() === undefined ? 'no-token' : undefined;
+}
+export function resolveFailureText(error) {
+    if (error instanceof HotCodePushError) {
+        return `${error.code} ${error.message}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+export function writeBuildResourceFile({ fingerprint, platform, projectConfig, resourceFilePath }, channelId, embeddedBundle) {
+    writeResourceFile(resourceFilePath, buildResourceFile({
+        builtAt: new Date().toISOString(),
+        channelId,
+        embeddedBundle,
+        fingerprint,
+        hosts: resolveDeviceHosts(readApiUrl()),
+        platform,
+        projectConfig,
+    }));
+}
+function assertProjectConfig(projectConfig) {
+    if (projectConfig?.appId === undefined) {
+        throw new InvalidParameterError('The project has no hotcodepush.json with an appId.', 'Run "hotcodepush init", or pass the file with --config.');
+    }
+    assertProjectConfigAppId(projectConfig.appId);
+    return { ...projectConfig, appId: projectConfig.appId };
+}
+// A build flavour sets `HOTCODEPUSH_CHANNEL` to override the channel of hotcodepush.json.
+function resolveChannelReference(projectConfig) {
+    const flavourChannel = process.env.HOTCODEPUSH_CHANNEL;
+    return flavourChannel
+        ? { reference: flavourChannel, source: 'HOTCODEPUSH_CHANNEL' }
+        : {
+            reference: resolveProjectChannel(projectConfig),
+            source: PROJECT_CONFIG_FILE_NAME,
+        };
+}

package/dist/utils/bundle-files.js

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { InvalidParameterError } from './errors.js';
+const DEAD_LINK_ERROR_CODES = new Set(['ELOOP', 'ENOENT']);
+export async function collectBundleFiles(directoryPath) {
+    await assertDirectory(directoryPath);
+    const filePaths = await collectFilePaths(directoryPath, new Set());
+    const collectedFiles = await Promise.all(filePaths
+        .map(filePath => ({
+        filePath,
+        path: relative(directoryPath, filePath).split(sep).join('/'),
+    }))
+        .filter(({ path }) => isShipped(path))
+        .map(async ({ filePath, path }) => ({
+        filePath,
+        path,
+        sha256: await computeFileSha256(filePath),
+        sizeBytes: (await stat(filePath)).size,
+    })));
+    return collectedFiles.sort((a, b) => a.path.localeCompare(b.path));
+}
+// The manifest names files by this hash, and the upload path uses it too.
+export async function computeFileSha256(filePath) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(filePath), hash);
+    return hash.digest('hex');
+}
+// Source maps belong in the error tracker and dotfiles are tooling, so neither ships to devices.
+export function isShipped(path) {
+    return (!path.endsWith('.map') &&
+        !path.split('/').some(segment => segment.startsWith('.')));
+}
+async function assertDirectory(directoryPath) {
+    const isDirectory = await stat(directoryPath)
+        .then(stats => stats.isDirectory())
+        .catch(() => false);
+    if (!isDirectory) {
+        throw new InvalidParameterError(`The directory ${directoryPath} from --path does not exist.`);
+    }
+}
+// Follows links like a web server, so the bundle carries what the native build copies through a link.
+// A link back into a directory the walk is inside ends there instead of looping.
+async function collectFilePaths(directoryPath, ancestorRealPaths) {
+    const realDirectoryPath = await realpath(directoryPath);
+    if (ancestorRealPaths.has(realDirectoryPath)) {
+        return [];
+    }
+    const walkedRealPaths = new Set([...ancestorRealPaths, realDirectoryPath]);
+    const entryNames = await readdir(directoryPath);
+    const collectedFilePaths = await Promise.all(entryNames.map(async (entryName) => {
+        const entryPath = join(directoryPath, entryName);
+        const stats = await readEntryStats(entryPath);
+        if (stats?.isDirectory()) {
+            return collectFilePaths(entryPath, walkedRealPaths);
+        }
+        return stats?.isFile() ? [entryPath] : [];
+    }));
+    return collectedFilePaths.flat();
+}
+function isDeadLinkError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        DEAD_LINK_ERROR_CODES.has(error.code));
+}
+// A link that points nowhere or to itself has no content to serve.
+async function readEntryStats(entryPath) {
+    try {
+        return await stat(entryPath);
+    }
+    catch (error) {
+        if (isDeadLinkError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/dist/utils/bundle-resolution.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { InvalidParameterError } from './errors.js';
+import { fetchAllPages } from './pagination.js';
+import { ID_SCHEMA } from './project-config.js';
+import { promptSelect } from './prompts.js';
+const NUMBER_PATTERN = /^\d+$/;
+export const bundleOptionShape = {
+    bundle: z.string().optional().describe('The bundle, by its number or id.'),
+};
+export async function fetchBundle(hotCodePush, appId, options) {
+    const bundleId = await fetchBundleId(hotCodePush, appId, options);
+    return hotCodePush.apps.bundles.get({ appId, bundleId });
+}
+// A bundle that a binary ships is never in this list.
+export function fetchUploadedBundles(hotCodePush, appId) {
+    return fetchAllPages(page => hotCodePush.apps.bundles.list({ appId, ...page, source: 'upload' }));
+}
+// A bundle that a binary ships has no number, so it reads `embedded · 1.4.2`.
+export function resolveBundleLabel({ number, version, }) {
+    return `${number === null ? 'embedded' : `#${number}`} · ${version}`;
+}
+async function fetchBundleId(hotCodePush, appId, options) {
+    if (options.bundle === undefined) {
+        const bundles = await fetchUploadedBundles(hotCodePush, appId);
+        return promptSelect('--bundle', 'Which bundle?', bundles.map(bundle => ({
+            label: `${resolveBundleLabel(bundle)} (${bundle.status})`,
+            value: bundle.id,
+        })), options);
+    }
+    if (ID_SCHEMA.safeParse(options.bundle).success) {
+        return options.bundle;
+    }
+    if (!NUMBER_PATTERN.test(options.bundle)) {
+        throw new InvalidParameterError(`The value "${options.bundle}" of --bundle is neither a number nor an id.`);
+    }
+    return fetchBundleIdByNumber(hotCodePush, appId, Number(options.bundle));
+}
+// The list search matches numbers that contain the given one, so the exact match is picked here.
+async function fetchBundleIdByNumber(hotCodePush, appId, number) {
+    const searchedBundles = await fetchAllPages(page => hotCodePush.apps.bundles.list({ appId, ...page, query: String(number) }));
+    const numberedBundle = searchedBundles.find(candidate => candidate.number === number);
+    if (numberedBundle === undefined) {
+        throw new InvalidParameterError(`The app has no bundle #${number} from --bundle.`);
+    }
+    return numberedBundle.id;
+}

package/dist/utils/channel-fields.js

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { booleanFlagSchema } from './boolean-flag.js';
+import { DURATION_PATTERN, resolveDurationMilliseconds } from './duration.js';
+import { InvalidParameterError } from './errors.js';
+import { resolveNullableField } from './nullable-field.js';
+// The plan pins these defaults. The API and the console carry the same constant.
+export const FAILURE_POLICY_DEFAULTS = {
+    failureAction: 'pause',
+    failureMinimumUpdateCount: 50,
+    failureThresholdPercent: 5,
+};
+export const failurePolicyShape = {
+    failureAction: z
+        .enum(['none', 'notify', 'pause', 'revoke'])
+        .optional()
+        .describe('What auto-pause does when a release fails too often: pause, revoke, notify or none.'),
+    failureMinimumUpdateCount: z.coerce
+        .number()
+        .int()
+        .optional()
+        .describe('The applied updates a release needs before auto-pause judges it.'),
+    failureThresholdPercent: z.coerce
+        .number()
+        .int()
+        .optional()
+        .describe('The failure percentage at which auto-pause acts.'),
+};
+export const channelFieldsShape = {
+    discoverable: booleanFlagSchema
+        .optional()
+        .describe("Whether the app's setChannel finds the channel by its name; pass false to turn it off."),
+    expiresAt: z
+        .string()
+        .optional()
+        .describe('When the preview channel expires, an ISO 8601 timestamp; not on protected or default channels.'),
+    expiresIn: z
+        .string()
+        .regex(DURATION_PATTERN, 'Expected a number of days or hours such as 14d or 12h')
+        .optional()
+        .describe('How long until the preview channel expires, 14d or 12h.'),
+    ...failurePolicyShape,
+    protected: booleanFlagSchema
+        .optional()
+        .describe('Whether only Owners and Admins change what the channel serves; pass false to turn it off.'),
+};
+export const channelFieldsClearShape = {
+    clearExpiresAt: z
+        .boolean()
+        .optional()
+        .describe('Sets the expiry back to null: the channel never expires.'),
+    ...resolveFailurePolicyClearShape('the default policy applies'),
+};
+export const releaseFailurePolicyClearShape = resolveFailurePolicyClearShape("the channel's value applies");
+export function resolveChannelFields(options) {
+    return {
+        expiresAt: resolveExpiresAt(options),
+        ...resolveFailurePolicy(options),
+        isDiscoverable: options.discoverable,
+        isProtected: options.protected,
+    };
+}
+// Each field falls back from its own value to the channel, then to the default.
+export function resolveEffectiveFailurePolicy(ownFields, channelFields) {
+    return {
+        failureAction: resolveEffectiveFailurePolicyValue(ownFields.failureAction, channelFields?.failureAction, FAILURE_POLICY_DEFAULTS.failureAction),
+        failureMinimumUpdateCount: resolveEffectiveFailurePolicyValue(ownFields.failureMinimumUpdateCount, channelFields?.failureMinimumUpdateCount, FAILURE_POLICY_DEFAULTS.failureMinimumUpdateCount),
+        failureThresholdPercent: resolveEffectiveFailurePolicyValue(ownFields.failureThresholdPercent, channelFields?.failureThresholdPercent, FAILURE_POLICY_DEFAULTS.failureThresholdPercent),
+    };
+}
+export function resolveFailurePolicy(options) {
+    return {
+        failureAction: resolveNullableField(options.failureAction, options.clearFailureAction, 'failure-action'),
+        failureMinimumUpdateCount: resolveNullableField(options.failureMinimumUpdateCount, options.clearFailureMinimumUpdateCount, 'failure-minimum-update-count'),
+        failureThresholdPercent: resolveNullableField(options.failureThresholdPercent, options.clearFailureThresholdPercent, 'failure-threshold-percent'),
+    };
+}
+// An inherited value names its level, such as `5% (channel)` or `pause (default)`.
+export function resolveFailurePolicyDetails({ failureAction, failureMinimumUpdateCount, failureThresholdPercent, }) {
+    return [
+        [
+            'Failure threshold',
+            resolveEffectiveFailurePolicyText(`${failureThresholdPercent.value}%`, failureThresholdPercent.level),
+        ],
+        [
+            'Failure minimum update count',
+            resolveEffectiveFailurePolicyText(String(failureMinimumUpdateCount.value), failureMinimumUpdateCount.level),
+        ],
+        [
+            'Failure action',
+            resolveEffectiveFailurePolicyText(failureAction.value, failureAction.level),
+        ],
+    ];
+}
+function resolveEffectiveFailurePolicyText(valueText, level) {
+    return level === 'own' ? valueText : `${valueText} (${level})`;
+}
+function resolveEffectiveFailurePolicyValue(ownValue, channelValue, defaultValue) {
+    if (ownValue !== null) {
+        return { level: 'own', value: ownValue };
+    }
+    if (channelValue !== null && channelValue !== undefined) {
+        return { level: 'channel', value: channelValue };
+    }
+    return { level: 'default', value: defaultValue };
+}
+function resolveExpiresAt({ clearExpiresAt, expiresAt, expiresIn, }) {
+    if (expiresIn === undefined) {
+        return resolveNullableField(expiresAt, clearExpiresAt, 'expires-at');
+    }
+    if (expiresAt !== undefined) {
+        throw new InvalidParameterError('The flags --expires-in and --expires-at were passed together.', 'Pass only one of them.');
+    }
+    return resolveNullableField(new Date(Date.now() + resolveDurationMilliseconds(expiresIn)).toISOString(), clearExpiresAt, 'expires-in', 'clear-expires-at');
+}
+function resolveFailurePolicyClearShape(nullMeaning) {
+    return {
+        clearFailureAction: z
+            .boolean()
+            .optional()
+            .describe(`Sets the action back to null: ${nullMeaning}.`),
+        clearFailureMinimumUpdateCount: z
+            .boolean()
+            .optional()
+            .describe(`Sets the minimum update count back to null: ${nullMeaning}.`),
+        clearFailureThresholdPercent: z
+            .boolean()
+            .optional()
+            .describe(`Sets the threshold back to null: ${nullMeaning}.`),
+    };
+}

package/dist/utils/cli.js

@@ -0,0 +1,75 @@
+import { stripVTControlCharacters } from 'node:util';
+import { defineConfig, processConfig } from 'zodline';
+import { loadCommands, resolveInvocation } from './command-registry.js';
+import { isColorEnabled } from './environment.js';
+import { printError, resolveCliError } from './error-mapping.js';
+import { ExitCode, ReportedFailureError } from './errors.js';
+import { printTelemetryNotice, reportFinishedCommand } from './telemetry.js';
+import { printUpdateNotice, refreshLatestKnownVersion, } from './update-notice.js';
+export async function runCli(commandRegistry, argv, meta) {
+    if (isShellStartup(argv)) {
+        const { cliError } = await runCommandLine(commandRegistry, argv, meta);
+        printCommandLineError(cliError, argv);
+        return cliError?.exitCode ?? ExitCode.Success;
+    }
+    const startedAt = performance.now();
+    printTelemetryNotice();
+    // The check runs beside the command, so the notice after it never waits long on the registry.
+    const latestKnownVersionRefresh = refreshLatestKnownVersion();
+    const { cliError, commandName } = await runCommandLine(commandRegistry, argv, meta);
+    printCommandLineError(cliError, argv);
+    if (commandName !== undefined) {
+        await reportFinishedCommand({
+            cliError,
+            commandName,
+            durationMs: performance.now() - startedAt,
+        });
+    }
+    await latestKnownVersionRefresh;
+    printUpdateNotice();
+    return cliError?.exitCode ?? ExitCode.Success;
+}
+// A shell profile runs `completion` at startup, so it must not wait on the network or print a notice.
+function isShellStartup(argv) {
+    return argv[0] === 'completion';
+}
+function printCommandLineError(cliError, argv) {
+    if (cliError !== undefined && !(cliError instanceof ReportedFailureError)) {
+        printError(cliError, {
+            isJson: argv.includes('--json'),
+            isVerbose: argv.includes('--verbose'),
+        });
+    }
+}
+async function runCommandLine(commandRegistry, argv, meta) {
+    let commandName;
+    try {
+        const invocation = resolveInvocation(Object.keys(commandRegistry), argv);
+        // A line without a command shows the help or the version, and zodline ends the process there.
+        commandName =
+            invocation.commandNames.length === 1
+                ? invocation.commandNames[0]
+                : undefined;
+        const commands = await loadCommands(commandRegistry, invocation.commandNames);
+        const config = defineConfig({ commands, meta });
+        const { args, command, options } = isColorEnabled(process.stdout)
+            ? processConfig(config, invocation.argv)
+            : processConfigWithoutColor(config, invocation.argv);
+        await command.action(options, args);
+        return { cliError: undefined, commandName };
+    }
+    catch (error) {
+        return { cliError: resolveCliError(error), commandName };
+    }
+}
+// zodline always colours its help, so the colour codes are stripped while it runs.
+function processConfigWithoutColor(config, argv) {
+    const log = console.log;
+    console.log = (...values) => log(...values.map(value => typeof value === 'string' ? stripVTControlCharacters(value) : value));
+    try {
+        return processConfig(config, argv);
+    }
+    finally {
+        console.log = log;
+    }
+}