sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ QApps/ QApp.ts

import * as qapps from "@distilled.cloud/aws/qapps";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export class QAppInvalidProps extends Data.TaggedError("QAppInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class QAppUnexpectedResponse extends Data.TaggedError("QAppUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type AppStatus = qapps.AppStatus;
export type AppRequiredCapability = qapps.AppRequiredCapability;
export type CardInput = qapps.CardInput;

/**
 * Definition of an Amazon Q App — the ordered cards that make up the app's
 * flow plus an optional initial prompt.
 */
export interface QAppDefinition {
  /**
   * The cards that make up the Q App. Card ids must be UUIDs; dependencies
   * between cards are calculated by the service from references in prompts
   * (e.g. `@card-title`).
   */
  cards: qapps.CardInput[];
  /**
   * The initial prompt displayed when the Q App is started.
   */
  initialPrompt?: string;
}

export interface QAppProps {
  /**
   * The unique identifier of the Amazon Q Business application environment
   * instance the Q App is created in. Changing it replaces the Q App.
   */
  instanceId: string;
  /**
   * Title of the Q App.
   * @default ${app}-${stage}-${id}
   */
  title?: string;
  /**
   * A description of the Q App.
   */
  description?: string;
  /**
   * The definition of the Q App — its cards and flow.
   */
  appDefinition: QAppDefinition;
  /**
   * Tags to associate with the Q App.
   */
  tags?: Record<string, string>;
}

export interface QApp extends Resource<
  "AWS.QApps.QApp",
  QAppProps,
  {
    /**
     * Service-assigned unique identifier of the Q App.
     */
    appId: string;
    /**
     * ARN of the Q App.
     */
    appArn: string;
    /**
     * The Q Business application environment instance the Q App belongs to.
     */
    instanceId: string;
    /**
     * The Q App's title.
     */
    title: string;
    /**
     * The Q App's description.
     */
    description: string | undefined;
    /**
     * The current version of the Q App definition.
     */
    appVersion: number;
    /**
     * Lifecycle status of the Q App (`DRAFT`, `PUBLISHED`, `DELETED`).
     */
    status: AppStatus;
    /**
     * Capabilities end users need to run the Q App (e.g. `FileUpload`).
     */
    requiredCapabilities: AppRequiredCapability[] | undefined;
    /**
     * Current tags reported for the Q App.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Q App — a lightweight, purpose-built AI app defined as a flow of
 * cards (text inputs, file uploads, LLM query cards, plugin cards) running
 * inside an Amazon Q Business application environment.
 *
 * :::caution
 * Q Apps live inside an Amazon Q Business application (pass its id as
 * `instanceId`), which itself requires IAM Identity Center. The calling
 * identity must be a user of that Q Business application.
 * :::
 * ### Creating Q Apps
 * **Example:** Prompt-Driven Q App
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const summarizer = yield* AWS.QApps.QApp("Summarizer", {
 *   instanceId: qbusinessApp.applicationId,
 *   description: "Summarizes pasted text",
 *   appDefinition: {
 *     cards: [
 *       {
 *         textInput: {
 *           id: "11111111-1111-4111-8111-111111111111",
 *           title: "Source Text",
 *           type: "text-input",
 *         },
 *       },
 *       {
 *         qQuery: {
 *           id: "22222222-2222-4222-8222-222222222222",
 *           title: "Summary",
 *           type: "q-query",
 *           prompt: "Summarize the following text: @Source Text",
 *         },
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * **Example:** File Upload Q App
 * ```typescript
 * const analyzer = yield* AWS.QApps.QApp("DocAnalyzer", {
 *   instanceId: qbusinessApp.applicationId,
 *   appDefinition: {
 *     initialPrompt: "Upload a document to analyze",
 *     cards: [
 *       {
 *         fileUpload: {
 *           id: "33333333-3333-4333-8333-333333333333",
 *           title: "Document",
 *           type: "file-upload",
 *         },
 *       },
 *       {
 *         qQuery: {
 *           id: "44444444-4444-4444-8444-444444444444",
 *           title: "Analysis",
 *           type: "q-query",
 *           prompt: "List the key points of @Document",
 *         },
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const QApp = Resource<QApp>("AWS.QApps.QApp");

const createTitle = (id: string, props: { title?: string | undefined }) =>
  props.title ? Effect.succeed(props.title) : createPhysicalName({ id, maxLength: 100 });

const fetchTags = Effect.fn(function* (arn: string) {
  const response = yield* qapps
    .listTagsForResource({ resourceARN: arn })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  const tags: Record<string, string> = {};
  for (const [key, value] of Object.entries(response?.tags ?? {})) {
    if (value !== undefined) tags[key] = value;
  }
  return tags;
});

interface QAppState {
  attrs: QApp["Attributes"];
  observed: qapps.GetQAppOutput;
}

const readQAppById = Effect.fn(function* (instanceId: string, appId: string) {
  const observed = yield* qapps
    .getQApp({ instanceId, appId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!observed || observed.status === "DELETED") return undefined;
  const state: QAppState = {
    observed,
    attrs: {
      appId: observed.appId,
      appArn: observed.appArn,
      instanceId,
      title: observed.title,
      description: observed.description,
      appVersion: observed.appVersion,
      status: observed.status,
      requiredCapabilities: observed.requiredCapabilities?.slice(),
      tags: yield* fetchTags(observed.appArn),
    },
  };
  return state;
});

const findQAppByTitle = Effect.fn(function* (instanceId: string, title: string) {
  const apps = yield* qapps.listQApps.pages({ instanceId }).pipe(
    EffectStream.runCollect,
    Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.apps ?? [])),
  );
  const match = apps.find((app) => app.title === title && app.status !== "DELETED");
  if (!match?.appId) return undefined;
  return yield* readQAppById(instanceId, match.appId);
});

/**
 * Structural subset comparison: every defined field of `desired` must be
 * present (deep-equal) in `observed`. Observed cards carry service-computed
 * fields (`dependencies`, resolved `outputSource` defaults, …) that the
 * desired card input never specifies — those must not register as drift.
 */
const isSubsetOf = (desired: unknown, observed: unknown): boolean => {
  if (desired === undefined) return true;
  if (Array.isArray(desired)) {
    if (!Array.isArray(observed) || observed.length !== desired.length) {
      return false;
    }
    return desired.every((item, index) => isSubsetOf(item, observed[index]));
  }
  if (typeof desired === "object" && desired !== null) {
    if (typeof observed !== "object" || observed === null) return false;
    const observedRecord: Record<string, unknown> = { ...observed };
    return Object.entries(desired).every(([key, value]) => isSubsetOf(value, observedRecord[key]));
  }
  return desired === observed;
};

const definitionDrifted = (desired: QAppDefinition, observed: qapps.GetQAppOutput): boolean => {
  if (desired.initialPrompt !== undefined && desired.initialPrompt !== observed.initialPrompt) {
    return true;
  }
  return !isSubsetOf(desired.cards, observed.appDefinition.cards);
};

export const QAppProvider = () =>
  Provider.effect(
    QApp,
    Effect.gen(function* () {
      return {
        stables: ["appId", "appArn", "instanceId"],
        // Q Apps are keyed by their parent Q Business application environment
        // instance — enumeration across all instances is not meaningful here.
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ id, olds, output }) {
          const instanceId = output?.instanceId ?? olds?.instanceId;
          if (instanceId === undefined) return undefined;
          const state = output?.appId
            ? yield* readQAppById(instanceId, output.appId)
            : yield* findQAppByTitle(instanceId, yield* createTitle(id, olds ?? {}));
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.attrs.tags as Tags))
            ? state.attrs
            : Unowned(state.attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          // A Q App is bound to its Q Business application environment
          // instance at creation.
          if (olds.instanceId !== news.instanceId) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news) {
            return yield* new QAppInvalidProps({ message: "QApps QApp requires props" });
          }
          const title = yield* createTitle(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — prefer the cached id; fall back to a title lookup so a
          // create whose state failed to persist is adopted, not duplicated.
          let state = output?.appId
            ? yield* readQAppById(news.instanceId, output.appId)
            : yield* findQAppByTitle(news.instanceId, title);

          // Ensure — create if missing.
          if (state === undefined) {
            const created = yield* qapps.createQApp({
              instanceId: news.instanceId,
              title,
              description: news.description,
              appDefinition: {
                cards: news.appDefinition.cards,
                initialPrompt: news.appDefinition.initialPrompt,
              },
              tags: desiredTags,
            });
            yield* session.note(`Created Q App ${title} (${created.appId})`);
            state = yield* readQAppById(news.instanceId, created.appId);
            if (state === undefined) {
              return yield* new QAppUnexpectedResponse({
                message: `failed to read created Q App ${title}`,
              });
            }
          }

          // Sync title/description/definition via UpdateQApp — only on drift.
          const observed = state.observed;
          const needsUpdate =
            title !== observed.title ||
            (news.description ?? "") !== (observed.description ?? "") ||
            definitionDrifted(news.appDefinition, observed);
          if (needsUpdate) {
            yield* qapps.updateQApp({
              instanceId: news.instanceId,
              appId: state.attrs.appId,
              title,
              description: news.description,
              appDefinition: {
                cards: news.appDefinition.cards,
                initialPrompt: news.appDefinition.initialPrompt,
              },
            });
            yield* session.note(`Updated Q App ${title}`);
          }

          // Sync tags — diff against observed cloud tags.
          const { removed, upsert } = diffTags(state.attrs.tags, desiredTags);
          if (removed.length > 0) {
            yield* qapps.untagResource({
              resourceARN: state.attrs.appArn,
              tagKeys: removed,
            });
          }
          if (upsert.length > 0) {
            yield* qapps.tagResource({
              resourceARN: state.attrs.appArn,
              tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
            });
          }

          yield* session.note(state.attrs.appArn);

          const final = yield* readQAppById(news.instanceId, state.attrs.appId);
          if (!final) {
            return yield* new QAppUnexpectedResponse({
              message: `failed to read reconciled Q App ${title}`,
            });
          }
          return final.attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* qapps
            .deleteQApp({
              instanceId: output.instanceId,
              appId: output.appId,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );