/** Declarative help for the `assistant plugins` command. */

import type { CliCommandHelp } from "../lib/cli-command-help.js";
import {
  DEFAULT_PIN_HISTORY_LIMIT,
  DEFAULT_PLUGIN_REF,
  DEFAULT_PLUGIN_UPGRADE_STRATEGY,
  PLUGIN_UPGRADE_STRATEGIES,
} from "../lib/plugin-constants.js";

export const pluginsHelp: CliCommandHelp = {
  name: "plugins",
  description: "List, search, install, and manage plugins.",
  helpText: `
Plugins are superpowers: installable extensions that add skills, tools, integrations,
and so much more from the Vellum Community. When the user asks to set up,
install, connect, or integrate a product, service, or app, run
'assistant plugins search <name>' first before searching the web.`,
  subcommands: [
    {
      name: "install",
      args: "<name-or-url>",
      description:
        "Install a plugin by name from the Vellum platform (content is served as a verified tarball from the plugin's pinned commit), or directly from a GitHub URL (untrusted)",
      options: [
        {
          flags: "--force",
          description:
            "Overwrite an existing install and skip the declared-schedules confirmation prompt",
        },
        {
          flags: "--ref <ref>",
          description: `For a marketplace install, the manifest revision to read the pin from (default: ${DEFAULT_PLUGIN_REF}). For a GitHub URL, the git ref (branch/tag/SHA) to clone — states a slash-containing branch (e.g. feature/x) explicitly and skips the remote ref lookup a bare /tree/ URL otherwise does`,
        },
        {
          flags: "--pin <sha>",
          description:
            "Install a specific reviewed marketplace pin (full commit SHA); run `plugins versions <name>` to list them. Marketplace installs only",
        },
        {
          flags: "--allow-unreviewed",
          description:
            "With --pin, install a SHA that is not in the reviewed marketplace history (advanced; the curated adapter may not match). Marketplace installs only",
        },
        {
          flags: "--name <name>",
          description:
            "Install directory name for a GitHub-URL install (default: derived from the repo or sub-path leaf). Ignored for marketplace installs",
        },
      ],
      helpText: `
A plugin that declares schedules (a schedules/ directory) has them listed
during the install, and the install asks for confirmation before finalizing:
schedules run automatically in the background once the plugin is installed.
Pass --force to skip the prompt (required for non-interactive installs).

A plugin that ships a setup skill (skills/setup/ or
skills/<name>-setup/) prints a line after install telling the user to
load that skill to finish setup.

A GitHub URL (anything containing a slash) installs directly from that repo,
bypassing the marketplace whitelist. Such a plugin is UNTRUSTED — it has not
been reviewed and its hooks/tools run with full assistant access — so the
install prints a warning. Use it for a plugin still under development that is
not in the catalog yet. The ref comes from the URL's /tree/<ref>/ segment, or
defaults to the repository's default branch. A branch whose name contains a
slash (e.g. feature/x) is resolved automatically against the repo's refs, just
as github.com does — paste the /tree/ URL as-is, or pass --ref to skip the
lookup (e.g. offline, or to force a specific ref).

Examples:
  $ assistant plugins install https://github.com/owner/repo
  $ assistant plugins install https://github.com/owner/repo/tree/my-branch/path/to/plugin
  $ assistant plugins install https://github.com/owner/repo/tree/feat/results-viewer/path
  $ assistant plugins install owner/repo --name my-plugin --force`,
    },
    {
      name: "versions",
      args: "<name>",
      description:
        "List the recent reviewed marketplace pins for a plugin, newest first. Install an older one with `plugins install <name> --pin <sha>`",
      options: [
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of a table",
        },
        {
          flags: "--limit <n>",
          description: `Maximum number of pins to show (default: ${DEFAULT_PIN_HISTORY_LIMIT})`,
        },
      ],
    },
    {
      name: "list",
      description: "List plugins installed in your workspace.",
      options: [
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of a table",
        },
        {
          flags: "--all",
          description:
            "Include first-party default plugins and disabled plugins in the listing",
        },
      ],
    },
    {
      name: "inspect",
      args: "<name>",
      description:
        "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools, schedules) it contributes",
      options: [
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of a summary",
        },
      ],
    },
    {
      name: "diff",
      args: "<name>",
      description:
        "Show a unified diff of local edits to an installed plugin against the commit it was installed at",
      options: [
        {
          flags: "--json",
          description:
            "Emit the machine-readable diff result as JSON (files: { path, status, diff, binary, reconstructed }[]) instead of a unified diff",
        },
      ],
      helpText: `
Arguments:
  name   Install name (kebab-case directory under the workspace plugins dir);
         run 'assistant plugins list' to see installed names.

The baseline is the exact commit the plugin was installed at (recorded in its
install-meta.json), re-materialized through the install pipeline — so an
install-time adapter transform never reads as a local change. To compare
against the marketplace's current pin instead, use 'plugins upgrade --dry-run'.

Examples:
  $ assistant plugins diff example
  $ assistant plugins diff example --json`,
    },
    {
      name: "search",
      args: "<query>",
      description:
        "Search the plugin marketplace. Query is a case-insensitive regex against plugin names",
      options: [
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of a table",
        },
      ],
      helpText: `
When to use:
  First stop when the user asks to set up, install, connect, or integrate a
  product, service, or app (for example "Setup <app> for me",
  "connect this service"). Search here before searching the web.

Arguments:
  query    Case-insensitive regex matched against plugin names, not the full
           user sentence. Use the product or plugin name. Anchors like
           ^example work.

If a match is found, install it with 'assistant plugins install <name>'.
If nothing matches, try 'assistant skills search <query>', then web search.

Examples:
  $ assistant plugins search example
  $ assistant plugins search "^example"
  $ assistant plugins search example --json`,
    },
    {
      name: "publish",
      description:
        "Validate and submit the plugin in the current directory to the Vellum marketplace catalog",
      options: [
        {
          flags: "--print",
          description:
            "Print the entry JSON without submitting to the platform",
        },
        {
          flags: "--path <dir>",
          description: "Validate a plugin at the given path instead of CWD",
        },
        { flags: "--force", description: "Skip the confirmation prompt" },
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of human output",
        },
        {
          flags: "--category <cat>",
          description: "Set the category, skipping the interactive prompt",
        },
      ],
      helpText: `

Validates the plugin in the current directory (or --path), resolves the
git commit SHA and GitHub remote, and submits the entry to the Vellum
platform API. The platform creates a pull request against
vellum-ai/vellum-assistant adding the plugin to the marketplace catalog.

Requires a connected Vellum platform account (run \`assistant platform connect\`).
Use --print to validate and print the entry without submitting.

Examples:
$ assistant plugins publish
$ assistant plugins publish --print
$ assistant plugins publish --path ./my-plugin --category productivity
$ assistant plugins publish --json`,
    },
    {
      name: "uninstall",
      args: "<name>",
      description: "Remove a plugin from <workspaceDir>/plugins/<name>/",
      options: [
        { flags: "--force", description: "Skip the confirmation prompt" },
      ],
    },
    {
      name: "disable",
      args: "<name>",
      description:
        "Disable a plugin by creating a .disabled sentinel file. Works for both user-installed and default plugins. Takes effect immediately in a running assistant.",
    },
    {
      name: "enable",
      args: "<name>",
      description:
        "Re-enable a disabled plugin by removing the .disabled sentinel file. Takes effect immediately.",
    },
    {
      name: "upgrade",
      args: "<name>",
      description:
        "Upgrade an installed plugin to its source's current revision (the marketplace pin, or — for a GitHub-URL install — whatever its recorded branch/tag/ref now resolves to)",
      options: [
        {
          flags: "--dry-run",
          description: "Show what would change without modifying the install",
        },
        {
          flags: "--strategy <strategy>",
          description: `How to reconcile local edits with the target: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")} (default: ${DEFAULT_PLUGIN_UPGRADE_STRATEGY})`,
        },
        {
          flags: "--json",
          description: "Emit machine-readable JSON instead of a summary",
        },
        {
          flags: "--force",
          description:
            "Skip the declared-schedules confirmation prompt of a local upgrade (the assistant-applied path never prompts)",
        },
      ],
      helpText: `
A marketplace plugin upgrades to the curated pin. A plugin installed directly
from a GitHub URL (untrusted) upgrades against its recorded source: it re-fetches
whatever its recorded ref resolves to now — a pinned commit SHA is immutable (a
no-op), while a branch/tag/HEAD advances as upstream does — and re-materializes
it verbatim, with no curated adapter overlay.

With the assistant running, the upgrade is applied by it immediately, with no
confirmation prompt: a schedule the new revision declares is armed by the
assistant and surfaced as a notification, and the upgrade output lists the
revision's declared schedules with any new ones marked. Only when the
assistant is unreachable does the upgrade run locally instead; that path
stages the new revision first, and a revision that declares schedules lists
them and asks for confirmation before going live (--force skips that prompt,
as for install).

Examples:
  $ assistant plugins upgrade example
  $ assistant plugins upgrade example --dry-run
  $ assistant plugins upgrade example --strategy ours`,
    },
  ],
};