export interface BulbServer {
  /** OS process id of the dev server. */
  pid: number
  /** Bound loopback port. */
  port: number
  /** http://localhost:<port>. */
  url: string
  /** Absolute path to the .bulb.md being served. */
  file: string
  /** The cwd the server was launched in (the project it belongs to). */
  cwd?: string
  /** Epoch ms the server began listening. */
  startedAt: number
  /** Launched with --trust (filesystem / AI / server.ts enabled)? */
  trust?: boolean
  /** Human label of a capability the proactive scan predicts this untrusted bulb will need
   *  (set at register time; probabilistic, not enforcement). */
  predicted?: string
  /** Human label of a privileged capability this untrusted server denied (set by the gate). */
  denied?: string
}

/** Launch (or re-attach to) a standalone `typebulb` dev server for `file`. Idempotent
 *  per file: a live server already serving it is returned, not re-spawned. Always silent
 *  (no console window); detached so it outlives the caller. `trust` passes --trust. */
export declare function launchBulbServer(file: string, opts?: { cwd?: string; open?: boolean; trust?: boolean }): Promise<BulbServer>

/** Every live dev server, oldest first. Dead entries are pruned on read. Pass `cwd` to scope the
 *  list to that project's bulbs (the machine-global default is for explicit pid/file targeting). */
export declare function listBulbServers(cwd?: string): Promise<BulbServer[]>

/** Stop a server by pid (SIGTERM + deregister). Idempotent. */
export declare function stopBulbServer(pid: number): Promise<void>

/** New console bytes of a server (its `<pid>.log`) since `offset`; returns the text and
 *  the new offset. A trim past the cap resyncs from 0. Absent file ⇒ empty. */
export declare function readServerLog(pid: number, offset?: number): { text: string; offset: number }

/** Absolute path of a server's console log, sibling of its registry entry. */
export declare function serverLogPath(pid: number): string

export interface BulbFileInfo {
  /** Absolute path to the .bulb.md. */
  path: string
  /** The bulb's `name:` frontmatter title, or the filename stem when unnamed. */
  name: string
  /** File mtime (epoch ms); 0 if it vanished mid-walk. */
  mtime: number
}

/** Every `*.bulb.md` under `cwd` (dot-dirs and node_modules skipped, depth-bounded),
 *  each with its frontmatter name (or filename stem) and mtime. */
export declare function listBulbFiles(cwd: string): BulbFileInfo[]

/** Scan a `.bulb.md` and return the privileged capability it probably needs (or undefined),
 *  so a host can offer --trust before launching. Probabilistic hint, never enforcement. */
export declare function predictBulbTrust(file: string): Promise<string | undefined>

/** The bulb's `name:` from its leading frontmatter, or undefined if absent. */
export declare function bulbName(source: string): string | undefined

/** A filesystem-safe slug from the bulb's name; 'bulb' when unnamed. */
export declare function slugifyBulbName(source: string): string

/** The source with its leading `---` frontmatter block stripped. */
export declare function stripFrontmatter(source: string): string

/** Return `source` with every bare client import in code.tsx guaranteed a config.json `dependencies`
 *  entry (deriving the missing ones as "latest" — the version the import-driven resolver already uses
 *  for an undeclared import). Idempotent: a fully-declared / non-bulb / import-less source is returned
 *  unchanged. Used by breakout to make a promoted embed a correct, runnable .bulb.md. */
export declare function ensureDeclaredDependencies(source: string): string

/** Is this bulb remembered as Trusted in the CLI's per-machine trust store? */
export declare function isBulbTrusted(file: string): boolean

/** Set or clear a bulb's remembered trust (written only by user/agent action, never bulb code). */
export declare function setBulbTrusted(file: string, trust: boolean): void

/** Every remembered-trusted bulb path (absolute, normalized). */
export declare function listTrustedBulbs(): string[]

/** Open `filePath` (optionally at `line`) in the user's editor, detached. Defaults to VS Code
 *  (`code`); override with `TYPEBULB_EDITOR`. Fire-and-forget. */
export declare function openInEditor(filePath: string, line?: number): void