The plugin API

import type { Ovvi } from "@ovvi/plugin-api"

export default async function main(ovvi: Ovvi) {
  const { text } = await ovvi.files.read(ovvi.card.arg)
  document.body.textContent = text
}

export interface Ovvi {
  /** The API version the app gives this page: the manifest's `api`. */
  readonly api: number
  readonly card: Card
  readonly files: Files
  readonly git: Git
  readonly state: State
  readonly controls: Controls
  readonly theme: Theme
  readonly pages: Pages
  readonly settings: Settings
  readonly clipboard: { write(text: string): Promise<void> }
  /** The native context menu at the pointer. Resolves with the picked item's value, or undefined. */
  readonly menu: { show(items: MenuItem[]): Promise<string | undefined> }
  /** Choose Folder…: the Mac's folder panel, a folder field on a remote machine. Resolves with the folder's path, or
   *  undefined. */
  readonly pick: { folder(from?: string): Promise<string | undefined> }

  /** Runs argv on the card's machine, in the pane's folder unless `cwd` says otherwise: no shell, 30 s unless
   *  `timeout` (ms) says otherwise, 4 MiB of stdout, two at a time per card. */
  run(argv: string[], options?: { cwd?: string; stdin?: string; timeout?: number }): Promise<RunResult>
  /** An open of a file, a folder (ends in `/`), a URL or a plugin's argument: in this card, in a new tab right after
   *  this card's tab (the default), in a pane to its side, or (`mac`, a ⌘⌥-click) in the Mac's default app for it,
   *  outside Ovvi (a remote machine's file or folder shows a notice). No `plugin`: the file's default plugin, the
   *  browser for a web address. `at`: the new card's landing (`card.at`). */
  open(arg: string, options?: {
    plugin?: string
    how?: "card" | "tab" | "side" | "mac"
    at?: string
    /** A new tab or pane opens behind: the selected tab and the keyboard stay where they are (a ⌘- or
     *  ⌥-click). */
    background?: boolean
  }): Promise<void>
  /** One line on glass at the top of the card, with `buttons` (the second the default) or OK. Resolves with the title
   *  picked, or undefined when another toast took its place. `destructive`: the main button deletes or discards (a
   *  Revert, a Delete), drawn red. */
  toast(text: string, buttons?: [other: string, main: string], options?: { destructive?: boolean }): Promise<string | undefined>
  /** An SF Symbol, or the app's `source.branch` or `text.wrap`, as a PNG data URL, `size` points tall (16 by default),
   *  black on clear: use it as a mask. */
  symbol(name: string, size?: number): Promise<string>

  /** A header control or a command, as the user changed it: a click (no value), a toggle, a segment, a menu item, a
   *  field's text (`submit` on Return), a path text's linked part (`part`, its index). */
  on(event: "control", fn: (e: { id: string; value?: string | boolean; submit?: boolean; part?: number }) => void): Off
  /** The card moved to another place: after `card.go`, Back, Forward, or a rename from elsewhere. After Back, `at`
   *  is the place it came back from: that place's landing, else its argument. */
  on(event: "place", fn: (place: { arg: string; at?: string }) => void): Off
  /** ⌘S, ⌘F, ⌘G, ⇧⌘G over the card, with `handles` in the manifest. */
  on(event: "save" | "find" | "findNext" | "findPrevious", fn: () => void): Off
  on(event: "visible" | "keyboard", fn: (yes: boolean) => void): Off
  on(event: "theme", fn: (theme: Theme) => void): Off
  /** The user changed settings of this plugin on its page in Settings: the new values by id. Every open card
   *  of the plugin hears it, hidden ones too. */
  on(event: "settings", fn: (changed: Record<string, SettingValue>) => void): Off
}

/** A toggle's value is a boolean, a number's a number, a choice's, a text's and a path's a string. */
export type SettingValue = boolean | number | string

/** The values of the manifest's `settings`, which the user sets on the plugin's page in Settings. Read only:
 *  a card keeps its own choices in `state`. */
export interface Settings {
  /** The value the user set, else the manifest's default. There at the page's first load, with no wait. */
  get<T extends SettingValue>(id: string): T
  /** Opens Settings at this plugin's page. */
  open(): void
}

/** Stops the handler or the watch. Every one ends with the page. */
export type Off = () => void

/** A card of many places draws each in a page of its own, and keeps the last five pages it showed, hidden,
 *  so Back and Forward show a place at once, as the user left it: its scroll, its open rows, its header controls. */
export interface Pages {
  /** Draws the card's places from this call on, starting with its current place: resolves once that page shows. A
   *  move to a place with a kept page shows that page at once; to another place, `draw` fills a new page, which shows
   *  when its promise ends, and the shown page stays until then. A page left with unsaved edits is dropped. From this
   *  call on ⌘← and ⌘→ go Back and Forward (manifest `history`), ahead of the page's own keys, unless a text field has
   *  the keyboard. */
  route(draw: (page: Page) => Promise<void>): Promise<void>
}

export interface Page {
  readonly arg: string
  /** The landing of the move that drew it. */
  readonly at?: string
  /** Over the whole card (`.ovvi-page`); hidden pages are `inert`. */
  readonly element: HTMLElement
  /** The page's own `ovvi`: its `on` handlers run only while it shows (`theme`, `visible` and `settings` always), its
   *  watches call back while it shows (a change while hidden calls once when it shows again), its header controls apply
   *  while it shows and come back when it shows again; all end when it drops. Its `place` fires when the card moves to
   *  this page again (Back, Forward, the same place with a landing). */
  readonly ovvi: Ovvi
  readonly shown: boolean
  /** Gone: work that ends after does nothing. */
  readonly dropped: boolean
  /** Runs when the page drops: a view's teardown. */
  keep(off: Off): void
  /** Draws the place again in a new page, which takes this one's place once drawn; a hidden page only drops. */
  redraw(): void
}

export interface Card {
  /** The instance id from the label: stable for the pane's life. */
  readonly id: string
  readonly plugin: { id: string; version: string }
  readonly machine: { id: string; name: string; remote: boolean }
  /** The place: the label's argument (a path, a root, "<root> <source>", a URL, or ""). */
  readonly arg: string
  /** The pane's folder on its machine. */
  readonly cwd: string
  /** A linked open's landing, on the first load only: a 1-based line, or a file of a diff. */
  readonly at?: string
  readonly visible: boolean
  readonly keyboard: boolean
  /** Moves the card to another place: the label follows, the app keeps Back and Forward. With unsaved edits the app
   *  asks first. The page hears `place` once it moved; it is not loaded again. */
  go(arg: string, options?: { at?: string }): void
  /** Ends the card's loader. Also when `main` returns. */
  ready(): void
  /** The Edited dot after the title. A dirty card is never dropped; a move or a close asks Discard or Keep Editing. */
  setDirty(dirty: boolean): void
}

export interface Files {
  /** UTF-8 text up to 16 MiB. `hash` is what `write` checks. `writable` is false over 4 MiB on a remote machine. */
  read(path: string): Promise<{ text: string; hash: string; writable: boolean }>
  /** Bytes up to 16 MiB, with the MIME type from the name. */
  readBytes(path: string): Promise<{ data: Uint8Array; type: string; hash: string }>
  /** The info view's facts: the size in bytes, the kind's name, the system's icon as a PNG data URL; and the hash
   *  `read` gives (none for a folder), to tell a change without reading the file. */
  info(path: string): Promise<{ name: string; size: number; kind: string; icon: string; folder: boolean; hash: string }>
  /** A folder's entries but `.git`, folders first, by name as the Finder sorts; `ignored` when git ignores it. */
  list(folder: string): Promise<{ name: string; folder: boolean; ignored: boolean }[]>
  /** Every file under the root, from it: the files git does not ignore in a repository, else every file, up to 8 MiB
   *  of names. */
  paths(root: string): Promise<string[]>
  /** Writes a new file beside the path and moves it over. With `over`, fails with `changed` if the file's hash
   *  differs. */
  write(path: string, data: string | Uint8Array, options?: { over?: string }): Promise<{ hash: string }>
  /** Renames or moves a file or a folder; never replaces: fails when something is at `to`. */
  move(path: string, to: string): Promise<void>
  /** Calls fn after a change under path, only while the card shows, and once on showing again. Under a folder, what
   *  git ignores (a build's output) and git's objects call nothing, and calls come at most every 2 s. */
  watch(path: string, fn: () => void): Off
}

/** Writes run one at a time per card, and never ask for a password (they fail with git's message). */
export interface Git {
  root(folder: string): Promise<string | null>
  /** The changed files from the root, each untracked file on its own: the index's letter for a file it adds or
   *  renames, else the work tree's, else the index's. */
  status(root: string): Promise<Change[]>
  /** The changes as the index keeps them: staged (the index against HEAD) and unstaged (untracked included); with
   *  `status`'s list and `head`'s answer plus the commit HEAD names ("" before the first), all from one `git status`. */
  changes(root: string): Promise<{
    staged: Change[]
    unstaged: Change[]
    status: Change[]
    head: { branch: string; ahead: number; behind: number; commit: string } | null
  }>
  /** The checkout's branch (the short hash when detached) and how far it is from its upstream; null outside a
   *  repository. */
  head(root: string): Promise<{ branch: string; ahead: number; behind: number } | null>
  /** The local branches, then the remote ones with no local branch of their name. */
  branches(root: string): Promise<{ name: string; remote: boolean; current: boolean }[]>
  /** The last `limit` commits (500 by default) of every branch, remote branch and tag, and HEAD, newest first, with the
   *  graph's lanes. */
  log(root: string, options?: { limit?: number }): Promise<Commit[]>
  /** The patch as git prints it: "uncommitted" (staged, unstaged and untracked against HEAD) or a commit against its
   *  first parent. Up to 16 MiB. */
  diff(root: string, source: string): Promise<string>
  /** A commit's page, by its hex hash (not a ref name): its subject (git's `%s`, as `log` gives it) and body (`%b`, trimmed), author, email, date in
   *  milliseconds since 1970, and the full hashes of its parents. */
  show(root: string, hash: string): Promise<{
    hash: string; parents: string[]; author: string; email: string; date: number; subject: string; body: string
  }>
  /** `git add -A` of the paths (literal, not patterns), or of everything. */
  stage(root: string, paths?: string[]): Promise<void>
  unstage(root: string, paths?: string[]): Promise<void>
  /** The paths (literal) back as HEAD has them, in the index and the work tree; untracked ones are deleted. With a
   *  tracked path it fails in a repository with no commits. */
  revert(root: string, paths: string[]): Promise<void>
  commit(root: string, message: string): Promise<void>
  fetch(root: string): Promise<void>
  /** git's own way (the user's `pull.rebase`). */
  pull(root: string): Promise<void>
  /** A branch with no upstream is published under its name. */
  push(root: string): Promise<void>
  /** A remote branch (`origin/x`) makes a local one that tracks it. */
  switch(root: string, branch: string): Promise<void>
  init(folder: string): Promise<void>
  /** Calls fn after a change of git's own files of the root: its `HEAD`, the repository's refs and its config (a
   *  commit, a checkout, a fetch, a new branch or tag, an upstream), as the sidebar's branch follows them. Only while
   *  the card shows, and once on showing again. */
  watch(root: string, fn: () => void): Off
}

export interface Change {
  /** M, T (the type changed), A, D, R, C (a conflict), U (untracked). */
  letter: string
  path: string
  oldPath?: string
}

export interface Commit {
  hash: string
  subject: string
  author: string
  /** As git's `%D` with `--decorate=full`: `HEAD -> refs/heads/main`, `refs/remotes/origin/main`, `tag: refs/tags/v1`. */
  refs: string[]
  /** Milliseconds since 1970. */
  date: number
  lane: number
  children: number[]
  parents: number[]
  through: number[]
}

export interface RunResult {
  code: number
  stdout: string
  /** The last 8 KiB. */
  stderr: string
  /** stdout passed 4 MiB: the command stops there. */
  truncated: boolean
}

export interface State {
  /** The card's state as last set: given at load, also after a drop, a reload or a relaunch. */
  get<T>(): T | undefined
  /** JSON, at most 256 KiB. Kept at once in the app; written to the card's machine 500 ms after the last set. */
  set<T>(value: T): void
}

export interface Controls {
  get(id: string): string | boolean | string[] | undefined
  /** Changes a header control or a command. `badge` "" or 0 clears; `busy` shows a spinner in a button or a menu and
   *  disables the control. A field's value changes as the user types: set it only to replace or clear it (after
   *  submit), never to echo it. */
  set(id: string, change: {
    value?: string | boolean | string[]
    title?: string
    /** An SF Symbol: a button's or a toggle's icon, or drawn ahead of a text's last part; "" clears. */
    symbol?: string
    /** What VoiceOver reads, when not the title ("Push, 1 ahead"); "" clears. */
    label?: string
    badge?: string | number
    /** A path text: its first parts are buttons, which send `control` with their `part`. */
    links?: number
    items?: MenuItem[]
    hidden?: boolean
    enabled?: boolean
    checked?: boolean
    busy?: boolean
    /** A plain field (not a path field) takes the keyboard (the page's ⌘F). */
    focus?: boolean
    /** A path field shakes and keeps the typed path: it names no place to go. */
    refused?: boolean
  }): void
}

/** An item, a section heading (no value) or a divider. */
export type MenuItem = { value: string; title: string; symbol?: string } | { title: string } | "-"

export interface Theme {
  dark: boolean
  style: "glass" | "classic"
  /** The app's text size in points (⌘+ ⌘− ⌘0). */
  textSize: number
  /** The app's tokens as CSS colors; also CSS variables on the root (`--text`, …), with `--app-text-size`. The app
   *  sets the root's inline style anew with each theme: put the page's own variables in a style sheet. `card` is an
   *  opaque stand-in for the card's fill (the keyboard card's while it is one: `theme` fires as the card gains or
   *  loses the keyboard), for a band that text scrolls under. */
  colors: Record<
    "text" | "dim" | "divider" | "card" | "accent" | "on-accent" | "working" | "needs-you" | "finished" | "error",
    string
  >
}

/** What every failed call rejects with. */
export interface OvviError extends Error {
  code: "notFound" | "notText" | "tooLarge" | "changed" | "timeout" | "closed" | "failed"
}

{ "controls": { "diff.layout": "split" }, "state": { "draft": "Fix the login", "list": false } }