@usestatemachines/cli 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,459 @@
+const loginNext = [
+    { command: 'statemachines login', reason: 'Sign in to continue.' },
+];
+const doctorNext = [
+    { command: 'statemachines doctor', reason: 'Check the local configuration.' },
+];
+export const errorCatalog = {
+    'cli.resource_failed': {
+        message: 'The resource failed.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.unexpected_status': {
+        message: 'The resource cannot reach the requested status.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.env_requires_login': {
+        message: 'Env pull needs a signed-in profile. Unset STATEMACHINES_API_KEY and sign in.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.env_path_refused': {
+        message: 'Choose an untracked, regular file inside this repository, outside Git and State metadata.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.env_invalid': {
+        message: 'The managed dotenv assignments are invalid. Fix them and try again.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.env_changed': {
+        message: 'The managed dotenv values changed during this command. Run env pull again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.git': {
+        message: 'Could not check Git file status or ignore rules. Check repository access and try again.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.child_start': {
+        message: 'Could not start the command. Check its name and PATH.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.package_install': {
+        message: 'The package manager could not install the dependencies. Check its output and run init again.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.invalid_environment_credential': {
+        message: 'STATEMACHINES_API_KEY must contain a workspace API key.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines whoami',
+                reason: 'Replace or unset STATEMACHINES_API_KEY, then check access again.',
+            },
+        ],
+    },
+    'cli.no_credential': {
+        message: 'Sign in to continue.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.credential_expired': {
+        message: 'Your credential has expired. Sign in again.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.credential_revoked': {
+        message: 'Your credential is no longer valid. Sign in again.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.profile_not_found': {
+        message: 'The selected profile has no saved session. Sign in again.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.not_linked': {
+        message: 'Choose a workspace with --workspace or link this repository.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines link',
+                reason: 'Link this repository to a workspace.',
+            },
+        ],
+    },
+    'cli.workspace_mismatch': {
+        message: 'The selected workspace does not match this credential or resource.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines whoami',
+                reason: 'Check the active credential and workspace.',
+            },
+        ],
+    },
+    'cli.organization_mismatch': {
+        message: 'The repository link belongs to a different organization.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines link --force',
+                reason: 'Replace the repository link.',
+            },
+        ],
+    },
+    'cli.origin_mismatch': {
+        message: 'The selected API origin does not match the saved credential. Sign in again.',
+        exitCode: 3,
+        retryable: false,
+        userActionRequired: true,
+        next: loginNext,
+    },
+    'cli.keychain_denied': {
+        message: 'Could not access the keychain. Check access and try again.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'STATEMACHINES_CREDENTIAL_STORE=file statemachines login',
+                reason: 'Save credentials in a protected file instead of the keychain.',
+            },
+        ],
+    },
+    'cli.keychain_timeout': {
+        message: 'The keychain did not respond in time. Check access and try again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.keychain_unavailable': {
+        message: 'The selected keychain is unavailable. Restore access before continuing.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.credential_store_mismatch': {
+        message: 'The selected credential store does not match the saved credential.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.credentials_invalid': {
+        message: 'Could not read the saved credential. Check the credential store.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.input_required': {
+        message: 'This command needs an answer. Supply the flag shown in the next command.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.invalid_arguments': {
+        message: 'The command arguments are invalid. Check the command help.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: false,
+        next: [
+            {
+                command: 'statemachines help',
+                reason: 'Check the supported arguments and flags.',
+            },
+        ],
+    },
+    'cli.path_refused': {
+        message: 'This API path is not allowed. Use the dedicated command for credentials.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: false,
+        next: [
+            {
+                command: 'statemachines logout',
+                reason: 'Revoke the active profile credential.',
+            },
+        ],
+    },
+    'cli.wait_timeout': {
+        message: 'The wait timed out. Check the current status before trying again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.config_too_new': {
+        message: 'A newer CLI wrote this configuration. Update the CLI to continue.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'npx @usestatemachines/cli@latest doctor',
+                reason: 'Check the configuration with the latest CLI.',
+            },
+        ],
+    },
+    'cli.file_not_utf8': {
+        message: 'A file is not valid UTF-8. Save it as UTF-8 and try again.',
+        exitCode: 2,
+        retryable: false,
+        userActionRequired: true,
+        next: [],
+    },
+    'cli.config_invalid': {
+        message: 'The saved configuration is invalid. Check the local configuration.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.config_locked': {
+        message: 'Another command is changing the configuration. Wait for it to finish and try again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.config_lock_invalid': {
+        message: 'Could not verify the configuration lock. Check that no other command is running.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.config_io': {
+        message: 'Could not read or save the local configuration. Check directory access.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: doctorNext,
+    },
+    'cli.login_busy': {
+        message: 'Another login is using this profile. Wait for it to finish and try again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.profile_changed': {
+        message: 'This profile changed during the command. Check the active profile and try again.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines whoami',
+                reason: 'Check the active profile before trying again.',
+            },
+        ],
+    },
+    'cli.logout_pending': {
+        message: 'Local access was removed, but revocation is pending. Revoke the CLI session in the dashboard settings.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: true,
+        next: [
+            {
+                command: 'statemachines logout',
+                reason: 'Retry the pending revocation.',
+            },
+        ],
+    },
+    'cli.network': {
+        message: 'Could not reach the API. Check the connection and try again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.invalid_response': {
+        message: 'The API returned an unexpected response. Try again.',
+        exitCode: 1,
+        retryable: true,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.invalid_result': {
+        message: 'The command returned an invalid result.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.cancelled': {
+        message: 'Command canceled.',
+        exitCode: 130,
+        retryable: false,
+        userActionRequired: false,
+        next: [],
+    },
+    'cli.internal': {
+        message: 'The command could not finish.',
+        exitCode: 1,
+        retryable: false,
+        userActionRequired: false,
+        next: [],
+    },
+};
+export class CliError extends Error {
+    code;
+    exitCode;
+    document;
+    constructor(code, options = {}) {
+        const definition = errorCatalog[code];
+        const message = options.message ?? definition.message;
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = definition.exitCode;
+        this.document = {
+            error: {
+                code,
+                message,
+                requestId: options.requestId ?? null,
+                retryable: definition.retryable,
+                next: options.next ?? definition.next,
+                userActionRequired: options.userActionRequired ?? definition.userActionRequired,
+                details: options.details ?? null,
+            },
+        };
+    }
+}
+export class ApiError extends Error {
+    status;
+    exitCode;
+    document;
+    constructor(input) {
+        super(input.message);
+        this.name = 'ApiError';
+        this.status = input.status;
+        this.exitCode = input.status === 401 ? 3 : 1;
+        this.document = {
+            error: {
+                code: input.code ?? 'cli.invalid_response',
+                message: input.message,
+                requestId: input.requestId,
+                retryable: input.status === 408 || input.status === 429 || input.status >= 500,
+                next: input.status === 401 ? loginNext : [],
+                userActionRequired: input.status === 401,
+                details: input.details,
+            },
+        };
+    }
+}
+export const keychainFailures = [
+    'cli.keychain_denied',
+    'cli.keychain_timeout',
+    'cli.keychain_unavailable',
+];
+export function failedWith(error, codes) {
+    return error instanceof CliError && codes.includes(error.document.error.code);
+}
+export function unconfirmedRevocations(count) {
+    return count === 1
+        ? {
+            problem: 'Could not confirm that 1 CLI session was revoked.',
+            remedy: 'Revoke it in the dashboard under Settings, Signed-in CLIs.',
+        }
+        : {
+            problem: `Could not confirm that ${count} CLI sessions were revoked.`,
+            remedy: 'Revoke them in the dashboard under Settings, Signed-in CLIs.',
+        };
+}
+export function withErrorDetails(error, details) {
+    const value = error.document.error;
+    return error instanceof CliError
+        ? new CliError(error.code, {
+            message: value.message,
+            requestId: value.requestId,
+            next: value.next,
+            userActionRequired: value.userActionRequired,
+            details,
+        })
+        : new ApiError({
+            status: error.status,
+            code: value.code,
+            message: value.message,
+            requestId: value.requestId,
+            details,
+        });
+}
+export function normalizeError(error) {
+    if (error instanceof CliError || error instanceof ApiError) {
+        return error;
+    }
+    if (error instanceof Error && error.name === 'AbortError') {
+        return new CliError('cli.cancelled');
+    }
+    return new CliError('cli.internal');
+}
+export function errorHelp() {
+    return Object.entries(errorCatalog).map(([code, definition]) => ({
+        code,
+        ...definition,
+    }));
+}
+export const exitCodeHelp = [
+    { code: 0, meaning: 'Success.' },
+    {
+        code: 1,
+        meaning: 'An API, network, resource, local state, or wait failed.',
+    },
+    {
+        code: 2,
+        meaning: 'Invalid arguments, a required answer, or a missing workspace link.',
+    },
+    {
+        code: 3,
+        meaning: 'A missing, expired, revoked, or origin-mismatched credential.',
+    },
+    { code: 130, meaning: 'Command canceled.' },
+];

package/dist/flags.d.ts

@@ -0,0 +1,22 @@
+export declare const globalFlags: ({
+    name: string;
+    key: string;
+    type: "string";
+    description: string;
+    short?: undefined;
+    negatedName?: undefined;
+} | {
+    name: string;
+    key: string;
+    type: "boolean";
+    negatedName: null;
+    description: string;
+    short?: undefined;
+} | {
+    name: string;
+    key: string;
+    short: string;
+    type: "boolean";
+    negatedName: null;
+    description: string;
+})[];

package/dist/flags.js

@@ -0,0 +1,56 @@
+export const globalFlags = [
+    {
+        name: 'profile',
+        key: 'profile',
+        type: 'string',
+        description: 'Use a saved profile.',
+    },
+    {
+        name: 'workspace',
+        key: 'workspace',
+        type: 'string',
+        description: 'Choose a workspace for commands that use one.',
+    },
+    {
+        name: 'format',
+        key: 'format',
+        type: 'string',
+        description: 'Print text or JSON.',
+    },
+    {
+        name: 'json',
+        key: 'json',
+        type: 'boolean',
+        negatedName: null,
+        description: 'Print JSON.',
+    },
+    {
+        name: 'no-input',
+        key: 'noInput',
+        type: 'boolean',
+        negatedName: null,
+        description: 'Run without prompts.',
+    },
+    {
+        name: 'yes',
+        key: 'yes',
+        type: 'boolean',
+        negatedName: null,
+        description: 'Confirm destructive actions.',
+    },
+    {
+        name: 'stream',
+        key: 'stream',
+        type: 'boolean',
+        negatedName: null,
+        description: 'Print progress as JSON lines on supported commands.',
+    },
+    {
+        name: 'help',
+        key: 'help',
+        short: 'h',
+        type: 'boolean',
+        negatedName: null,
+        description: 'Show command help.',
+    },
+];

package/dist/generated/internal.d.ts

@@ -0,0 +1,138 @@
+import type { StateMachinesError } from '@usestatemachines/sdk';
+export declare const parseStartLogin: (input: unknown) => {
+    publicKey: string;
+    cliVersion: string;
+    hostname: string;
+    platform: string;
+};
+export declare const parseStartedLogin: (input: unknown) => {
+    loginId: string;
+    deviceCode: string;
+    userCode: string;
+    verificationUrl: string;
+    expiresIn: number;
+    interval: number;
+};
+export declare const parseLoginToken: (input: unknown) => {
+    envelope: {
+        v: 1;
+        serverPublicKey: string;
+        nonce: string;
+        ciphertext: string;
+        tag: string;
+    };
+    tokenId: string;
+    idleExpiresAt: string;
+    expiresAt: string;
+    organization: {
+        id: string;
+        name: string;
+    };
+    user: {
+        email: string;
+    };
+};
+export declare const parsePollError: (input: unknown) => {
+    error: "access_denied" | "authorization_pending" | "expired_token" | "slow_down";
+    interval: number;
+};
+export declare const parseCollected: (input: unknown) => {
+    loginId: string;
+    status: "collected";
+};
+export declare const parseCreateKey: (input: unknown) => {
+    workspaceId: string;
+    name: string;
+    permissions: ("environments:connect" | "environments:read" | "environments:write" | "snapshots:read" | "snapshots:write")[];
+    kind?: "cli_run" | "env_pull" | undefined;
+};
+export declare const keyPolicy: {
+    permissions: ("environments:connect" | "environments:read" | "environments:write" | "snapshots:read" | "snapshots:write")[];
+    maxNameLength: number | null;
+};
+export declare const parseEnvironmentLabels: (input: unknown) => Record<string, string>;
+export declare const parseCreatedKey: (input: unknown) => {
+    apiKey: {
+        id: string;
+        workspaceId: string;
+        name: string;
+        displayValue: string;
+        permissions: ("environments:connect" | "environments:read" | "environments:write" | "snapshots:read" | "snapshots:write")[];
+        createdBy: {
+            type: "api_key" | "member" | "system";
+            id: string | null;
+            name: string | null;
+        };
+        createdAt: string;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+        kind: "cli_run" | "dashboard" | "env_pull";
+        expiresAt: string | null;
+    };
+    secret?: string | undefined;
+};
+export declare const parseKey: (input: unknown) => {
+    id: string;
+    workspaceId: string;
+    name: string;
+    displayValue: string;
+    permissions: ("environments:connect" | "environments:read" | "environments:write" | "snapshots:read" | "snapshots:write")[];
+    createdBy: {
+        type: "api_key" | "member" | "system";
+        id: string | null;
+        name: string | null;
+    };
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    kind: "cli_run" | "dashboard" | "env_pull";
+    expiresAt: string | null;
+};
+export declare const parseKeyListQuery: (input: unknown) => {
+    limit: number;
+    cursor?: string | undefined;
+    workspaceId: string;
+};
+export declare const parseKeyList: (input: unknown) => {
+    data: {
+        id: string;
+        workspaceId: string;
+        name: string;
+        displayValue: string;
+        permissions: ("environments:connect" | "environments:read" | "environments:write" | "snapshots:read" | "snapshots:write")[];
+        createdBy: {
+            type: "api_key" | "member" | "system";
+            id: string | null;
+            name: string | null;
+        };
+        createdAt: string;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+        kind: "cli_run" | "dashboard" | "env_pull";
+        expiresAt: string | null;
+    }[];
+    nextCursor: string | null;
+};
+export declare const parseTokenList: (input: unknown) => {
+    data: {
+        id: string;
+        name: string;
+        createdAt: string;
+        lastUsedAt: string | null;
+        idleExpiresAt: string;
+        expiresAt: string;
+        revokedAt: string | null;
+    }[];
+    nextCursor: string | null;
+};
+export declare const parseAgent: (input: unknown) => "claude_code" | "codex_cli" | "cursor" | "cursor-cli" | "gemini_cli" | "github-copilot" | null;
+export declare function parseApiError(input: unknown): Pick<ConstructorParameters<typeof StateMachinesError>[0], 'code' | 'message' | 'requestId' | 'fields'>;
+export declare const credentialVariables: (appName: string, actorToken: string, services: readonly {
+    id: string;
+    url: string;
+    headers: Readonly<Record<string, string>>;
+    servers?: readonly {
+        name: string;
+        url: string;
+    }[] | undefined;
+}[]) => [string, string][];