@spec append_project_head(Lightning.Projects.Project.t(), String.t()) ::
  {:ok, Lightning.Projects.Project.t()} | {:error, :bad_hash}

Appends a new 12-hex head hash to project.version_history (append-only).

This is a lenient wrapper that validates using Lightning.Validators.Hex.valid?(hash) and returns tagged tuples. For atomic locking and errors by exception, use append_project_head!/2.

Validation

• hash must be 12 lowercase hex characters (0-9, a-f).
• No duplicates: if the hash already exists in the array, this is a no-op.

Concurrency

The underlying !/2 variant locks the row (FOR UPDATE) to avoid lost updates.

@spec append_project_head!(Lightning.Projects.Project.t(), String.t()) ::
  Lightning.Projects.Project.t()

Like append_project_head/2, but raises on invalid input and performs the append within a transaction that locks the project row.

Behavior

• Raises ArgumentError if hash is not 12 lowercase hex.
• Uses SELECT … FOR UPDATE to read the current array, appends if missing, and writes back in the same transaction.
• Idempotent: if the hash is already present, returns the unchanged project.

Returns an %Ecto.Changeset{} for tracking project changes.

Examples

iex> change_project(project)
%Ecto.Changeset{data: %Project{}}

Computes a deterministic 12-hex “project head” hash from the latest version hash per workflow.

The algorithm:

1. For each workflow in the project, select the most recent row in workflow_versions by (inserted_at DESC, id DESC).
2. Build pairs [[workflow_id_as_string, hash], ...].
3. JSON-encode the pairs and take sha256 of the bytes.
4. Return the first 12 lowercase hex chars.

Guarantees

• Deterministic for a given set of latest heads.
• If a project has no workflow versions, returns the digest of [], i.e. a stable 12-hex string representing “empty”.

Use cases

• Change detection across environments.
• Cache keys and optimistic comparisons (e.g. “is this workspace up-to-date?”).

Creates a project.

Examples

iex> create_project(%{field: value})
{:ok, %Project{}}

iex> create_project(%{field: bad_value})
{:error, %Ecto.Changeset{}}

@spec create_sandbox(Lightning.Projects.Project.t(), map(), boolean()) ::
  {:ok, Lightning.Projects.Project.t()} | {:error, Ecto.Changeset.t()}

Creates a sandbox under the given parent by delegating to create_project/2.

This is a convenience wrapper that sets :parent_id and preserves the existing behavior around collaborator emails (off by default unless schedule_email? is true).

Notes

• Child names are scoped-unique by (parent_id, name). Root names may repeat, but two siblings cannot share a name (enforced by the projects_unique_child_name index).
• This function does not clone workflows, credentials, or dataclips. It only creates a new project row with parent_id set. See sandbox provisioning flow for full cloning.

Returns

• {:ok, %Project{}} on success
• {:error, %Ecto.Changeset{}} on validation/unique errors

Deletes a project and its related data, including workflows, work orders, steps, jobs, runs, triggers, project users, project credentials, and dataclips

Examples

iex> delete_project(project)
{:ok, %Project{}}

iex> delete_project(project)
{:error, %Ecto.Changeset{}}

@spec delete_project_dataclips(Lightning.Projects.Project.t(), non_neg_integer()) ::
  :ok

Deletes project dataclips in batches

@spec delete_project_user!(Lightning.Projects.ProjectUser.t()) ::
  Lightning.Projects.ProjectUser.t()

Deletes a project user and removes their credentials from the project.

This function:

1. Deletes the association between the user and the project
2. Removes any credentials owned by the user from the project

All operations are performed within a transaction for data consistency.

Parameters

• project_user: The ProjectUser struct to be deleted

Returns

• The deleted ProjectUser struct

@spec delete_project_workorders(Lightning.Projects.Project.t(), non_neg_integer()) ::
  :ok

Deletes project work orders in batches

@spec export_project(atom(), Ecto.UUID.t(), [Ecto.UUID.t()] | nil) :: {:ok, binary()}

Exports a project as yaml.

Examples

iex> export_project(:yaml, project_id)
{:ok, string}

@spec get_project(Ecto.UUID.t()) :: Lightning.Projects.Project.t() | nil

Fetches a project by id (root or sandbox) and preloads its direct :parent.

Returns nil if no project with the given id exists.

@spec get_project!(Ecto.UUID.t()) :: Lightning.Projects.Project.t()

Fetches a project by id (root or sandbox) and preloads its direct :parent.

Raises Ecto.NoResultsError if no project with the given id exists.

Gets a single project_user.

Raises Ecto.NoResultsError if the ProjectUser does not exist.

Examples

iex> get_project_user!(123)
%ProjectUser{}

iex> get_project_user!(456)
** (Ecto.NoResultsError)

@spec get_project_user_role(
  user :: Lightning.Accounts.User.t(),
  project :: Lightning.Projects.Project.t()
) :: atom() | nil

Returns the role of a user in a project. Possible roles are :admin, :viewer, :editor, and :owner

Examples

iex> get_project_user_role(user, project)
:admin

iex> get_project_user_role(user, project)
:viewer

iex> get_project_user_role(user, project)
:editor

iex> get_project_user_role(user, project)
:owner

Get all project users for a given project

Gets a single project with it's members via project_users.

Raises Ecto.NoResultsError if the Project does not exist.

Examples

iex> get_project!(123)
%Project{}

iex> get_project!(456)
** (Ecto.NoResultsError)

@spec get_projects_for_user(user :: Lightning.Accounts.User.t()) :: [
  Lightning.Projects.Project.t()
]

Fetches projects for a given user from the database.

Parameters

• user: The user struct for which projects are being queried.
• opts: Keyword list of options including :include for associations to preload and :order_by for sorting.

Returns

• A list of projects associated with the user.

@spec get_workspace_projects(Lightning.Projects.Project.t()) :: [
  Lightning.Projects.Project.t()
]

Returns a read-only “workspace” view for a parent project: the parent itself plus all of its direct sandboxes (unique set, no preloads).

Use this for nav/filters where showing the parent alongside its sandboxes is needed.

Notes

• Order is not guaranteed. Sort the resulting list if a specific order is needed.
• Not recursive. If we later model deeper hierarchies, use a recursive CTE.

@spec list_project_admin_emails(Ecto.UUID.t()) :: [String.t(), ...] | []

Lists emails of users with :owner or :admin roles in the project

Returns the list of projects.

Examples

iex> list_projects()
[%Project{}, ...]

@spec list_projects_having_history_retention() ::
  [] | [Lightning.Projects.Project.t(), ...]

Lists all projects that have history retention

@spec list_sandboxes(Ecto.UUID.t()) :: [Lightning.Projects.Project.t()]

Returns the direct sandboxes (children) of a parent project, ordered by name (ASC).

This is a flat view: only rows where parent.id == child.parent_id are returned. If we later support arbitrarily deep nesting, switch this to a recursive CTE.

Perform, when called with %{"type" => "purge_deleted"} will find projects that are ready for permanent deletion and purge them.

@spec projects_for_user_query(user :: Lightning.Accounts.User.t()) ::
  Ecto.Queryable.t()

Builds a query to retrieve projects associated with a user.

Parameters

• user: The user struct for which projects are being queried.
• opts: Keyword list of options including :include for associations to preload and :order_by for sorting.

Returns

• An Ecto queryable struct to fetch projects.

@spec provision_sandbox(
  Lightning.Projects.Project.t(),
  Lightning.Accounts.User.t(),
  map()
) ::
  {:ok, Lightning.Projects.Project.t()} | {:error, term()}

Provisions a sandbox (child) project under the given parent.

This is a thin wrapper around Lightning.Projects.Sandboxes.provision/3.

Authorization

The actor must be an :owner or :admin of the parent project. Returns {:error, :unauthorized} otherwise.

Attributes (attrs)

• :name (required) — Sandbox name (must be unique per parent_id).
• :color — Optional hex color (string) for the project.
• :env — Optional environment slug to set on the project.
• :collaborators — Optional list of %{user_id: Ecto.UUID.t(), role: atom()}. The actor is always added as :owner; extra :owner entries are ignored.
• :dataclip_ids — Optional list of named dataclip IDs to copy (eligible types: :global | :saved_input | :http_request).

Behavior

• Clones a subset of project settings from the parent.
• References existing credentials via project_credentials (no credential duplication).
• Clones the workflow DAG (jobs, triggers, edges), disables triggers in the clone, remaps node positions, and copies the latest workflow head/version per workflow.
• Does not copy runs/history.

Examples

iex> provision_sandbox(parent, actor, %{name: "SB-1", color: "#aabbcc"})
{:ok, %Lightning.Projects.Project{}}

iex> provision_sandbox(parent, viewer, %{name: "SB-1"})
{:error, :unauthorized}

@spec root_of(Lightning.Projects.Project.t()) :: Lightning.Projects.Project.t()

Returns the root ancestor of a project by walking up parent_id links.

Supports arbitrarily deep nesting. (Assumes the parent chain is well-formed.)

Should input or output dataclips be saved for runs in this project?

Given a project, this function sets a scheduled deletion date based on the PURGE_DELETED_AFTER_DAYS environment variable. If no ENV is set, this date defaults to NOW but the automatic project purge cronjob will never run. (Note that subsequent logins will be blocked for projects pending deletion.)

See Lightning.Projects.Events.subscribe/0.

Updates a project.

Examples

iex> update_project(project, %{field: new_value})
{:ok, %Project{}}

iex> update_project(project, %{field: bad_value})
{:error, %Ecto.Changeset{}}

Updates a project user.

Examples

iex> update_project_user(project_user, %{field: new_value})
{:ok, %ProjectUser{}}

iex> update_project_user(projectUser, %{field: bad_value})
{:error, %Ecto.Changeset{}}

Returns an %Ecto.Changeset{} for changing the project scheduled_deletion.

Examples

iex> validate_for_deletion(project)
%Ecto.Changeset{data: %Project{}}