@highstate/backend 0.9.18 → 0.9.20

package/src/shared/models/project/operation.ts

@@ -1,139 +1,275 @@
-import { z } from "zod"
-import { objectMetaSchema } from "@highstate/contract"
+import type { Operation, OperationStatus, OperationType } from "../../../database"
+import { instanceIdSchema, objectMetaSchema, z } from "@highstate/contract"
 
-export const operationTypeSchema = z.enum(["update", "preview", "destroy", "recreate", "refresh"])
+/**
+ * Phase type for operation execution.
+ */
+export const operationPhaseTypeSchema = z.enum(["destroy", "update", "refresh"])
 
-export const operationStatusSchema = z.enum([
-  "pending",
-  "running",
-  "completed",
-  "failed",
-  "cancelled",
-  "failing",
-])
-
-export const operationOptionsSchema = z.object({
+/**
+ * Instance information for operation phase.
+ */
+export const operationPhaseInstanceSchema = z.object({
   /**
-   * Whether to force update all dependencies of the instances even if they are not changed.
-   *
-   * Only applicable for `update`, `preview`, `recreate`, and `refresh` operations.
-   *
-   * By default, `false`.
+   * The ID of the instance.
    */
-  forceUpdateDependencies: z.boolean().default(false),
+  id: instanceIdSchema,
 
   /**
-   * Whether to force update all children of the composite instances even if they are not changed.
-   *
-   * Only applicable for `update`, `preview`, `recreate`, and `refresh` operations.
-   *
-   * By default, `false`.
+   * The parent ID of the instance, either from the model or the state.
    */
-  forceUpdateChildren: z.boolean().default(false),
+  parentId: z.string().optional(),
 
   /**
-   * Whether to destroy all dependents of the instances when destroying them.
-   *
-   * Only applicable for `destroy` and `recreate` operations.
-   *
-   * By default, `true`.
-   */
-  destroyDependentInstances: z.boolean().default(true),
+   * Human-readable explanation of the decision.
+   * */
+  message: z.string(),
+})
 
+/**
+ * Single phase of operation execution.
+ */
+export const operationPhaseSchema = z.object({
   /**
-   * Whether to invoke destroy triggers when destroying the instances.
-   *
-   * Only applicable for `destroy`.
-   *
-   * By default, `true`.
+   * Type of phase being executed.
    */
-  invokeDestroyTriggers: z.boolean().default(true),
+  type: operationPhaseTypeSchema,
 
   /**
-   * Whether to delete unreachable resources when updating or destroying the instances.
-   * This is potentially dangerous and should be used with caution.
-   *
-   * By default, `false`.
+   * List of instances to be processed in this phase.
    */
-  deleteUnreachableResources: z.boolean().default(false),
+  instances: z.array(operationPhaseInstanceSchema),
+})
 
-  /**
-   * Whether to delete the stack state even if the destroy operation fails.
-   * This is very dangerous and should be used only when the stack is unrecoverable.
-   *
-   * By default, `false`.
-   */
-  forceDeleteState: z.boolean().default(false),
+export type OperationPhase = z.infer<typeof operationPhaseSchema>
+export type OperationPhaseType = z.infer<typeof operationPhaseTypeSchema>
+export type OperationPhaseInstance = z.infer<typeof operationPhaseInstanceSchema>
 
-  /**
-   * Whether to allow partial updates of composite instances when updating, destroying or recreating them.
-   *
-   * If `true`, the operation will only update/destroy composite instance children that are directly referenced by other affected instances.
-   * If `false`, the operation will update/destroy all children at of the composite instances at all levels if at least one of them is referenced by affected instances.
-   *
-   * By default, `false`.
-   */
-  allowPartialCompositeInstanceUpdates: z.boolean().default(false),
+export const operationOptionsSchema = z
+  .object({
+    /**
+     * Force update all dependencies regardless of their current state.
+     *
+     * **Operation Behavior Impact:**
+     * - bypasses hash-based change detection for dependency chains;
+     * - includes **ALL** dependencies (up-to-date, out-of-date, and error states);
+     * - traverses the entire dependency graph from requested instances.
+     *
+     * **Usage with other options:**
+     * - combined with `forceUpdateChildren`: updates entire dependency tree **AND** all composite children;
+     * - independent of `allowPartialCompositeInstanceCreation`: affects dependency traversal, not composite logic.
+     */
+    forceUpdateDependencies: z.boolean().default(false),
 
-  /**
-   * Whether to refresh the state before running the operation.
-   *
-   * By default, `false`.
-   */
-  refresh: z.boolean().default(false),
-})
+    /**
+     * Force update all children of composite instances regardless of their state.
+     *
+     * **Operation Behavior Impact:**
+     * - overrides selective child inclusion logic for composites;
+     * - includes **ALL** children of affected composites (up-to-date, out-of-date, and error states);
+     * - applied after dependency traversal and parent inclusion.
+     *
+     * **Usage with other options:**
+     * - combined with `forceUpdateDependencies`: creates comprehensive force-update behavior;
+     * - overrides `allowPartialCompositeInstanceCreation`: when enabled, **ALL** children are included regardless of existence.
+     */
+    forceUpdateChildren: z.boolean().default(false),
 
-export const operationRequestSchema = z.object({
-  projectId: z.string(),
-  type: operationTypeSchema,
-  instanceIds: z.array(z.string()),
-  options: operationOptionsSchema.partial().optional(),
-})
+    /**
+     * Include dependent instances when destroying instances.
+     *
+     * **Operation Behavior Impact:**
+     * - extends destroy operations to include instances that depend on the target;
+     * - traverses the dependency graph in reverse (dependents, not dependencies);
+     * - prevents orphaned instances that would fail without their dependencies.
+     *
+     * **Usage with other options:**
+     * - works with `invokeDestroyTriggers`: ensures triggers run for all dependents;
+     * - independent of update-related options.
+     */
+    destroyDependentInstances: z.boolean().default(true),
 
-export const operationSchema = z.object({
-  id: z.uuidv7(),
-  meta: objectMetaSchema,
-  status: operationStatusSchema,
+    /**
+     * Execute destroy triggers when destroying instances.
+     *
+     * **Operation Behavior Impact:**
+     * - affects how individual units are destroyed (triggers vs direct deletion);
+     * - does not change which instances are selected for destruction;
+     * - controls trigger execution during the destruction phase.
+     *
+     * **Usage with other options:**
+     * - used with `destroyDependentInstances`: ensures triggers run for cascade deletions;
+     * - independent of update-related options.
+     */
+    invokeDestroyTriggers: z.boolean().default(true),
 
-  error: z.string().nullable(),
+    /**
+     * Delete Pulumi resources that are no longer referenced in the state.
+     *
+     * **Operation Behavior Impact:**
+     * - does not affect which instances are selected for operations;
+     * - deletes orphaned Pulumi resources within individual instances.
+     *
+     * **Usage with other options:**
+     * - independent of instance selection options;
+     * - complements destroy-related options for thorough cleanup.
+     */
+    deleteUnreachableResources: z.boolean().default(false),
 
-  type: operationTypeSchema,
+    /**
+     * Force deletion of instance state even if the destroy operation fails.
+     *
+     * **Operation Behavior Impact:**
+     * - forces state deletion even when destroy operations fail;
+     * - does not affect which instances are selected for operations;
+     * - bypasses normal destroy procedures as emergency fallback.
+     *
+     * **Usage with other options:**
+     * - used with destroy-related options when normal cleanup fails;
+     * - should be used cautiously as it can create state inconsistencies.
+     */
+    forceDeleteState: z.boolean().default(false),
 
-  requestedInstanceIds: z.array(z.string()),
+    /**
+     * Allow partial update of composite instances without requiring all outdated children.
+     *
+     * **Operation Behavior Impact:**
+     * - controls whether composite operations must include all outdated children or only necessary ones;
+     * - when `false` (default): all outdated children of substantive composites are included in operations;
+     * - when `true`: only necessary children are included, allowing partial composite operations;
+     * - applied during composite child traversal phase for substantive composites only.
+     *
+     * **Usage with other options:**
+     * - overridden by `forceUpdateChildren`: when force is enabled, **ALL** children are included regardless;
+     * - independent of `forceUpdateDependencies`: affects composite logic, not dependency traversal.
+     */
+    allowPartialCompositeInstanceUpdate: z.boolean().default(false),
 
-  instanceIdsToUpdate: z.array(z.string()).default(() => []),
-  instanceIdsToDestroy: z.array(z.string()).default(() => []),
+    /**
+     * Allow partial destruction of composite instances during cascade operations.
+     *
+     * **Operation Behavior Impact:**
+     * - controls whether cascade destruction must include all children or only necessary ones;
+     * - when `false` (default): cascade destruction includes **ALL** children of affected composites;
+     * - when `true`: cascade destruction includes only directly dependent children;
+     * - does not affect explicit composite destruction (always destroys all children);
+     * - does not affect parent propagation when destroying sibling composites.
+     *
+     * **Usage with other options:**
+     * - works with `destroyDependentInstances`: controls completeness of cascade destruction;
+     * - independent of update-related options.
+     */
+    allowPartialCompositeInstanceDestruction: z.boolean().default(false),
 
-  options: operationOptionsSchema,
+    /**
+     * Also refresh the state of instances during the operation.
+     *
+     * **Operation Behavior Impact:**
+     * - does not change which instances are selected for operations;
+     * - synchronizes state with actual infrastructure during the operation.
+     *
+     * **Usage with other options:**
+     * - additive with dependency resolution options: refreshes all selected instances;
+     * - works with both all operation types.
+     */
+    refresh: z.boolean().default(false),
 
-  startedAt: z.number(),
-  completedAt: z.number().nullable(),
-})
+    /**
+     * Enable debug logging for Pulumi engine and resource providers.
+     *
+     * **Security Note:**
+     * Debug mode may expose sensitive information including credentials in the logs.
+     * Use only when absolutely necessary for troubleshooting.
+     *
+     * **Implementation:**
+     * - sets Pulumi's debug option to true;
+     * - sets TF_LOG=DEBUG environment variable for Terraform providers.
+     */
+    debug: z.boolean().default(false),
+  })
+  .partial()
 
-export type OperationType = z.infer<typeof operationTypeSchema>
-export type OperationStatus = z.infer<typeof operationStatusSchema>
-export type Operation = z.infer<typeof operationSchema>
-export type OperationRequest = z.infer<typeof operationRequestSchema>
-export type OperationOptions = z.infer<typeof operationOptionsSchema>
+export const operationTypeSchema = z.enum([
+  "update",
+  "preview",
+  "destroy",
+  "recreate",
+  "refresh",
+]) satisfies z.ZodType<OperationType>
 
-export function isFinalOperationStatus(status: OperationStatus): boolean {
-  return status === "completed" || status === "failed" || status === "cancelled"
-}
+export const operationStatusSchema = z.enum([
+  "pending",
+  "running",
+  "failing",
+  "completed",
+  "failed",
+  "cancelled",
+]) satisfies z.ZodType<OperationStatus>
 
-export const operationLogEntrySchema = z.tuple([
-  z.uuidv7(),
-  z.string(), // The log message
-])
+export const operationMetaSchema = objectMetaSchema.pick({
+  title: true,
+  description: true,
+})
+
+export const operationInputSchema = z.object({
+  projectId: z.string(),
+  type: operationTypeSchema,
+  instanceIds: z.array(instanceIdSchema).min(1),
+  options: operationOptionsSchema.partial().optional(),
+  meta: operationMetaSchema.optional(),
+  plan: operationPhaseSchema.array().optional(),
+})
 
-export type OperationLogEntry = z.infer<typeof operationLogEntrySchema>
+export type OperationMeta = z.infer<typeof operationMetaSchema>
+export type OperationInput = z.infer<typeof operationInputSchema>
+export type OperationOptions = z.infer<typeof operationOptionsSchema>
 
 export const operationEventSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("updated"),
-    operation: operationSchema,
+    operation: z.custom<Operation>(),
   }),
   z.object({
     type: z.literal("deleted"),
     operationId: z.string(),
   }),
 ])
+
+export const operationOutputSchema = z.object({
+  id: z.cuid2(),
+  type: operationTypeSchema,
+  status: operationStatusSchema,
+  meta: operationMetaSchema,
+  startedAt: z.date(),
+  updatedAt: z.date(),
+  finishedAt: z.date().nullable(),
+})
+
+export type OperationOutput = z.infer<typeof operationOutputSchema>
+
+export type { Operation, OperationLog, OperationStatus, OperationType } from "../../../database"
+
+export const finalOperationStatuses: OperationStatus[] = ["completed", "failed", "cancelled"]
+
+/**
+ * Checks if an operation status is final (stable).
+ *
+ * Final statuses are: completed, failed, cancelled
+ * Transient statuses are: pending, running, failing
+ *
+ * @param status The operation status to check
+ * @returns True if the status is final
+ */
+export function isFinalOperationStatus(status: OperationStatus): boolean {
+  return finalOperationStatuses.includes(status)
+}
+
+/**
+ * Checks if an operation status exists and is transient (not stable).
+ *
+ * @param status The operation status to check
+ * @returns True if the status is transient
+ */
+export function isTransientOperationStatus(status?: OperationStatus): boolean {
+  return !!status && !finalOperationStatuses.includes(status)
+}

package/src/shared/models/project/page.ts

@@ -1,57 +1,46 @@
+import type { ServiceAccount } from "../../../database"
+import {
+  commonObjectMetaSchema,
+  pageBlockSchema,
+  serviceAccountMetaSchema,
+} from "@highstate/contract"
 import { z } from "zod"
-import { fileSchema, objectMetaSchema, userObjectMetaSchema } from "@highstate/contract"
-
-/**
- * Page block schema for database storage and unit API.
- */
-export const pageBlockSchema = z.union([
-  z.object({
-    type: z.literal("markdown"),
-    content: z.string(),
-  }),
-  z.object({
-    type: z.literal("qr"),
-    content: z.string(),
-    showContent: z.coerce.boolean(),
-    language: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal("file"),
-    ...fileSchema.shape,
-  }),
-])
-
-export type PageBlock = z.infer<typeof pageBlockSchema>
-
-/**
- * Page info for frontend display.
- * Contains only basic information visible to the frontend.
- */
-export const pageSchema = z.object({
-  id: z.string(),
-  instanceId: z.string().optional(),
-  meta: objectMetaSchema,
+import { collectionQuerySchema } from "../base"
+
+export const pageOutputSchema = z.object({
+  id: z.cuid2(),
+  meta: commonObjectMetaSchema,
+  name: z.string().nullable(),
+  stateId: z.cuid2().nullable(),
+  serviceAccountId: z.cuid2().nullable(),
+  serviceAccountMeta: serviceAccountMetaSchema.nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
 })
 
-export type Page = z.infer<typeof pageSchema>
+export type PageOutput = z.infer<typeof pageOutputSchema>
 
-/**
- * The content of a page separated from the page info.
- */
-export const pageContentSchema = z.object({
-  id: z.string(),
-  content: z.array(pageBlockSchema),
+export const pageQuerySchema = collectionQuerySchema.extend({
+  serviceAccountId: z.string().optional(),
+  stateId: z.string().optional(),
+  artifactId: z.string().optional(),
 })
 
-export type PageContent = z.infer<typeof pageContentSchema>
+export type PageQuery = z.infer<typeof pageQuerySchema>
 
-/**
- * Page schema for unit API.
- * This is what units provide - excludes id, instanceId and some fields from meta since those are set by the system.
- */
-export const unitPageSchema = pageContentSchema.omit({ id: true }).extend({
-  name: z.string(),
-  meta: userObjectMetaSchema,
+export const pageDetailsOutputSchema = z.object({
+  ...pageOutputSchema.shape,
+  content: z.array(pageBlockSchema),
 })
 
-export type UnitPage = z.infer<typeof unitPageSchema>
+export type PageDetailsOutput = z.infer<typeof pageDetailsOutputSchema>
+
+export function toPageOutput(
+  page: Omit<PageOutput, "serviceAccountMeta">,
+  serviceAccount?: Pick<ServiceAccount, "meta"> | null,
+): PageOutput {
+  return {
+    ...page,
+    serviceAccountMeta: serviceAccount?.meta ?? null,
+  }
+}

package/src/shared/models/project/secret.ts

@@ -1,98 +1,38 @@
-import { z } from "zod"
-import { objectMetaSchema } from "@highstate/contract"
-
-export const secretDescriptorSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("system"),
-    secretName: z.string(),
-  }),
-  z.object({
-    type: z.literal("instance"),
-    instanceId: z.string(),
-    secretName: z.string(),
-  }),
-])
-
-/**
- * Secret info for frontend display.
- * Contains only basic information visible to the frontend without the actual secret value.
- */
-export const secretSchema = z.object({
-  /**
-   * The UUIDv7 of the secret generated when the secret is first created.
-   */
-  id: z.uuidv7(),
+import type { ServiceAccount } from "../../../database"
+import { globalCommonObjectMetaSchema, serviceAccountMetaSchema, z } from "@highstate/contract"
+import { collectionQuerySchema } from "../base"
+
+export const secretOutputSchema = z.object({
+  id: z.cuid2(),
+  meta: globalCommonObjectMetaSchema,
+  name: z.string().nullable(),
+  systemName: z.string().nullable(),
+  stateId: z.cuid2().nullable(),
+  serviceAccountId: z.cuid2().nullable(),
+  serviceAccountMeta: serviceAccountMetaSchema.nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
 
-  /**
-   * The metadata of the secret object.
-   */
-  meta: objectMetaSchema,
+export type SecretOutput = z.infer<typeof secretOutputSchema>
 
-  /**
-   * The descriptor of the secret in the object form, which follows one of these formats when serialized:
-   * - `system:<secretName>`
-   * - `instance:<instanceId>:<secretName>`
-   */
-  descriptor: secretDescriptorSchema.optional(),
+export const secretQuerySchema = collectionQuerySchema.extend({
+  serviceAccountId: z.string().optional(),
+  stateId: z.string().optional(),
 })
 
-export type SecretDescriptor = z.infer<typeof secretDescriptorSchema>
-export type Secret = z.infer<typeof secretSchema>
+export type SecretQuery = z.infer<typeof secretQuerySchema>
 
-/**
- * Formats a SecretDescriptor into a string representation.
- *
- * @param descriptor The SecretDescriptor to format.
- * @returns The formatted secret descriptor string.
- */
-export function formatSecretDescriptor(descriptor: SecretDescriptor): string {
-  switch (descriptor.type) {
-    case "system":
-      return `system:${descriptor.secretName}`
-    case "instance":
-      return `instance:${descriptor.instanceId}:${descriptor.secretName}`
+export function toSecretOutput(
+  secret: Omit<SecretOutput, "serviceAccountMeta">,
+  serviceAccount?: Pick<ServiceAccount, "meta"> | null,
+): SecretOutput {
+  return {
+    ...secret,
+    serviceAccountMeta: serviceAccount?.meta ?? null,
   }
 }
 
-/**
- * Parses a secret descriptor string into a structured SecretDescriptor object.
- *
- * @param descriptorString The secret descriptor string to parse.
- * @returns The parsed SecretDescriptor object.
- * @throws Error if the secret descriptor format is invalid.
- */
-export function parseSecretDescriptor(descriptorString: string): SecretDescriptor {
-  const parts = descriptorString.split(":")
-  if (parts.length < 2) {
-    throw new Error(`Invalid secret descriptor format: ${descriptorString}`)
-  }
-
-  switch (parts[0]) {
-    case "system": {
-      if (parts.length !== 2) {
-        throw new Error(`Invalid system secret descriptor: ${descriptorString}`)
-      }
-      return { type: "system", secretName: parts[1] }
-    }
-
-    case "instance": {
-      // instance format is "instance:<instanceId>:<secretName>" where instanceId may contain colons
-      const secretName = parts[parts.length - 1]
-      const instanceId = parts.slice(1, -1).join(":")
-      if (!instanceId || !secretName) {
-        throw new Error(`Invalid instance secret descriptor: ${descriptorString}`)
-      }
-      return { type: "instance", instanceId, secretName }
-    }
-
-    default:
-      throw new Error(`Unknown secret descriptor type: ${parts[0]}`)
-  }
+export enum SystemSecretNames {
+  PulumiPassword = "pulumi-password",
 }
-
-export const WellKnownSecretDescriptors = {
-  PulumiPassword: {
-    type: "system",
-    secretName: "pulumi-password",
-  },
-} satisfies Record<string, SecretDescriptor>

package/src/shared/models/project/service-account.ts

@@ -1,22 +1,17 @@
-import { z } from "zod"
-import { objectMetaSchema } from "@highstate/contract"
+import { serviceAccountMetaSchema, z } from "@highstate/contract"
+import { collectionQuerySchema } from "../base"
 
-export const serviceAccountSchema = z.object({
-  id: z.uuidv7(),
+export const serviceAccountOutputSchema = z.object({
+  id: z.cuid2(),
+  meta: serviceAccountMetaSchema,
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
 
-  meta: objectMetaSchema.pick({
-    title: true,
-    description: true,
-    icon: true,
-    iconColor: true,
-    createdAt: true,
-    updatedAt: true,
-  }),
+export type ServiceAccountOutput = z.infer<typeof serviceAccountOutputSchema>
 
-  /**
-   * The ID of the artifact that stores the avatar image for this service account.
-   */
-  avatarArtifactId: z.string().optional(),
+export const serviceAccountQuerySchema = collectionQuerySchema.extend({
+  artifactId: z.string().optional(),
 })
 
-export type ServiceAccount = z.infer<typeof serviceAccountSchema>
+export type ServiceAccountQuery = z.infer<typeof serviceAccountQuerySchema>