@usestatemachines/cli 0.0.0-stage → 0.1.0

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+import type { ChildResult, Io } from './io-types.js';
+export declare function main(argv: readonly string[], io: Io): Promise<number | ChildResult>;

package/dist/main.js

@@ -0,0 +1,126 @@
+import { CliError } from './errors.js';
+import { commandError, printError, printExecution, printResult, } from './output.js';
+import { parseCommand } from './parser.js';
+import { cliVersion, sdkVersion } from './version.js';
+function presentationFor(io, globals, agent) {
+    const env = io.host.environment;
+    const interactive = !globals.noInput &&
+        env.STATEMACHINES_NO_INPUT !== '1' &&
+        env.CI === undefined &&
+        agent === null &&
+        io.host.terminal === 'both';
+    return {
+        mode: interactive ? 'interactive' : 'non-interactive',
+        format: globals.format ?? (interactive ? 'text' : 'json'),
+        stream: globals.stream,
+    };
+}
+export async function main(argv, io) {
+    let presentation = presentationFor(io, {
+        profile: null,
+        workspace: null,
+        format: null,
+        noInput: false,
+        yes: false,
+        stream: false,
+    }, null);
+    let session = null;
+    let errorsToStderr = false;
+    try {
+        const { commands } = await import('./registry.js');
+        const parsed = parseCommand(argv, commands);
+        errorsToStderr =
+            parsed.kind === 'run' || (parsed.kind === 'invalid' && parsed.stderr);
+        const env = io.host.environment;
+        const fastPath = parsed.kind !== 'command' && parsed.kind !== 'run';
+        const agent = !fastPath ||
+            (io.host.terminal === 'both' &&
+                !parsed.globals.noInput &&
+                env.STATEMACHINES_NO_INPUT !== '1' &&
+                env.CI === undefined)
+            ? await io.detectAgent()
+            : null;
+        presentation = presentationFor(io, parsed.globals, agent);
+        if (parsed.kind === 'invalid') {
+            throw parsed.error;
+        }
+        if (presentation.stream && presentation.format !== 'json') {
+            throw new CliError('cli.invalid_arguments', {
+                message: 'Use --json with --stream.',
+            });
+        }
+        if (parsed.kind === 'help') {
+            const { helpDocument, helpText } = await import('./help.js');
+            await printResult(io, presentation, helpDocument(commands, parsed.command, parsed.group), () => helpText(commands, parsed.command, parsed.group));
+            return 0;
+        }
+        if (parsed.kind === 'version') {
+            const result = {
+                cli: cliVersion,
+                sdk: sdkVersion,
+                node: io.host.nodeVersion,
+            };
+            await printResult(io, presentation, result, () => `CLI ${result.cli}\nSDK ${result.sdk}\nNode ${result.node}`);
+            return 0;
+        }
+        if (parsed.kind === 'completion') {
+            const { completionScript } = await import('./help.js');
+            await io.stdout.write(`${completionScript(commands, parsed.shell)}\n`);
+            return 0;
+        }
+        if (io.signal.aborted) {
+            throw new CliError('cli.cancelled');
+        }
+        if (parsed.kind === 'run') {
+            const { createContextSession } = await import('./context.js');
+            session = await createContextSession({
+                io,
+                globals: parsed.globals,
+                presentation,
+                version: cliVersion,
+                agent,
+            });
+            const context = await session.contexts.workspace();
+            return await context.programs.run({
+                command: parsed.command,
+                args: parsed.args,
+            });
+        }
+        if (parsed.command.help.destructive && !parsed.globals.yes) {
+            if (presentation.mode !== 'interactive') {
+                throw new CliError('cli.input_required', {
+                    message: 'Add --yes to confirm this action.',
+                });
+            }
+            if (parsed.command.help.confirmation !== 'handler' &&
+                !(await io.prompt.confirm(`Continue with ${parsed.command.syntax.name.join(' ')}?`, { signal: io.signal, deadline: null }))) {
+                throw new CliError('cli.cancelled');
+            }
+        }
+        const { createContextSession } = await import('./context.js');
+        session = await createContextSession({
+            io,
+            globals: parsed.globals,
+            presentation,
+            version: cliVersion,
+            agent,
+        });
+        const exitCode = await printExecution(io, presentation, parsed.command.invoke(parsed.input, {
+            contexts: session.contexts,
+            presentation,
+        }));
+        if (!io.signal.aborted && presentation.mode === 'interactive') {
+            const { notifyUpdate } = await import('./update.js');
+            await notifyUpdate({ io, presentation, version: cliVersion, agent });
+        }
+        return exitCode;
+    }
+    catch (cause) {
+        const error = await commandError(cause, io.signal);
+        await printError(io, presentation, error, errorsToStderr);
+        return error.exitCode;
+    }
+    finally {
+        await session?.close();
+    }
+}

package/dist/native-helper.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/native-helper.js

@@ -0,0 +1,2 @@
+import { runNativeHelper } from './io.js';
+runNativeHelper();

package/dist/output.d.ts

@@ -0,0 +1,8 @@
+import type { Printable } from './command.js';
+import type { Presentation } from './context-types.js';
+import { ApiError, CliError, type ExitCode } from './errors.js';
+import type { Io } from './io-types.js';
+export declare function printResult(io: Io, presentation: Presentation, result: unknown, text: () => string): Promise<void>;
+export declare function commandError(error: unknown, signal?: AbortSignal): Promise<CliError | ApiError>;
+export declare function printError(io: Io, presentation: Presentation, error: CliError | ApiError, stderr?: boolean): Promise<void>;
+export declare function printExecution(io: Io, presentation: Presentation, events: AsyncIterable<Printable>): Promise<ExitCode>;

package/dist/output.js

@@ -0,0 +1,135 @@
+import { ApiError, CliError, normalizeError } from './errors.js';
+import { untrustedResult, untrustedText } from './text.js';
+export async function printResult(io, presentation, result, text) {
+    await io.stdout.write(`${presentation.format === 'json' ? JSON.stringify(result) : text().replace(/[\r\n]+$/u, '')}\n`);
+}
+export async function commandError(error, signal) {
+    if (error instanceof CliError && error.exitCode === 130) {
+        return error;
+    }
+    if (signal?.aborted) {
+        return new CliError('cli.cancelled');
+    }
+    if (error instanceof CliError ||
+        error instanceof ApiError ||
+        (error instanceof Error && error.name === 'AbortError')) {
+        return normalizeError(error);
+    }
+    const { StateMachinesError, EnvironmentFailedError, SnapshotFailedError, UnexpectedStatusError, WaitTimeoutError, } = await import('@usestatemachines/sdk');
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error && !seen.has(current) && seen.size < 8) {
+        seen.add(current);
+        if (current instanceof CliError || current instanceof ApiError) {
+            return current;
+        }
+        if (current instanceof WaitTimeoutError) {
+            return new CliError('cli.wait_timeout', {
+                message: current.message,
+                details: {
+                    id: current.resource?.id ?? null,
+                    status: current.resource?.status ?? null,
+                    timeoutMs: current.timeoutMs,
+                },
+            });
+        }
+        if (current instanceof EnvironmentFailedError) {
+            return new CliError('cli.resource_failed', {
+                message: current.message,
+                details: {
+                    id: current.environment.id,
+                    status: current.environment.status,
+                    failure: current.environment.failure,
+                },
+            });
+        }
+        if (current instanceof SnapshotFailedError) {
+            return new CliError('cli.resource_failed', {
+                message: current.message,
+                details: {
+                    id: current.snapshot.id,
+                    status: current.snapshot.status,
+                    failure: current.snapshot.failure,
+                },
+            });
+        }
+        if (current instanceof UnexpectedStatusError) {
+            return new CliError('cli.unexpected_status', {
+                message: current.message,
+                details: { id: current.resource.id, status: current.status },
+            });
+        }
+        if (current instanceof StateMachinesError && current.status !== null) {
+            return new ApiError({
+                status: current.status,
+                code: current.code,
+                message: current.message,
+                requestId: current.requestId,
+                details: current.fields,
+            });
+        }
+        current = current.cause;
+    }
+    if (error instanceof StateMachinesError) {
+        return new CliError('cli.network');
+    }
+    return normalizeError(error);
+}
+export async function printError(io, presentation, error, stderr = false) {
+    const destination = stderr || presentation.format === 'text' ? io.stderr : io.stdout;
+    const first = error.document.error.next[0];
+    const details = error.document.error.details;
+    if (presentation.format === 'json' &&
+        error.exitCode === 130 &&
+        details !== null &&
+        typeof details === 'object' &&
+        'resource' in details &&
+        details.resource === 'environment' &&
+        'id' in details &&
+        typeof details.id === 'string') {
+        await io.stderr.write(`Stopped waiting for environment ${untrustedText(details.id)}.${first === undefined ? '' : `\nCleanup: ${untrustedText(first.command)}`}\n`);
+    }
+    await destination.write(presentation.format === 'json'
+        ? `${JSON.stringify(error.document)}\n`
+        : `${untrustedText(error.message)}${first === undefined ? '' : `\nNext: ${untrustedText(first.command)} (${untrustedText(first.reason)})`}\n`);
+}
+export async function printExecution(io, presentation, events) {
+    let raw = false;
+    try {
+        for await (const event of events) {
+            switch (event.kind) {
+                case 'progress':
+                    if (presentation.stream) {
+                        await io.stdout.write(`${JSON.stringify(event.json)}\n`);
+                    }
+                    else if (presentation.mode === 'interactive' || event.always) {
+                        await io.stderr.write(`${event.text?.() ?? JSON.stringify(untrustedResult(event.json))}\n`);
+                    }
+                    break;
+                case 'result':
+                    await printResult(io, { ...presentation, format: event.format ?? presentation.format }, event.json, event.text);
+                    return event.exitCode;
+                case 'literal':
+                    raw = true;
+                    await io.stdout.write(event.text.endsWith('\n') ? event.text : `${event.text}\n`);
+                    return event.exitCode;
+                case 'raw':
+                    raw = true;
+                    for await (const chunk of event.response.body) {
+                        await io.stdout.write(chunk);
+                    }
+                    return event.response.status >= 200 && event.response.status < 300
+                        ? 0
+                        : event.response.status === 401
+                            ? 3
+                            : 1;
+            }
+        }
+        throw new CliError('cli.invalid_result');
+    }
+    catch (cause) {
+        const error = await commandError(cause, io.signal);
+        await printError(io, presentation, error, raw);
+        return error.exitCode;
+    }
+}

package/dist/parser.d.ts

@@ -0,0 +1,28 @@
+import type { CommandHelp, RegisteredCommand } from './command.js';
+import { type Globals } from './context-types.js';
+import { CliError } from './errors.js';
+export type ParsedCommand = {
+    readonly globals: Globals;
+} & ({
+    readonly kind: 'help';
+    readonly command: CommandHelp | null;
+    readonly group: string | null;
+} | {
+    readonly kind: 'version';
+} | {
+    readonly kind: 'invalid';
+    readonly error: CliError;
+    readonly stderr: boolean;
+} | {
+    readonly kind: 'run';
+    readonly command: string;
+    readonly args: readonly string[];
+} | {
+    readonly kind: 'completion';
+    readonly shell: 'bash' | 'zsh' | 'fish';
+} | {
+    readonly kind: 'command';
+    readonly command: RegisteredCommand;
+    readonly input: Readonly<Record<string, unknown>>;
+});
+export declare function parseCommand(argv: readonly string[], commands: readonly RegisteredCommand[]): ParsedCommand;

package/dist/parser.js

@@ -0,0 +1,250 @@
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { profileNameSchema } from './context-types.js';
+import { CliError } from './errors.js';
+import { globalFlags } from './flags.js';
+import { utilityCommands } from './help.js';
+const globalsSchema = z.strictObject({
+    profile: profileNameSchema.optional(),
+    workspace: z.string().min(1).optional(),
+    format: z.enum(['text', 'json']).optional(),
+    json: z.boolean().optional(),
+    noInput: z.boolean().optional(),
+    yes: z.boolean().optional(),
+    stream: z.boolean().optional(),
+    help: z.boolean().optional(),
+});
+function invalid(message = 'Check the command arguments with statemachines help.') {
+    throw new CliError('cli.invalid_arguments', { message });
+}
+function flagNames(flag) {
+    return flag.type === 'boolean' && flag.negatedName !== null
+        ? [flag.name, flag.negatedName]
+        : [flag.name];
+}
+function tokenize(argv, options) {
+    try {
+        return parseArgs({
+            args: [...argv],
+            options,
+            strict: false,
+            allowPositionals: true,
+            tokens: true,
+        });
+    }
+    catch {
+        return invalid();
+    }
+}
+function firstCommand(argv) {
+    for (let index = 0; index < argv.length; index++) {
+        const word = argv[index];
+        if (word === undefined) {
+            return null;
+        }
+        if (word === '--') {
+            return argv[index + 1] ?? null;
+        }
+        if (!word.startsWith('-')) {
+            return word;
+        }
+        const name = word.slice(2).split('=')[0];
+        const flag = globalFlags.find((value) => value.name === name);
+        if (flag === undefined) {
+            return null;
+        }
+        if (flag.type === 'string' && !word.includes('=')) {
+            index++;
+        }
+    }
+    return null;
+}
+export function parseCommand(argv, commands) {
+    let globals = {
+        profile: null,
+        workspace: null,
+        format: null,
+        noInput: false,
+        yes: false,
+        stream: false,
+    };
+    try {
+        const flags = [
+            ...globalFlags,
+            ...commands.flatMap((command) => command.syntax.flags),
+        ];
+        const options = {};
+        for (const flag of flags) {
+            for (const name of flagNames(flag)) {
+                const option = {
+                    type: flag.type === 'boolean' ? 'boolean' : 'string',
+                    multiple: flag.type === 'string[]',
+                };
+                if (options[name] !== undefined && options[name].type !== option.type) {
+                    throw new Error('Commands must agree on shared flag types.');
+                }
+                options[name] = {
+                    ...option,
+                    multiple: options[name]?.multiple || option.multiple,
+                    ...(flag.short === undefined || name !== flag.name
+                        ? {}
+                        : { short: flag.short }),
+                };
+            }
+        }
+        const parsed = tokenize(argv, options);
+        for (const token of parsed.tokens) {
+            if (token.kind === 'option' &&
+                token.inlineValue === true &&
+                options[token.name]?.type === 'boolean') {
+                return invalid(`--${token.name} does not take a value.`);
+            }
+        }
+        const globalValues = {};
+        for (const flag of globalFlags) {
+            if (parsed.values[flag.name] !== undefined) {
+                globalValues[flag.key] = parsed.values[flag.name];
+            }
+        }
+        const validated = globalsSchema.safeParse(globalValues);
+        if (!validated.success) {
+            return invalid();
+        }
+        const values = validated.data;
+        if (values.json && values.format === 'text') {
+            return invalid('Use either --json or --format text.');
+        }
+        globals = {
+            profile: values.profile ?? null,
+            workspace: values.workspace ?? null,
+            format: values.json ? 'json' : (values.format ?? null),
+            noInput: values.noInput ?? false,
+            yes: values.yes ?? false,
+            stream: values.stream ?? false,
+        };
+        const positionals = parsed.positionals;
+        const help = values.help || positionals[0] === 'help' || positionals.length === 0;
+        const words = positionals[0] === 'help' ? positionals.slice(1) : positionals;
+        const command = commands.find((entry) => entry.syntax.name.every((word, index) => word === words[index]));
+        const selectedHelp = command?.help ??
+            utilityCommands.find((entry) => entry.name[0] === words[0]);
+        const allowedFlags = [...globalFlags, ...(command?.syntax.flags ?? [])];
+        const seen = new Set();
+        for (const token of parsed.tokens) {
+            if (token.kind !== 'option') {
+                continue;
+            }
+            const flag = allowedFlags.find((candidate) => flagNames(candidate).includes(token.name));
+            if (flag === undefined) {
+                return invalid();
+            }
+            if (flag.type !== 'string[]' && seen.has(flag.key)) {
+                return invalid('Specify each option only once.');
+            }
+            if (flag.type !== 'boolean' &&
+                !token.inlineValue &&
+                token.value?.startsWith('-')) {
+                return invalid(`--${flag.name} needs a value. To pass a value that starts with -, use --${flag.name}=<value>.`);
+            }
+            seen.add(flag.key);
+        }
+        if (globals.workspace !== null && !selectedHelp?.acceptsWorkspace) {
+            return invalid('This command does not accept --workspace.');
+        }
+        if (globals.stream && (!command?.help.streams || help)) {
+            return invalid('This command does not support --stream.');
+        }
+        const group = command === undefined &&
+            words.length === 1 &&
+            commands.some((entry) => entry.syntax.name.length > 1 && entry.syntax.name[0] === words[0])
+            ? (words[0] ?? null)
+            : null;
+        if (group !== null) {
+            return { kind: 'help', command: null, group, globals };
+        }
+        if (help) {
+            const target = command?.help ??
+                (words.length === 1
+                    ? utilityCommands.find((entry) => entry.name[0] === words[0])
+                    : undefined);
+            if (words.length !== 0 &&
+                (target === undefined || words.length !== target.name.length)) {
+                return invalid();
+            }
+            return { kind: 'help', command: target ?? null, group: null, globals };
+        }
+        if (words.length === 1 && words[0] === 'version') {
+            return { kind: 'version', globals };
+        }
+        if (words[0] === 'run') {
+            const delimiter = parsed.tokens.find((token) => token.kind === 'option-terminator');
+            if (delimiter === undefined || positionals[0] !== 'run') {
+                return invalid('Use statemachines run -- <command> [args].');
+            }
+            const child = argv[delimiter.index + 1];
+            if (child === undefined ||
+                child.length === 0 ||
+                parsed.tokens.filter((token) => token.kind === 'positional' && token.index < delimiter.index).length !== 1) {
+                return invalid('Use statemachines run -- <command> [args].');
+            }
+            return {
+                kind: 'run',
+                globals,
+                command: child,
+                args: argv.slice(delimiter.index + 2),
+            };
+        }
+        if (words[0] === 'completion') {
+            const shell = z.enum(['bash', 'zsh', 'fish']).safeParse(words[1]);
+            if (!shell.success || words.length !== 2) {
+                return invalid('Use completion bash, completion zsh, or completion fish.');
+            }
+            return { kind: 'completion', shell: shell.data, globals };
+        }
+        if (command === undefined) {
+            return invalid();
+        }
+        const input = {};
+        const args = words.slice(command.syntax.name.length);
+        let index = 0;
+        for (const argument of command.syntax.arguments) {
+            if (argument.many) {
+                if (args.length > index) {
+                    input[argument.key] = args.slice(index);
+                }
+                index = args.length;
+            }
+            else if (args[index] !== undefined) {
+                input[argument.key] = args[index++];
+            }
+        }
+        if (index !== args.length) {
+            return invalid();
+        }
+        for (const flag of command.syntax.flags) {
+            const value = parsed.values[flag.name];
+            if (value !== undefined) {
+                input[flag.key] =
+                    flag.type !== 'string[]' && Array.isArray(value) ? value[0] : value;
+            }
+            if (flag.type === 'boolean' &&
+                flag.negatedName !== null &&
+                parsed.values[flag.negatedName] === true) {
+                input[flag.key] = false;
+            }
+        }
+        command.validate(input);
+        return { kind: 'command', command, input, globals };
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            return {
+                kind: 'invalid',
+                globals,
+                error,
+                stderr: firstCommand(argv) === 'run',
+            };
+        }
+        throw error;
+    }
+}

package/dist/program-types.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { type Account, type ApiOrigin, type WorkspaceId } from './context-types.js';
+import type { ChildResult, EffectOptions, Io } from './io-types.js';
+export declare const environmentTargetSchema: z.ZodObject<{
+    repositoryRoot: z.ZodString;
+    path: z.ZodString;
+    expectedManagedDigest: z.ZodString;
+}, z.core.$strict>;
+export type EnvironmentTarget = z.infer<typeof environmentTargetSchema>;
+export declare const envPullResultSchema: z.ZodObject<{
+    path: z.ZodString;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId", "out">;
+    keyId: z.ZodString;
+    expiresAt: z.ZodString;
+    pendingRevocation: z.ZodBoolean;
+}, z.core.$strict>;
+export type EnvPullResult = z.infer<typeof envPullResultSchema>;
+export interface EnvironmentFiles {
+    prepare(file: string, options: EffectOptions): Promise<EnvironmentTarget>;
+    write(target: EnvironmentTarget, credential: {
+        readonly key: string;
+        readonly origin: ApiOrigin;
+    }, options: EffectOptions, commit: () => Promise<void>): Promise<void>;
+    commitIfMatches(target: EnvironmentTarget, credential: {
+        readonly key: string;
+        readonly origin: ApiOrigin;
+    }, options: EffectOptions, commit: () => Promise<void>): Promise<boolean>;
+}
+export interface ProgramKeys {
+    withRunKey<Value>(input: {
+        readonly account: Extract<Account, {
+            kind: 'cli-token';
+        }>;
+        readonly workspace: WorkspaceId;
+        readonly consume: (key: string) => Promise<Value>;
+    }, options: EffectOptions): Promise<Value>;
+    pullEnvironment(input: {
+        readonly account: Extract<Account, {
+            kind: 'cli-token';
+        }>;
+        readonly workspace: WorkspaceId;
+        readonly target: EnvironmentTarget;
+    }, options: EffectOptions): Promise<EnvPullResult>;
+}
+export interface Programs {
+    run(input: {
+        readonly command: string;
+        readonly args: readonly string[];
+    }, options?: EffectOptions): Promise<ChildResult>;
+    pullEnvironment(file: string, options?: EffectOptions): Promise<EnvPullResult>;
+}
+export interface ProgramOptions {
+    readonly io: Io;
+    readonly origin: ApiOrigin;
+    readonly workspace: WorkspaceId;
+    readonly files: EnvironmentFiles;
+    readonly credential: {
+        readonly kind: 'workspace-key';
+        readonly key: string;
+    } | {
+        readonly kind: 'cli-token';
+        readonly account: Extract<Account, {
+            kind: 'cli-token';
+        }>;
+        readonly keys: ProgramKeys;
+    };
+}

package/dist/program-types.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { workspaceIdSchema, } from './context-types.js';
+export const environmentTargetSchema = z.strictObject({
+    repositoryRoot: z.string().min(1),
+    path: z.string().min(1),
+    expectedManagedDigest: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export const envPullResultSchema = z.strictObject({
+    path: z.string(),
+    workspaceId: workspaceIdSchema,
+    keyId: z.string(),
+    expiresAt: z.string(),
+    pendingRevocation: z.boolean(),
+});

package/dist/programs.d.ts

@@ -0,0 +1,2 @@
+import type { ProgramOptions, Programs } from './program-types.js';
+export declare function createPrograms(options: ProgramOptions): Programs;