Codex.Plugins (Codex SDK v0.16.1)

Local plugin authoring helpers for manifests, marketplaces, and scaffold flows.

This namespace is intentionally separate from the app-server runtime APIs on Codex.AppServer. Use Codex.Plugins.* to author files locally with normal Elixir file IO. Use Codex.AppServer.plugin_* only when you want runtime discovery, read, install, or uninstall verification against a running Codex app-server.

Summary

Types

scaffold_error()

scaffold_result()

Functions

add_marketplace_plugin(path, plugin, opts \\ [])

Safely appends or replaces one marketplace entry without erasing unrelated entries.

new_manifest(attrs)

Builds and validates a manifest struct.

new_marketplace(attrs)

Builds and validates a marketplace struct.

read_manifest(path)

Reads and validates a local plugin manifest.

read_marketplace(path)

Reads and validates a local marketplace file.

scaffold(opts)

Scaffolds a minimal local plugin tree.

validate_manifest(attrs)

Validates manifest data and returns normalized issues on failure.

validate_marketplace(attrs)

Validates marketplace data and returns normalized issues on failure.

write_manifest(path, manifest, opts \\ [])

Writes a manifest deterministically using local file IO.

write_marketplace(path, marketplace, opts \\ [])

Writes a marketplace deterministically using local file IO.

Types

scaffold_error()

@type scaffold_error() ::
  {:plugin_io, %{action: atom(), path: String.t(), reason: term()}}
  | {:invalid_plugin_json,
     %{path: String.t(), reason: String.t(), raw_reason: term()}}
  | {:plugin_file_exists, %{path: String.t()}}
  | {:repo_root_not_found, %{cwd: String.t()}}
  | {:invalid_plugin_scope, %{scope: term()}}
  | {:invalid_plugin_name, %{name: term(), message: String.t()}}
  | {:invalid_plugin_root, %{path: String.t(), message: String.t()}}
  | {:invalid_marketplace_path, %{path: String.t(), message: String.t()}}
  | {:invalid_marketplace_source_path,
     %{path: String.t(), source_path: String.t(), message: String.t()}}
  | {:plugin_conflict, %{path: String.t(), plugin_name: String.t()}}
  | {:invalid_plugin_manifest, CliSubprocessCore.Schema.error_detail()}
  | {:invalid_plugin_marketplace, CliSubprocessCore.Schema.error_detail()}
  | {:invalid_plugin_marketplace_plugin,
     CliSubprocessCore.Schema.error_detail()}

scaffold_result()

@type scaffold_result() :: %{
  scope: Codex.Plugins.Paths.scope(),
  plugin_name: String.t(),
  plugin_root: String.t(),
  manifest_path: String.t(),
  manifest: Codex.Plugins.Manifest.t(),
  skill_paths: [String.t()],
  marketplace_path: String.t() | nil,
  marketplace: Codex.Plugins.Marketplace.t() | nil,
  created_paths: [String.t()]
}

Functions

add_marketplace_plugin(path, plugin, opts \\ [])

@spec add_marketplace_plugin(Path.t(), map() | keyword(), keyword()) ::
  {:ok, map()} | {:error, term()}

Safely appends or replaces one marketplace entry without erasing unrelated entries.

new_manifest(attrs)

@spec new_manifest(map() | keyword() | Codex.Plugins.Manifest.t()) ::
  {:ok, Codex.Plugins.Manifest.t()} | {:error, term()}

Builds and validates a manifest struct.

new_marketplace(attrs)

@spec new_marketplace(map() | keyword() | Codex.Plugins.Marketplace.t()) ::
  {:ok, Codex.Plugins.Marketplace.t()} | {:error, term()}

Builds and validates a marketplace struct.

read_manifest(path)

@spec read_manifest(Path.t()) :: {:ok, Codex.Plugins.Manifest.t()} | {:error, term()}

Reads and validates a local plugin manifest.

read_marketplace(path)

@spec read_marketplace(Path.t()) ::
  {:ok, Codex.Plugins.Marketplace.t()} | {:error, term()}

Reads and validates a local marketplace file.

scaffold(opts)

@spec scaffold(keyword()) :: {:ok, scaffold_result()} | {:error, scaffold_error()}

Scaffolds a minimal local plugin tree.

validate_manifest(attrs)

@spec validate_manifest(map() | keyword() | Codex.Plugins.Manifest.t()) ::
  :ok | {:error, [map()]}

Validates manifest data and returns normalized issues on failure.

validate_marketplace(attrs)

@spec validate_marketplace(map() | keyword() | Codex.Plugins.Marketplace.t()) ::
  :ok | {:error, [map()]}

Validates marketplace data and returns normalized issues on failure.

write_manifest(path, manifest, opts \\ [])

@spec write_manifest(
  Path.t(),
  map() | keyword() | Codex.Plugins.Manifest.t(),
  keyword()
) ::
  :ok | {:error, term()}

Writes a manifest deterministically using local file IO.

write_marketplace(path, marketplace, opts \\ [])

@spec write_marketplace(
  Path.t(),
  map() | keyword() | Codex.Plugins.Marketplace.t(),
  keyword()
) ::
  :ok | {:error, term()}

Writes a marketplace deterministically using local file IO.