alchemy 2.0.0-beta.2 → 2.0.0-beta.21

package/src/Axiom/AuthProvider.ts

@@ -0,0 +1,336 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Match from "effect/Match";
+import * as Redacted from "effect/Redacted";
+import {
+  AuthError,
+  AuthProviderLayer,
+  type ConfigureContext,
+} from "../Auth/AuthProvider.ts";
+import {
+  deleteCredentials,
+  displayRedacted,
+  readCredentials,
+  writeCredentials,
+} from "../Auth/Credentials.ts";
+import { getEnv, getEnvRedacted, retryOnce } from "../Auth/Env.ts";
+import * as Clank from "../Util/Clank.ts";
+import { DEFAULT_API_BASE_URL } from "@distilled.cloud/axiom/Credentials";
+
+const STORAGE_KEY = "axiom-stored";
+
+const options: Array<{
+  value: AxiomAuthConfig["method"];
+  label: string;
+  hint?: string;
+}> = [
+  {
+    value: "env",
+    label: "Environment Variables",
+    hint: "AXIOM_TOKEN (or AXIOM_API_KEY) + optional AXIOM_ORG_ID, AXIOM_URL",
+  },
+  {
+    value: "stored",
+    label: "API Token or Personal Access Token",
+    hint: "enter credentials interactively, stored in ~/.alchemy/credentials",
+  },
+];
+
+export type AxiomAuthConfig =
+  | { method: "env" }
+  | { method: "stored"; credentialType: "apiToken" }
+  | { method: "stored"; credentialType: "pat" };
+
+export type AxiomStoredCredentials =
+  | { type: "apiToken"; apiToken: string; apiBaseUrl?: string; orgId?: string }
+  | { type: "pat"; apiToken: string; apiBaseUrl?: string; orgId: string };
+
+export type AxiomResolvedCredentials =
+  | {
+      type: "apiToken";
+      apiToken: Redacted.Redacted<string>;
+      apiBaseUrl: string;
+      orgId?: string;
+      source: { type: AxiomAuthConfig["method"]; details?: string };
+    }
+  | {
+      type: "pat";
+      apiToken: Redacted.Redacted<string>;
+      apiBaseUrl: string;
+      orgId: string;
+      source: { type: AxiomAuthConfig["method"]; details?: string };
+    };
+
+export const AXIOM_AUTH_PROVIDER_NAME = "Axiom";
+
+/**
+ * Layer that registers the Axiom {@link AuthProvider} into the
+ * {@link AuthProviders} registry when built. Include this in the Axiom
+ * `providers()` layer so `alchemy login` can discover it.
+ */
+export const AxiomAuth = AuthProviderLayer<
+  AxiomAuthConfig,
+  AxiomResolvedCredentials
+>()(AXIOM_AUTH_PROVIDER_NAME, {
+  configure: (profileName, ctx) => configureCredentials(profileName, ctx),
+  logout: (profileName, config) => logout(profileName, config),
+  login: (profileName, config) => login(profileName, config),
+  prettyPrint: (profileName, config) => prettyPrint(profileName, config),
+  read: (profileName, config) => resolveCredentials(profileName, config),
+});
+
+const resolveCredentials = (
+  profileName: string,
+  config: AxiomAuthConfig,
+): Effect.Effect<AxiomResolvedCredentials, AuthError, FileSystem.FileSystem> =>
+  Match.value(config).pipe(
+    Match.when(
+      { method: "env" },
+      Effect.fnUntraced(function* () {
+        const apiToken =
+          (yield* getEnvRedacted("AXIOM_TOKEN")) ??
+          (yield* getEnvRedacted("AXIOM_API_KEY"));
+        if (!apiToken) {
+          return yield* new AuthError({
+            message:
+              "Axiom env credentials not found. Set AXIOM_TOKEN (or AXIOM_API_KEY).",
+          });
+        }
+        const apiBaseUrl = (yield* getEnv("AXIOM_URL")) ?? DEFAULT_API_BASE_URL;
+        const orgId = yield* getEnv("AXIOM_ORG_ID");
+        if (orgId) {
+          return {
+            type: "pat" as const,
+            apiToken,
+            apiBaseUrl,
+            orgId,
+            source: { type: "env" as const },
+          };
+        }
+        return {
+          type: "apiToken" as const,
+          apiToken,
+          apiBaseUrl,
+          source: { type: "env" as const },
+        };
+      }),
+    ),
+    Match.when({ method: "stored" }, () =>
+      readCredentials<AxiomStoredCredentials>(profileName, STORAGE_KEY).pipe(
+        Effect.flatMap((creds) =>
+          creds == null
+            ? Effect.fail(
+                new AuthError({
+                  message:
+                    "Axiom stored credentials not found. Run: alchemy login --configure",
+                }),
+              )
+            : Effect.succeed(
+                Match.value(creds).pipe(
+                  Match.when({ type: "apiToken" }, (c) => ({
+                    type: "apiToken" as const,
+                    apiToken: Redacted.make(c.apiToken),
+                    apiBaseUrl: c.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+                    orgId: c.orgId,
+                    source: { type: "stored" as const },
+                  })),
+                  Match.when({ type: "pat" }, (c) => ({
+                    type: "pat" as const,
+                    apiToken: Redacted.make(c.apiToken),
+                    apiBaseUrl: c.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+                    orgId: c.orgId,
+                    source: { type: "stored" as const },
+                  })),
+                  Match.exhaustive,
+                ),
+              ),
+        ),
+      ),
+    ),
+    Match.exhaustive,
+  );
+
+const logout = (profileName: string, config: AxiomAuthConfig) =>
+  Match.value(config).pipe(
+    Match.when({ method: "env" }, () => Effect.void),
+    Match.when({ method: "stored" }, () =>
+      deleteCredentials(profileName, STORAGE_KEY).pipe(
+        Effect.andThen(Clank.success("Axiom: stored credentials removed")),
+      ),
+    ),
+    Match.exhaustive,
+  );
+
+const login = (profileName: string, config: AxiomAuthConfig) =>
+  Match.value(config)
+    .pipe(
+      Match.when({ method: "env" }, () => Effect.void),
+      Match.when({ method: "stored" }, () =>
+        readCredentials<AxiomStoredCredentials>(profileName, STORAGE_KEY).pipe(
+          Effect.flatMap((creds) =>
+            creds == null ? loginStored(profileName) : Effect.void,
+          ),
+        ),
+      ),
+      Match.exhaustive,
+    )
+    .pipe(
+      Effect.mapError(
+        (e) => new AuthError({ message: "login failed", cause: e }),
+      ),
+    );
+
+const configureCredentials = (profileName: string, ctx: ConfigureContext) =>
+  Effect.gen(function* () {
+    if (ctx.ci) {
+      return { method: "env" as const };
+    }
+    return yield* configureInteractive(profileName);
+  }).pipe(
+    Effect.mapError(
+      (e) =>
+        new AuthError({
+          message: "failed to configure credentials",
+          cause: e,
+        }),
+    ),
+  );
+
+const configureInteractive = (profileName: string) =>
+  Clank.select({
+    message: "Axiom authentication method",
+    options,
+  }).pipe(
+    Effect.flatMap((method) =>
+      Match.value(method).pipe(
+        Match.when("env", () => Effect.succeed({ method: "env" as const })),
+        Match.when("stored", () => loginStored(profileName)),
+        Match.exhaustive,
+      ),
+    ),
+  );
+
+const loginStored = Effect.fnUntraced(function* (profileName: string) {
+  const credentialType = yield* Clank.select({
+    message: "Axiom credential type",
+    options: [
+      {
+        value: "apiToken" as const,
+        label: "API Token",
+        hint: "recommended — scoped to specific datasets/actions",
+      },
+      {
+        value: "pat" as const,
+        label: "Personal Access Token",
+        hint: "full account control, requires Org ID",
+      },
+    ],
+  }).pipe(retryOnce);
+
+  const apiBaseUrlPrompt = yield* Clank.text({
+    message: "Axiom API Base URL (Enter for default)",
+    placeholder: DEFAULT_API_BASE_URL,
+    defaultValue: DEFAULT_API_BASE_URL,
+  }).pipe(retryOnce);
+  const apiBaseUrl =
+    apiBaseUrlPrompt && apiBaseUrlPrompt.length > 0
+      ? apiBaseUrlPrompt
+      : undefined;
+
+  return yield* Match.value(credentialType).pipe(
+    Match.when("apiToken", () =>
+      Effect.gen(function* () {
+        const apiToken = yield* Clank.password({
+          message: "Axiom API Token",
+          validate: (v) => (v.length === 0 ? "Required" : undefined),
+        }).pipe(retryOnce);
+        const orgId = yield* promptOrgId(false);
+
+        yield* writeCredentials<AxiomStoredCredentials>(
+          profileName,
+          STORAGE_KEY,
+          {
+            type: "apiToken",
+            apiToken,
+            apiBaseUrl,
+            orgId: orgId && orgId.length > 0 ? orgId : undefined,
+          },
+        );
+        yield* Clank.success("Axiom: credentials saved.");
+        return {
+          method: "stored" as const,
+          credentialType: "apiToken" as const,
+        };
+      }),
+    ),
+    Match.when("pat", () =>
+      Effect.gen(function* () {
+        const apiToken = yield* Clank.password({
+          message: "Axiom Personal Access Token",
+          validate: (v) => (v.length === 0 ? "Required" : undefined),
+        }).pipe(retryOnce);
+        const orgId = yield* promptOrgId(true);
+
+        yield* writeCredentials<AxiomStoredCredentials>(
+          profileName,
+          STORAGE_KEY,
+          { type: "pat", apiToken, apiBaseUrl, orgId },
+        );
+        yield* Clank.success("Axiom: credentials saved.");
+        return {
+          method: "stored" as const,
+          credentialType: "pat" as const,
+        };
+      }),
+    ),
+    Match.exhaustive,
+  );
+});
+
+const promptOrgId = (required: boolean) =>
+  getEnv("AXIOM_ORG_ID").pipe(
+    Effect.flatMap((envOrgId) =>
+      Clank.text({
+        message: required
+          ? "Axiom Org ID (required for PAT)"
+          : "Axiom Org ID (Enter to skip)",
+        placeholder: envOrgId ?? "",
+        defaultValue: envOrgId ?? "",
+        validate: required
+          ? (v) => (v.length === 0 ? "Required" : undefined)
+          : undefined,
+      }).pipe(retryOnce),
+    ),
+  );
+
+const prettyPrint = (profileName: string, config: AxiomAuthConfig) =>
+  resolveCredentials(profileName, config).pipe(
+    Effect.tap((creds) => {
+      const sourceStr = creds.source.details
+        ? `${creds.source.type} - ${creds.source.details}`
+        : creds.source.type;
+      return Match.value(creds).pipe(
+        Match.when({ type: "apiToken" }, (c) =>
+          Effect.all([
+            Console.log(`  apiToken: ${displayRedacted(c.apiToken, 9)}`),
+            Console.log(`  apiBaseUrl: ${c.apiBaseUrl}`),
+            Console.log(`  orgId: ${c.orgId ?? "(none)"}`),
+            Console.log(`  source: ${sourceStr}`),
+          ]),
+        ),
+        Match.when({ type: "pat" }, (c) =>
+          Effect.all([
+            Console.log(`  apiToken: ${displayRedacted(c.apiToken, 9)}`),
+            Console.log(`  apiBaseUrl: ${c.apiBaseUrl}`),
+            Console.log(`  orgId: ${c.orgId}`),
+            Console.log(`  source: ${sourceStr}`),
+          ]),
+        ),
+        Match.exhaustive,
+      );
+    }),
+    Effect.catch((e) =>
+      Console.error(`  Failed to retrieve credentials: ${e}`),
+    ),
+  );

package/src/Axiom/Chart.ts

@@ -0,0 +1,94 @@
+/**
+ * Typed view of the Axiom dashboard chart-JSON subset.
+ *
+ * Axiom's `CreateDashboardInput` declares
+ * `dashboard.charts: ReadonlyArray<unknown>` (see
+ * `@distilled.cloud/axiom/.../v2/createDashboard.ts`); these
+ * interfaces give callers compile-time safety when building the
+ * payload by hand.
+ *
+ * `chart.id` is a free-form string the author picks — Axiom
+ * doesn't validate the format. It joins to the matching
+ * `LayoutCell.i` in `dashboard.layout`.
+ */
+
+/**
+ * Axiom-validated chart kinds. Discovered by probing
+ * `POST /v2/dashboards`: anything else returns
+ * `dashboard validation failed at [charts N type]: Invalid input`.
+ */
+export type ChartKind =
+  | "TimeSeries"
+  | "Table"
+  | "Pie"
+  | "Statistic"
+  | "Heatmap"
+  | "LogStream"
+  | "Note";
+
+/**
+ * Minimum chart payload Axiom's `POST /v2/dashboards` accepts.
+ * Any unknown keys (e.g. `dataset`, `description`) trigger
+ * `Unrecognized keys: "<name>"`, so this struct is intentionally
+ * narrow. The dataset is implicit via the APL query.
+ */
+export interface BaseChart {
+  readonly id: string;
+  readonly name: string;
+  readonly type: ChartKind;
+  readonly query: { readonly apl: string };
+}
+
+export interface TimeSeriesChart extends BaseChart {
+  readonly type: "TimeSeries";
+}
+
+export interface TableChart extends BaseChart {
+  readonly type: "Table";
+}
+
+export interface PieChart extends BaseChart {
+  readonly type: "Pie";
+}
+
+export interface StatisticChart extends BaseChart {
+  readonly type: "Statistic";
+}
+
+export interface HeatmapChart extends BaseChart {
+  readonly type: "Heatmap";
+}
+
+export interface LogStreamChart extends BaseChart {
+  readonly type: "LogStream";
+}
+
+export interface NoteChart extends BaseChart {
+  readonly type: "Note";
+}
+
+export type Chart =
+  | TimeSeriesChart
+  | TableChart
+  | PieChart
+  | StatisticChart
+  | HeatmapChart
+  | LogStreamChart
+  | NoteChart;
+
+/**
+ * Mirrors Axiom's `CreateDashboardInput.dashboard.layout` cell schema.
+ * `i` references a chart by its `id`.
+ */
+export interface LayoutCell {
+  readonly i: string;
+  readonly x: number;
+  readonly y: number | null;
+  readonly w: number;
+  readonly h: number;
+  readonly minW?: number;
+  readonly minH?: number;
+  readonly maxW?: number;
+  readonly maxH?: number;
+  readonly static?: boolean;
+}

package/src/Axiom/Credentials.ts

@@ -0,0 +1,66 @@
+import { Credentials } from "@distilled.cloud/axiom/Credentials";
+import { ConfigError } from "@distilled.cloud/core/errors";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import { getAuthProvider } from "../Auth/AuthProvider.ts";
+import { ALCHEMY_PROFILE, loadOrConfigure } from "../Auth/Profile.ts";
+import {
+  AXIOM_AUTH_PROVIDER_NAME,
+  type AxiomAuthConfig,
+  type AxiomResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/axiom/Credentials";
+
+/**
+ * Build a `Credentials` layer that resolves Axiom credentials via the Alchemy
+ * AuthProvider using the configured profile (defaults to "default", overridable
+ * with the `ALCHEMY_PROFILE` env/config value).
+ */
+export const fromAuthProvider = () =>
+  Layer.effect(
+    Credentials,
+    Effect.gen(function* () {
+      const auth = yield* getAuthProvider<
+        AxiomAuthConfig,
+        AxiomResolvedCredentials
+      >(AXIOM_AUTH_PROVIDER_NAME);
+      const profileName = yield* ALCHEMY_PROFILE;
+      const ci = yield* Config.boolean("CI").pipe(Config.withDefault(false));
+      const ctx = yield* Effect.context<never>();
+
+      return yield* loadOrConfigure(auth, profileName, { ci }).pipe(
+        Effect.flatMap((config) =>
+          auth.read(profileName, config as AxiomAuthConfig),
+        ),
+        Effect.map((creds) =>
+          Match.value(creds).pipe(
+            Match.when({ type: "apiToken" }, (c) => ({
+              apiKey: c.apiToken,
+              apiBaseUrl: c.apiBaseUrl,
+              orgId: c.orgId,
+            })),
+            Match.when({ type: "pat" }, (c) => ({
+              apiKey: c.apiToken,
+              apiBaseUrl: c.apiBaseUrl,
+              orgId: c.orgId,
+            })),
+            Match.exhaustive,
+          ),
+        ),
+        Effect.mapError(
+          (e) =>
+            new ConfigError({
+              message: `Failed to resolve Axiom credentials for profile '${profileName}': ${(e as { message?: string }).message ?? String(e)}`,
+            }),
+        ),
+        Effect.provide(ctx),
+      );
+    }),
+  );

package/src/Axiom/Dashboard.ts

@@ -0,0 +1,189 @@
+import * as Axiom from "@distilled.cloud/axiom";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import type { Chart, LayoutCell } from "./Chart.ts";
+import type { Providers } from "./Providers.ts";
+
+type DashboardDoc = Axiom.CreateDashboardInput["dashboard"];
+
+/**
+ * Dashboard input. Mirrors `Operations.CreateDashboardInput` but
+ * narrows `dashboard.charts` and `dashboard.layout` to the typed
+ * {@link Chart} / {@link LayoutCell} shapes (Axiom declares them
+ * as `Schema.Array(Schema.Unknown)`, so this is a compile-time-only
+ * refinement; runtime validation is unchanged).
+ */
+export type DashboardProps = Omit<Axiom.CreateDashboardInput, "dashboard"> & {
+  readonly dashboard: Omit<DashboardDoc, "charts" | "layout"> & {
+    readonly charts: readonly Chart[];
+    readonly layout: readonly LayoutCell[];
+  };
+};
+
+export type Dashboard = Resource<
+  "Axiom.Dashboard",
+  DashboardProps,
+  {
+    /** Stable Axiom dashboard `uid` (used as the path identifier). */
+    uid: string;
+    id: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    /** The full dashboard document as returned by Axiom. */
+    dashboard: Axiom.CreateDashboardOutput["dashboard"]["dashboard"];
+  },
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom dashboard — a named, layout-driven collection of charts. Each
+ * dashboard takes a full document (`charts` + `layout` array of grid cells +
+ * `timeWindow` + `refreshTime`) at version `schemaVersion: 2`.
+ *
+ * Charts are typed via {@link Chart} (a discriminated union over the
+ * Axiom-validated chart kinds — `TimeSeries`, `Table`, `Pie`, `Statistic`,
+ * `Heatmap`, `LogStream`, `Note`). The `id` on each chart is a free-form
+ * string the author picks; layout cells join via `LayoutCell.i`.
+ *
+ * The path identifier is `uid` (auto-assigned by Axiom). `id` is also
+ * exposed as an output but the API uses `uid` everywhere.
+ *
+ * Notes from probing `POST /v2/dashboards`:
+ *
+ * - Relative time windows must use the `qr-now-{duration}` form (e.g.
+ *   `"qr-now-7d"` / `"qr-now"`); plain `"now-7d"` is rejected.
+ * - When authenticating with an API token, `dashboard.owner` must be `""`
+ *   (Axiom rewrites this to the org-shared `X-AXIOM-EVERYONE`); per-user
+ *   "private" dashboards aren't allowed for tokens.
+ * - The chart payload is strict: only `id`, `name`, `type`, `query`. Extra
+ *   keys (e.g. `dataset`, `description`) trigger
+ *   `Unrecognized keys: "<name>"`.
+ *
+ * @see https://axiom.co/docs/query-data/dashboards
+ *
+ * @section Creating a Dashboard
+ * @example Minimal empty dashboard
+ * ```typescript
+ * yield* Axiom.Dashboard("ops", {
+ *   dashboard: {
+ *     name: "Ops Overview",
+ *     owner: "",                 // org-shared (required for API tokens)
+ *     description: "Top-level service health",
+ *     charts: [],
+ *     layout: [],
+ *     refreshTime: 60,           // seconds: 15 | 60 | 300
+ *     schemaVersion: 2,
+ *     timeWindowStart: "qr-now-1h",
+ *     timeWindowEnd: "qr-now",
+ *   },
+ * });
+ * ```
+ *
+ * @example One-chart dashboard
+ * ```typescript
+ * import type { Chart, LayoutCell } from "alchemy/Axiom";
+ *
+ * const errors: Chart = {
+ *   id: "errors-5m",
+ *   name: "5xx errors / 5m",
+ *   type: "TimeSeries",
+ *   query: {
+ *     apl: `['my-app-traces']
+ *       | where status >= 500
+ *       | summarize count() by bin_auto(_time)`,
+ *   },
+ * };
+ *
+ * yield* Axiom.Dashboard("errors", {
+ *   dashboard: {
+ *     name: "Errors",
+ *     owner: "",
+ *     refreshTime: 60,
+ *     schemaVersion: 2,
+ *     timeWindowStart: "qr-now-24h",
+ *     timeWindowEnd: "qr-now",
+ *     charts: [errors],
+ *     layout: [{ i: errors.id, x: 0, y: 0, w: 12, h: 6 } satisfies LayoutCell],
+ *   },
+ * });
+ * ```
+ *
+ * @example Compare to last 24h
+ * ```typescript
+ * yield* Axiom.Dashboard("compare", {
+ *   dashboard: {
+ *     name: "Compare vs yesterday",
+ *     owner: "",
+ *     refreshTime: 300,
+ *     schemaVersion: 2,
+ *     timeWindowStart: "qr-now-1h",
+ *     timeWindowEnd: "qr-now",
+ *     against: "-1d",            // overlay the same window from 24h ago
+ *     charts: [],
+ *     layout: [],
+ *   },
+ * });
+ * ```
+ */
+export const Dashboard = Resource<Dashboard>("Axiom.Dashboard");
+
+export const DashboardProvider = () =>
+  Provider.effect(
+    Dashboard,
+    Effect.gen(function* () {
+      const create = yield* Axiom.createDashboard;
+      const update = yield* Axiom.updateDashboard;
+      const get = yield* Axiom.getDashboard;
+      const del = yield* Axiom.deleteDashboard;
+
+      const toAttrsFromCreate = (envelope: Axiom.CreateDashboardOutput) => ({
+        uid: envelope.dashboard.uid,
+        id: envelope.dashboard.id,
+        createdAt: envelope.dashboard.createdAt,
+        createdBy: envelope.dashboard.createdBy,
+        updatedAt: envelope.dashboard.updatedAt,
+        updatedBy: envelope.dashboard.updatedBy,
+        dashboard: envelope.dashboard.dashboard,
+      });
+      const toAttrsFromGet = (current: Axiom.GetDashboardOutput) => ({
+        uid: current.uid,
+        id: current.id,
+        createdAt: current.createdAt,
+        createdBy: current.createdBy,
+        updatedAt: current.updatedAt,
+        updatedBy: current.updatedBy,
+        dashboard: current.dashboard,
+      });
+
+      return {
+        stables: ["uid", "id", "createdAt", "createdBy"],
+        create: Effect.fn(function* ({ news }) {
+          return toAttrsFromCreate(yield* create(news));
+        }),
+        update: Effect.fn(function* ({ news, output }) {
+          // `overwrite: true` short-circuits Axiom's optimistic-concurrency
+          // check (otherwise the API requires the caller to echo back the
+          // server-side `version`, which the resource state doesn't track).
+          return toAttrsFromCreate(
+            yield* update({ ...news, uid: output.uid, overwrite: true }),
+          );
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ uid: output.uid }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.uid) return undefined;
+          return yield* get({ uid: output.uid }).pipe(
+            Effect.map(toAttrsFromGet),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );