automate.ax 0.1.3

package/dist/cli/utils.js

@@ -0,0 +1,561 @@
+import { cancel, log as clackLog, confirm, intro, isCancel, isCI, log, select, text, } from "@clack/prompts";
+import { bgYellow, red } from "ansis";
+import fs from "fs";
+import os from "node:os";
+import path from "node:path";
+import { z, ZodError } from "zod";
+import { commandExamples } from "./command-names.js";
+import { apiClient } from "./lib/api-client.js";
+import { authClient } from "./lib/auth-client.js";
+import { accent, dimmed } from "./lib/io.js";
+import { isJsonOutput, writeJson } from "./lib/json-output.js";
+import { findConfigDirMatches, findExplicitConfigDirMatch, } from "./lib/config-dir.js";
+import { clearSpinner, startSpinner } from "./lib/spinner.js";
+export const SESSION_PATH = path.join(os.homedir(), ".automate/session.json");
+export const REASONABLE_NAME_SCHEMA = z.string().min(1).max(255).trim();
+export const ORG_OPT = {
+    org: {
+        type: "string",
+        description: "Organization name or ID",
+        alias: ["o"],
+    },
+};
+export const API_KEY_OPT = {
+    key: {
+        type: "string",
+        description: "API key name, prefix, or ID",
+        alias: ["k"],
+    },
+};
+export const PROJECT_OPT = {
+    project: {
+        type: "string",
+        description: "Project name or ID",
+        alias: ["p"],
+    },
+};
+export const CLI_PREFIX = bgYellow.black.bold ` automate `;
+/** Reads and validates the saved CLI session token. */
+export function loadSavedTokenSync() {
+    try {
+        return z
+            .object({ token: z.string() })
+            .parse(JSON.parse(fs.readFileSync(SESSION_PATH, "utf-8"))).token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persists the session token to disk for use by subsequent CLI commands.
+ *
+ * @param token - Bearer token to save.
+ */
+export function saveTokenSync(token) {
+    fs.mkdirSync(path.dirname(SESSION_PATH), { recursive: true });
+    fs.writeFileSync(SESSION_PATH, JSON.stringify({ token }, null, 2));
+}
+/** Removes the saved CLI session token. */
+export function clearSavedTokenSync() {
+    fs.unlinkSync(SESSION_PATH);
+}
+/** Checks whether the current process can safely show interactive prompts. */
+function canPrompt() {
+    return process.stdin.isTTY && !isCI() && !isJsonOutput();
+}
+/**
+ * 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 function promptableOption(schema, optionName) {
+    return schema
+        .nullable()
+        .prefault(null)
+        .refine((value) => value != null || canPrompt(), `${optionName ?? "Option"} must be passed explicitly in non-interactive mode.`);
+}
+/**
+ * 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 async function safelyPrompt(promptFactory, optionName) {
+    if (!canPrompt()) {
+        throw new Error(`${optionName ?? "Option"} must be passed explicitly in non-interactive mode.`);
+    }
+    const result = await promptFactory();
+    if (isCancel(result)) {
+        clearSpinner();
+        cancel("Cancelled");
+        process.exit(0);
+    }
+    return result;
+}
+/**
+ * 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 async function safelyPromptTextWithValidation(promptOptions, schema, optionName) {
+    return schema.parseAsync(await safelyPrompt(() => text({
+        validate: (v) => {
+            const validation = schema.safeParse(v);
+            return validation.success
+                ? undefined
+                : z.prettifyError(validation.error);
+        },
+        ...promptOptions,
+    }), optionName));
+}
+/**
+ * Extracts the most specific message from common API error envelopes.
+ *
+ * @param error - Unknown error value returned by a command dependency.
+ */
+function extractErrorMessage(error) {
+    const errorWithMessage = z.object({ message: z.string() }).safeParse(error);
+    const bodyWithMessage = z
+        .looseObject({ body: z.looseObject({ message: z.string() }) })
+        .safeParse(error);
+    const causeWithMessage = z
+        .looseObject({ cause: z.looseObject({ message: z.string() }) })
+        .safeParse(error);
+    const causeBodyWithMessage = z
+        .looseObject({
+        cause: z.looseObject({
+            body: z.looseObject({ message: z.string() }),
+        }),
+    })
+        .safeParse(error);
+    return errorWithMessage.success
+        ? errorWithMessage.data.message
+        : bodyWithMessage.success
+            ? bodyWithMessage.data.body.message
+            : causeWithMessage.success
+                ? causeWithMessage.data.cause.message
+                : causeBodyWithMessage.success
+                    ? causeBodyWithMessage.data.cause.body.message
+                    : String(error);
+}
+/**
+ * Formats an error for human-readable CLI output.
+ *
+ * @param error - Error to format.
+ */
+function formatErrorMessage(error) {
+    if (error instanceof ZodError)
+        return z.prettifyError(error);
+    return extractErrorMessage(error).replaceAll(/`([^`]+)`/g, (_, command) => accent(command));
+}
+/**
+ * Converts an error into the CLI's stable JSON error envelope.
+ *
+ * @param error - Error to serialize.
+ */
+export function formatJsonError(error) {
+    if (error instanceof ZodError) {
+        return {
+            error: {
+                message: "Failed validation",
+                ...z.flattenError(error),
+            },
+        };
+    }
+    return {
+        error: {
+            message: extractErrorMessage(error),
+        },
+    };
+}
+/**
+ * Writes a serialized CLI error to stderr.
+ *
+ * @param error - Error to serialize and write.
+ */
+export function writeJsonError(error) {
+    process.stderr.write(`${JSON.stringify(formatJsonError(error), null, 2)}\n`);
+}
+export const output = {
+    normal: (printFn) => {
+        if (!isJsonOutput())
+            printFn();
+        return output;
+    },
+    json: (value) => {
+        if (isJsonOutput())
+            writeJson(value);
+        return output;
+    },
+};
+export async function useSession({ signInAnonymously = true, } = {}) {
+    return authClient.getSession().then(async (session) => {
+        if (session || !signInAnonymously)
+            return session;
+        return await authClient.signIn.anonymous();
+    });
+}
+/**
+ * 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 function sessionIntro(session, { skipAnonWarning = false } = {}) {
+    intro(`${CLI_PREFIX}  ${dimmed(session && !session.user.isAnonymous
+        ? session.user.email
+        : "Not logged in")}`);
+    if (!skipAnonWarning && session?.user.isAnonymous) {
+        log.warn(dimmed.italic `You're using Automate.ax anonymously. Some features will be limited. Sign in with ${accent(commandExamples.login)} for full functionality.`);
+    }
+}
+/**
+ * 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 async function requireAuthenticatedSession(action) {
+    const session = await useSession({ signInAnonymously: false });
+    if (!session || session.user.isAnonymous) {
+        output.normal(() => sessionIntro(session, { skipAnonWarning: true }));
+        throw new Error(`You must log in with ${accent(commandExamples.login)} to ${action}.`);
+    }
+    return session;
+}
+/** Shared schema fragment for commands that operate on an organization. */
+export const orgOptsSchema = z.object({
+    org: z.string().optional(),
+});
+/** Shared schema fragment for commands that select an organization API key. */
+export const apiKeyOptsSchema = orgOptsSchema.extend({
+    key: z.string().optional(),
+});
+/**
+ * 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 async function useOrganization(opts, { whenEmpty = "error" } = {}) {
+    startSpinner("Fetching organizations");
+    const organizations = opts.org
+        ? await apiClient.org.list({ query: opts.org })
+        : await apiClient.org.list();
+    clearSpinner();
+    if (opts.org) {
+        const exactIdMatch = organizations.find((org) => org.id === opts.org);
+        if (exactIdMatch)
+            return exactIdMatch;
+        if (organizations.length === 0) {
+            throw new Error(`Organization not found: ${opts.org}`);
+        }
+        if (organizations.length === 1)
+            return organizations[0];
+        return promptOrg(organizations, { allowCreate: false });
+    }
+    if (organizations.length === 0) {
+        if (whenEmpty === "error") {
+            throw new Error("You don't belong to any organizations.");
+        }
+        if (whenEmpty === "prompt-create")
+            return promptCreateOrganization();
+        return createOrgInline();
+    }
+    if (organizations.length === 1)
+        return organizations[0];
+    return promptOrg(organizations, { allowCreate: whenEmpty !== "error" });
+}
+/**
+ * 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 async function useOrganizationApiKey(organizationId, opts) {
+    startSpinner("Fetching API keys");
+    const apiKeys = await apiClient.apiKey.list({ organizationId });
+    clearSpinner();
+    if (apiKeys.length === 0) {
+        throw new Error(`No API keys. Create one with \`${commandExamples.orgApiKeyCreate}\``);
+    }
+    if (opts.key) {
+        const matches = apiKeys.filter((apiKey) => apiKey.id === opts.key ||
+            apiKey.start === opts.key ||
+            apiKey.name === opts.key);
+        if (matches.length === 0) {
+            throw new Error(`API key not found: ${opts.key}`);
+        }
+        if (matches.length === 1)
+            return matches[0];
+        return promptOrganizationApiKey(matches);
+    }
+    if (apiKeys.length === 1)
+        return apiKeys[0];
+    return promptOrganizationApiKey(apiKeys);
+}
+export async function promptOrg(organizations, { allowCreate = true } = {}) {
+    if (organizations.length === 0)
+        return promptCreateOrganization();
+    const orgOptions = organizations.map((o) => ({
+        label: `${o.plan === "pro" ? "★ " : ""}${o.name} ${dimmed(o.id)}`,
+        value: o.id,
+    }));
+    const selected = await safelyPrompt(() => select({
+        message: "Which organization?",
+        options: allowCreate
+            ? [...orgOptions, { label: "Create a new organization", value: null }]
+            : orgOptions,
+    }), "--org");
+    if (selected == null)
+        return createOrgInline();
+    return organizations.find((o) => o.id === selected);
+}
+/**
+ * Prompts for one API key from an organization-scoped list.
+ *
+ * @param apiKeys - API keys available for selection.
+ */
+async function promptOrganizationApiKey(apiKeys) {
+    const selected = await safelyPrompt(() => select({
+        message: "Which API key?",
+        options: apiKeys.map((apiKey) => ({
+            label: `${apiKey.name ?? "Unnamed"} ${dimmed(apiKey.start ?? apiKey.id)}`,
+            value: apiKey.id,
+        })),
+    }), "--key");
+    return apiKeys.find((apiKey) => apiKey.id === selected);
+}
+/** Walks the user through creating an organization. */
+async function createOrgInline() {
+    const session = await requireAuthenticatedSession("create an organization");
+    const defaultName = session.user.name &&
+        !session.user.isAnonymous &&
+        !z.email().safeParse(session.user.name).success
+        ? `${session.user.name}'s Organization`
+        : "My Organization";
+    startSpinner("Creating organization");
+    const org = await apiClient.org.create({
+        name: await safelyPromptTextWithValidation({
+            message: "What should we name the organization?",
+            placeholder: defaultName,
+            defaultValue: defaultName,
+        }, REASONABLE_NAME_SCHEMA, "--name"),
+    });
+    clearSpinner();
+    clackLog.success(`Created ${accent(org.name)} ${dimmed(org.id)}`);
+    return org;
+}
+/**
+ * Asks whether to create the user's first organization, then creates it.
+ *
+ * @throws {Error} When the user declines creation.
+ */
+export async function promptCreateOrganization() {
+    if (!(await safelyPrompt(() => confirm({
+        message: "You don't have any organizations. Create one now?",
+        initialValue: true,
+    }), "organization"))) {
+        throw new Error("You don't belong to any organizations.");
+    }
+    return createOrgInline();
+}
+/** Shared schema fragment for commands that operate on a project. */
+export const projectOptsSchema = z.object({
+    project: z.string().optional(),
+});
+/** Shared schema fragment for commands that operate on a config directory. */
+export const configDirOptsSchema = z.object({
+    dir: z.string().optional(),
+});
+/**
+ * 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 async function useProject(opts, { mode = "select-or-create" } = {}) {
+    startSpinner("Fetching projects");
+    const allProjects = opts.project
+        ? await apiClient.project.list({ query: opts.project })
+        : await apiClient.project.list();
+    clearSpinner();
+    if (opts.project) {
+        const exactIdMatch = allProjects.find((project) => project.id === opts.project);
+        if (exactIdMatch)
+            return exactIdMatch;
+        if (allProjects.length === 0) {
+            throw new Error(`Project not found: ${opts.project}`);
+        }
+        if (allProjects.length === 1)
+            return allProjects[0];
+        return promptProject(allProjects, { allowCreate: false });
+    }
+    if (allProjects.length === 1)
+        return allProjects[0];
+    if (mode !== "select-or-create") {
+        if (allProjects.length === 0) {
+            throw new Error(`No projects. Create one with \`${commandExamples.projectCreate}\``);
+        }
+        return promptProject(allProjects, { allowCreate: false });
+    }
+    const organizations = await apiClient.org.list();
+    return promptProject(allProjects, {
+        allowCreate: true,
+        organizations: organizations.length > 0
+            ? organizations
+            : [await promptCreateOrganization()],
+    });
+}
+/**
+ * Interactive project selection prompt showing "Org > Project" format with an
+ * option to create a new project inline. When there are no existing projects,
+ * skips straight to creation.
+ *
+ * @param projects - Projects available for selection.
+ * @param options - Selection and inline-creation options.
+ */
+async function promptProject(projects, options) {
+    if (projects.length === 0) {
+        if (!options.allowCreate) {
+            throw new Error(`No projects. Create one with \`${commandExamples.projectCreate}\``);
+        }
+        return createProjectInline(options.organizations);
+    }
+    const projectOptions = projects.map((p) => ({
+        label: `${p.org.name} › ${p.name}`,
+        value: p.id,
+    }));
+    const selected = await safelyPrompt(() => select({
+        message: "Which project?",
+        options: options.allowCreate
+            ? [...projectOptions, { label: "Create a new project", value: null }]
+            : projectOptions,
+    }), "--project");
+    if (selected == null && options.allowCreate) {
+        return createProjectInline(options.organizations);
+    }
+    return projects.find((p) => p.id === selected);
+}
+/**
+ * Walks the user through creating a project.
+ *
+ * @param organizations - Organizations that may own the project.
+ */
+async function createProjectInline(organizations) {
+    const org = organizations.length === 1
+        ? organizations[0]
+        : await promptOrg(organizations, {
+            allowCreate: true,
+        });
+    startSpinner("Creating project");
+    const project = await apiClient.project.create({
+        organizationId: org.id,
+        name: await safelyPromptTextWithValidation({
+            message: "What should we name the project?",
+        }, REASONABLE_NAME_SCHEMA, "--name"),
+    });
+    clearSpinner();
+    clackLog.success(`Created ${accent(project.name)} ${dimmed(project.id)}`);
+    return { ...project, org };
+}
+/**
+ * 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 async function useConfigDir(opts) {
+    if (opts.dir)
+        return findExplicitConfigDirMatch(opts.dir);
+    const matches = await findConfigDirMatches();
+    if (matches.length === 0) {
+        throw new Error("No config file found. Run from a project directory or pass a directory explicitly.");
+    }
+    if (matches.length === 1)
+        return matches[0];
+    return promptConfigDir(matches);
+}
+/**
+ * Prompts the user to select from multiple matching config directories.
+ *
+ * @param matches - Config directory matches discovered by the search.
+ */
+async function promptConfigDir(matches) {
+    const cwd = process.cwd();
+    const selected = await safelyPrompt(() => select({
+        message: "Which config directory?",
+        options: matches.map((match) => ({
+            label: formatRelativePath(match.dir, cwd),
+            value: match.dir,
+        })),
+    }), "--dir");
+    return matches.find((match) => match.dir === selected);
+}
+/**
+ * Formats a path relative to the current working directory.
+ *
+ * @param target - Absolute path to display.
+ * @param cwd - Working directory used as the relative base.
+ */
+function formatRelativePath(target, cwd) {
+    const relative = path.relative(cwd, target);
+    return relative.length > 0 ? relative : ".";
+}
+/**
+ * Parses `ctx.args`, invokes the command handler, and reports failures.
+ *
+ * @param optsSchema - Optional schema for parsing Citty arguments.
+ * @param cb - Command handler receiving parsed options when present.
+ */
+export function createCommandRun(optsSchema, cb) {
+    return async (ctx) => {
+        try {
+            await cb(await optsSchema?.parseAsync(ctx.args));
+        }
+        catch (err) {
+            clearSpinner();
+            if (isJsonOutput()) {
+                writeJsonError(err);
+                process.exit(1);
+            }
+            // zod errors have a leading "✖ " that we don't want to print
+            clackLog.message(red(`${formatErrorMessage(err).replace(/^✖ ?/, "")}\n`), {
+                output: process.stderr,
+                symbol: red("✖"),
+            });
+            process.exit(1);
+        }
+    };
+}
+/**
+ * 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 function pluralize(count, singularWord) {
+    if (count === 1)
+        return singularWord;
+    if (singularWord.endsWith("y") && !/[aeiou]y$/i.test(singularWord)) {
+        return singularWord.slice(0, -1) + "ies";
+    }
+    return `${singularWord}s`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { runMain } from "./cli/index.js";
+import.meta.require = createRequire(import.meta.url);
+await runMain();

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface ProjectConfig {
+    projectId: string;
+}
+/**
+ * Preserves a project's configuration while providing type checking to config
+ * files.
+ *
+ * @param config - Project configuration to expose to the CLI.
+ */
+export declare function defineConfig(config: ProjectConfig): ProjectConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,iBAEjD"}

package/dist/config.js

@@ -0,0 +1,9 @@
+/**
+ * Preserves a project's configuration while providing type checking to config
+ * files.
+ *
+ * @param config - Project configuration to expose to the CLI.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import "./automation/runtime.js";
+export * from "./config.js";
+export * from "./automation/signal.js";
+export * from "./automation/subscribe.js";
+export * from "./automation/automation.js";
+export * from "./automation/actions.js";
+export * from "./automation/integrations.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iCAA6B;AAE7B,4BAAwB;AACxB,uCAAmC;AACnC,0CAAsC;AACtC,2CAAuC;AACvC,wCAAoC;AACpC,6CAAyC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+import "./automation/runtime.js";
+export * from "./config.js";
+export * from "./automation/signal.js";
+export * from "./automation/subscribe.js";
+export * from "./automation/automation.js";
+export * from "./automation/actions.js";
+export * from "./automation/integrations.js";