automate.ax 0.1.3

package/dist/cli/utils.d.ts

@@ -0,0 +1,291 @@
+import { type TextOptions } from "@clack/prompts";
+import { z, type ZodType } from "zod";
+import { authClient } from "./lib/auth-client.js";
+import { type ConfigDirMatch } from "./lib/config-dir.js";
+export declare const SESSION_PATH: string;
+export declare const REASONABLE_NAME_SCHEMA: z.ZodString;
+export declare const ORG_OPT: {
+    org: {
+        type: "string";
+        description: string;
+        alias: string[];
+    };
+};
+export declare const API_KEY_OPT: {
+    key: {
+        type: "string";
+        description: string;
+        alias: string[];
+    };
+};
+export declare const PROJECT_OPT: {
+    project: {
+        type: "string";
+        description: string;
+        alias: string[];
+    };
+};
+export declare const CLI_PREFIX: string;
+/** Reads and validates the saved CLI session token. */
+export declare function loadSavedTokenSync(): string | null;
+/**
+ * Persists the session token to disk for use by subsequent CLI commands.
+ *
+ * @param token - Bearer token to save.
+ */
+export declare function saveTokenSync(token: string): void;
+/** Removes the saved CLI session token. */
+export declare function clearSavedTokenSync(): void;
+/**
+ * Makes an option nullable only when the CLI can ask for it interactively.
+ *
+ * @param schema - Schema for the option's explicit value.
+ * @param optionName - Human-readable option name used in validation errors.
+ */
+export declare function promptableOption<T extends z.ZodType>(schema: T, optionName?: string): z.ZodPrefault<z.ZodNullable<T>>;
+/**
+ * Runs an interactive prompt and handles cancellation consistently.
+ *
+ * @param promptFactory - Function that starts the prompt.
+ * @param optionName - Explicit option users can pass in non-interactive mode.
+ * @throws {Error} When prompting is unavailable.
+ */
+export declare function safelyPrompt<T>(promptFactory: () => Promise<T | symbol>, optionName?: string): Promise<T>;
+/**
+ * Prompts for text, displays schema validation errors, and parses the result.
+ *
+ * @param promptOptions - Text prompt labels and defaults.
+ * @param schema - Schema used to validate and transform the response.
+ * @param optionName - Explicit option users can pass instead of prompting.
+ */
+export declare function safelyPromptTextWithValidation<T extends ZodType>(promptOptions: TextOptions, schema: T, optionName?: string): Promise<z.output<T>>;
+/**
+ * Converts an error into the CLI's stable JSON error envelope.
+ *
+ * @param error - Error to serialize.
+ */
+export declare function formatJsonError(error: unknown): {
+    error: {
+        formErrors: string[];
+        fieldErrors: {};
+        message: string;
+    };
+} | {
+    error: {
+        message: string;
+    };
+};
+/**
+ * Writes a serialized CLI error to stderr.
+ *
+ * @param error - Error to serialize and write.
+ */
+export declare function writeJsonError(error: unknown): void;
+export declare const output: {
+    normal: (printFn: () => unknown) => /*elided*/ any;
+    json: (value: unknown) => /*elided*/ any;
+};
+export interface UseSessionOptions {
+    /** If true, will sign in anonymously if not signed in. Defaults to true. */
+    signInAnonymously?: boolean;
+}
+type UseSessionReturnType = Awaited<ReturnType<typeof authClient.getSession>>;
+/**
+ * Reads the current session without creating an anonymous fallback.
+ *
+ * @param opts - Session options with anonymous sign-in disabled.
+ */
+export declare function useSession(opts: UseSessionOptions & {
+    signInAnonymously: false;
+}): Promise<UseSessionReturnType>;
+/**
+ * Reads the current session, creating an anonymous one when necessary.
+ *
+ * @param opts - Session options allowing anonymous sign-in.
+ */
+export declare function useSession(opts?: UseSessionOptions & {
+    signInAnonymously?: true;
+}): Promise<NonNullable<UseSessionReturnType>>;
+/** Session identity accepted by the CLI banner. */
+type SessionArg = {
+    user: {
+        email: string;
+        isAnonymous?: boolean | null | undefined;
+    };
+} | null | undefined;
+/**
+ * Prints the CLI banner and current authentication identity.
+ *
+ * @param session - Session whose identity should be displayed.
+ * @param options - Intro display options.
+ * @param options.skipAnonWarning - Whether to suppress the anonymous-user
+ *   warning.
+ */
+export declare function sessionIntro(session: SessionArg, { skipAnonWarning }?: {
+    skipAnonWarning?: boolean;
+}): void;
+/**
+ * Requires a real user session. Anonymous sessions can bootstrap local flows,
+ * but organization management needs an authenticated account.
+ *
+ * @param action - User-facing action that requires authentication.
+ * @throws {Error} When the current user is signed out or anonymous.
+ */
+export declare function requireAuthenticatedSession(action: string): Promise<import("./lib/auth-client").CliAuthSession>;
+/** Shared schema fragment for commands that operate on an organization. */
+export declare const orgOptsSchema: z.ZodObject<{
+    org: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Shared schema fragment for commands that select an organization API key. */
+export declare const apiKeyOptsSchema: z.ZodObject<{
+    org: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OrgList = {
+    id: string;
+    name: string;
+    plan?: string | null;
+}[];
+export interface UseOrganizationOptions {
+    /** What to do when the current user belongs to no organizations. */
+    whenEmpty?: "error" | "prompt-create" | "create";
+}
+/**
+ * Resolves an organization from CLI flags or interactive prompt. Precedence:
+ * `--org` flag > auto-select (single org) > prompt. Callers opt into inline
+ * creation so destructive/update flows don't create empty organizations.
+ *
+ * @param opts - Parsed organization CLI options.
+ * @param options - Empty-organization behavior options.
+ * @param options.whenEmpty - Behavior when the user belongs to no
+ *   organizations.
+ */
+export declare function useOrganization(opts: z.infer<typeof orgOptsSchema>, { whenEmpty }?: UseOrganizationOptions): Promise<{
+    id: string;
+    name: string;
+}>;
+/**
+ * Resolves an API key owned by an organization from `--key` or an interactive
+ * prompt.
+ *
+ * @param organizationId - Organization whose API keys may be selected.
+ * @param opts - Parsed API key selector.
+ */
+export declare function useOrganizationApiKey(organizationId: string, opts: z.infer<typeof apiKeyOptsSchema>): Promise<{
+    id: string;
+    name: string | null;
+    start: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date | null;
+}>;
+/**
+ * Selects an existing organization without offering creation.
+ *
+ * @param organizations - Organizations available for selection.
+ * @param options - Prompt options with creation disabled.
+ * @param options.allowCreate - Disables inline organization creation.
+ */
+export declare function promptOrg<T extends {
+    name: string;
+    id: string;
+}>(organizations: T[], options: {
+    allowCreate: false;
+}): Promise<T>;
+/**
+ * Selects an organization and optionally offers inline creation.
+ *
+ * @param organizations - Organizations available for selection.
+ * @param options - Prompt options.
+ * @param options.allowCreate - Whether to offer inline organization creation.
+ */
+export declare function promptOrg(organizations: OrgList, options: {
+    allowCreate: boolean;
+}): Promise<OrgList[number]>;
+/**
+ * Selects an organization, offering inline creation by default.
+ *
+ * @param organizations - Organizations available for selection.
+ * @param options - Optional prompt behavior.
+ * @param options.allowCreate - Whether to offer inline organization creation.
+ */
+export declare function promptOrg(organizations: OrgList, options?: {
+    allowCreate?: true;
+}): Promise<OrgList[number]>;
+/**
+ * Asks whether to create the user's first organization, then creates it.
+ *
+ * @throws {Error} When the user declines creation.
+ */
+export declare function promptCreateOrganization(): Promise<{
+    id: string;
+    name: string;
+}>;
+/** Shared schema fragment for commands that operate on a project. */
+export declare const projectOptsSchema: z.ZodObject<{
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Shared schema fragment for commands that operate on a config directory. */
+export declare const configDirOptsSchema: z.ZodObject<{
+    dir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export interface UseProjectOptions {
+    /** Whether project resolution may create a project interactively. */
+    mode?: "select" | "select-or-create";
+}
+/**
+ * Resolves a project from CLI flags or interactive prompt. Fetches all projects
+ * across all orgs so the user doesn't need to specify an org. Precedence:
+ * `--project` flag > auto-select (single project) > prompt (with inline
+ * creation).
+ *
+ * @param opts - Parsed project CLI options.
+ * @param options - Project resolution behavior.
+ * @param options.mode - Whether interactive project creation is allowed.
+ */
+export declare function useProject(opts: z.infer<typeof projectOptsSchema>, { mode }?: UseProjectOptions): Promise<{
+    id: string;
+    name: string;
+    organizationId: string;
+    createdAt: Date;
+    createdBy: string | null;
+    org: {
+        id: string;
+        name: string;
+    };
+}>;
+/**
+ * Resolves the config directory from a positional directory or config search.
+ * Precedence: explicit directory > current directory > nearest parent >
+ * downward search. Multiple downward matches are selected interactively.
+ *
+ * @param opts - Parsed config-directory CLI options.
+ */
+export declare function useConfigDir(opts: z.infer<typeof configDirOptsSchema>): Promise<ConfigDirMatch>;
+/**
+ * Creates a Citty runner for a command without parsed options.
+ *
+ * @param optsSchema - `null` because the command accepts no options.
+ * @param cb - Command handler to invoke.
+ */
+export declare function createCommandRun(optsSchema: null, cb: () => Promise<void>): (ctx: {
+    args: unknown;
+}) => Promise<void>;
+/**
+ * Creates a Citty runner that parses command options before handling them.
+ *
+ * @param optsSchema - Schema for parsing Citty arguments.
+ * @param cb - Command handler receiving parsed options.
+ */
+export declare function createCommandRun<T extends ZodType>(optsSchema: T, cb: (opts: z.infer<T>) => Promise<void>): (ctx: {
+    args: unknown;
+}) => Promise<void>;
+/**
+ * Selects a simple English singular or plural word form.
+ *
+ * @param count - Quantity determining which form to use.
+ * @param singularWord - Singular noun to pluralize when needed.
+ */
+export declare function pluralize(count: number, singularWord: string): string;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/cli/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/cli/utils.ts"],"names":[],"mappings":"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"}