@hudhod/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hudhod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @hudhod/sdk
+
+The public API surface for building [hudhod](../../README.md) extensions.
+
+hudhod is an in-browser IDE built on WebContainers. This package describes what
+an extension can do. It is **types-first**: the only values it ships are
+`defineExtension()` and `isHudhodError()`, so importing it adds essentially
+nothing to your bundle.
+
+The same API backs the AI agent tool layer, so anything an extension can do, an
+agent can do.
+
+## Install
+
+```bash
+pnpm add @hudhod/sdk
+```
+
+## Quickstart
+
+```ts
+import { defineExtension } from "@hudhod/sdk";
+
+export default defineExtension({
+  manifest: {
+    id: "acme.todo-finder",
+    name: "TODO Finder",
+    version: "1.0.0",
+    activationEvents: ["onCommand:acme.todoFinder.scan"],
+    contributes: {
+      commands: [{ id: "acme.todoFinder.scan", title: "Scan for TODOs" }],
+    },
+  },
+  async activate({ hudhod, subscriptions }) {
+    subscriptions.push(
+      hudhod.commands.registerCommand("acme.todoFinder.scan", async () => {
+        const { matches } = await hudhod.search.findInFiles("TODO", {
+          include: ["**/*.ts", "**/*.tsx"],
+        });
+        await hudhod.window.showMessage(`Found ${matches.length} TODOs`);
+      }),
+    );
+  },
+});
+```
+
+## Design rules
+
+Three constraints shape every signature in this package:
+
+1. **Everything is async.** Even operations that could be synchronous today
+   return a promise, so the host can later move extensions into a worker or
+   sandboxed frame without a breaking change.
+2. **Everything is structured-cloneable.** No classes, no functions, and no live
+   objects cross the API boundary — with the single deliberate exception of
+   `ProcessHandle`, which carries streams and is therefore same-context only.
+   Use `ProcessInfo` when you need a serialisable snapshot.
+3. **Paths are absolute and POSIX-style**, rooted at the workspace root (`/`).
+   Relative paths are rejected rather than resolved against ambient state.
+
+## API
+
+The root object is `HudhodApi`, delivered as `context.hudhod` on activation.
+
+| Namespace   | Purpose                                         |
+| ----------- | ----------------------------------------------- |
+| `fs`        | Read and write files                            |
+| `workspace` | Workspace edits, edit history, revert           |
+| `search`    | Find files by glob, search and replace in files |
+| `diff`      | Compare text, create and apply unified patches  |
+| `process`   | Spawn processes, run one-shot commands          |
+| `terminal`  | Create and drive interactive shells             |
+| `commands`  | Register and invoke commands                    |
+| `window`    | Notifications, prompts, contributed panels      |
+
+### `hudhod.fs`
+
+| Method                                   | Returns                     |
+| ---------------------------------------- | --------------------------- |
+| `readFile(path)`                         | `Promise<Uint8Array>`       |
+| `readTextFile(path)`                     | `Promise<string>`           |
+| `writeFile(path, data, options?)`        | `Promise<void>`             |
+| `writeTextFile(path, content, options?)` | `Promise<void>`             |
+| `createFile(path, options?)`             | `Promise<void>`             |
+| `createDirectory(path)`                  | `Promise<void>`             |
+| `delete(path, options?)`                 | `Promise<void>`             |
+| `rename(from, to, options?)`             | `Promise<void>`             |
+| `copy(from, to, options?)`               | `Promise<void>`             |
+| `stat(path)`                             | `Promise<FileStat>`         |
+| `exists(path)`                           | `Promise<boolean>`          |
+| `readDirectory(path)`                    | `Promise<DirectoryEntry[]>` |
+| `watch(path, listener, options?)`        | `Disposable`                |
+| `onDidChangeFile`                        | `Event<FileChangeEvent[]>`  |
+
+Writes create missing parent directories by default. Change events are debounced
+and delivered in batches.
+
+### `hudhod.process`
+
+| Method                            | Returns                  |
+| --------------------------------- | ------------------------ |
+| `spawn(command, args?, options?)` | `Promise<ProcessHandle>` |
+| `exec(command, args?, options?)`  | `Promise<ExecResult>`    |
+| `list()`                          | `Promise<ProcessInfo[]>` |
+| `kill(id)`                        | `Promise<boolean>`       |
+| `onDidStartProcess`               | `Event<ProcessInfo>`     |
+| `onDidExitProcess`                | `Event<ProcessInfo>`     |
+
+`exec()` is guarded so a runaway command cannot hang the browser tab:
+
+| Option           | Default   | Disable with |
+| ---------------- | --------- | ------------ |
+| `timeout`        | 60 000 ms | `false`      |
+| `maxOutputBytes` | 1 MiB     | `false`      |
+
+Breaching either guard kills the process and throws, and the thrown error
+carries the output collected so far on `partialOutput`.
+
+> **stdout and stderr are merged.** The WebContainer runtime exposes a single
+> output stream per process, so `ExecResult` has one `output` field rather than
+> an `stderr` that would always be empty.
+
+### `hudhod.workspace`
+
+Agent edits go through `applyEdit()`, which supports two modes:
+
+```ts
+// Apply now; revertable via the edit history, and undoable in the editor.
+await hudhod.workspace.applyEdit(edits, { mode: "immediate", label: "Fix types" });
+
+// Show the user a diff and wait. Nothing is written unless they accept.
+const { applied } = await hudhod.workspace.applyEdit(edits, { mode: "review" });
+```
+
+Edits within a file are applied bottom-up so earlier ranges stay valid, and the
+whole set is atomic — if one file fails, none are written.
+
+### `hudhod.commands`
+
+```ts
+const sub = hudhod.commands.registerCommand("demo.run", handler, {
+  title: "Run Demo",
+  category: "Demo",
+});
+```
+
+Commands without a `title` are callable but stay hidden from the palette.
+
+### `hudhod.window`
+
+```ts
+hudhod.window.registerPanel(
+  "demo.stats",
+  (container) => {
+    container.textContent = "Hello";
+    return () => {
+      /* cleanup on close */
+    };
+  },
+  { title: "Stats", location: "right" },
+);
+```
+
+## Error handling
+
+Match on `code`, never on message text:
+
+```ts
+import { isHudhodError } from "@hudhod/sdk";
+
+try {
+  await hudhod.fs.readTextFile("/missing.ts");
+} catch (error) {
+  if (isHudhodError(error) && error.code === "FileNotFound") {
+    // handle it
+  }
+}
+```
+
+Codes: `FileNotFound`, `FileExists`, `NotADirectory`, `NotAFile`,
+`DirectoryNotEmpty`, `InvalidPath`, `CommandNotFound`, `CommandExists`,
+`ProcessTimeout`, `OutputLimitExceeded`, `PatchFailed`, `Cancelled`.
+
+## Activation events
+
+Prefer lazy activation; every `onStartup` extension delays workbench boot.
+
+| Event               | Fires when                    |
+| ------------------- | ----------------------------- |
+| `onStartup`         | The workbench is ready        |
+| `onCommand:<id>`    | A command is first invoked    |
+| `onFileOpen:<glob>` | A matching file is opened     |
+| `onView:<panelId>`  | A contributed panel is opened |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,1044 @@
+//#region src/lifecycle.d.ts
+/**
+ * Core lifecycle primitives shared by every hudhod API namespace.
+ *
+ * These are declared as *contracts* only — the runtime implementations live in
+ * `@hudhod/core`. Keeping them here means extension authors never need to depend
+ * on the host runtime just to type a subscription.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A resource that must be released when it is no longer needed.
+ *
+ * Every subscription and registration in the hudhod API returns a `Disposable`.
+ * Push them onto {@link ExtensionContext.subscriptions} and the host will clean
+ * them up automatically when your extension is deactivated.
+ *
+ * @example
+ * ```ts
+ * const sub = hudhod.fs.watch("/src", () => console.log("changed"));
+ * context.subscriptions.push(sub);
+ * ```
+ */
+interface Disposable {
+  /** Releases the underlying resource. Calling this more than once is a no-op. */
+  dispose(): void;
+}
+/**
+ * A function that registers a listener and returns a {@link Disposable} to
+ * unregister it.
+ *
+ * @typeParam T - The payload delivered to listeners.
+ *
+ * @example
+ * ```ts
+ * const sub = hudhod.process.onDidExitProcess((info) => {
+ *   console.log(`${info.command} exited with ${info.exitCode}`);
+ * });
+ * ```
+ */
+type Event<T> = (listener: (event: T) => unknown) => Disposable;
+/**
+ * Signals that a long-running operation should be abandoned.
+ *
+ * Search and other potentially expensive operations accept one so callers can
+ * bail out early.
+ */
+interface CancellationToken {
+  /** Whether cancellation has already been requested. */
+  readonly isCancellationRequested: boolean;
+  /** Fires once, when cancellation is first requested. */
+  readonly onCancellationRequested: Event<void>;
+}
+//#endregion
+//#region src/commands.d.ts
+/** A command that has been registered with the host. */
+interface CommandDescriptor {
+  /** Unique identifier, conventionally `namespace.verbNoun`. */
+  readonly id: string;
+  /** Label shown in the command palette. */
+  readonly title: string;
+  /** Optional grouping shown alongside the title. */
+  readonly category?: string;
+  /** Identifier of the extension that contributed the command. */
+  readonly extensionId?: string;
+}
+/** Options for {@link CommandsApi.registerCommand}. */
+interface RegisterCommandOptions {
+  /**
+   * Label shown in the command palette. Commands without a title are callable
+   * but stay hidden from the palette.
+   */
+  readonly title?: string;
+  /** Optional grouping shown alongside the title. */
+  readonly category?: string;
+}
+/**
+ * Register and invoke commands.
+ *
+ * Commands are the seam between UI affordances and behaviour: anything the
+ * palette, a menu, or an agent can trigger is a command.
+ *
+ * @example
+ * ```ts
+ * context.subscriptions.push(
+ *   hudhod.commands.registerCommand(
+ *     "demo.formatAll",
+ *     async () => { await hudhod.process.exec("npm", ["run", "fmt"]); },
+ *     { title: "Format All Files", category: "Demo" },
+ *   ),
+ * );
+ * ```
+ */
+interface CommandsApi {
+  /**
+   * Registers a command handler.
+   * @throws When `id` is already registered.
+   * @returns A {@link Disposable} that unregisters the command.
+   */
+  registerCommand(id: string, handler: (...args: readonly unknown[]) => unknown, options?: RegisterCommandOptions): Disposable;
+  /**
+   * Invokes a registered command.
+   * @throws A `CommandNotFound` error when `id` is not registered.
+   */
+  executeCommand<T = unknown>(id: string, ...args: readonly unknown[]): Promise<T>;
+  /** Lists every registered command. */
+  getCommands(): Promise<CommandDescriptor[]>;
+}
+//#endregion
+//#region src/diff.d.ts
+/**
+ * Diff and patch API types.
+ *
+ * @packageDocumentation
+ */
+/** How two pieces of text differ, as a sequence of ordered hunks. */
+interface DiffChange {
+  /** Whether this run of lines was added, removed, or left untouched. */
+  readonly type: "added" | "removed" | "unchanged";
+  /** The lines covered by this hunk, without trailing newlines. */
+  readonly lines: readonly string[];
+}
+/** Options controlling how text is compared. */
+interface DiffOptions {
+  /**
+   * Ignore differences that consist only of whitespace.
+   * @defaultValue false
+   */
+  readonly ignoreWhitespace?: boolean;
+  /**
+   * Ignore differences in letter casing.
+   * @defaultValue false
+   */
+  readonly ignoreCase?: boolean;
+  /**
+   * Lines of unchanged context to keep around each hunk in a unified patch.
+   * @defaultValue 3
+   */
+  readonly context?: number;
+}
+/** Aggregate statistics for a diff. */
+interface DiffStat {
+  /** Number of added lines. */
+  readonly added: number;
+  /** Number of removed lines. */
+  readonly removed: number;
+}
+/**
+ * Compare text and files, and apply unified patches.
+ *
+ * @example
+ * ```ts
+ * const patch = await hudhod.diff.createPatch("/src/a.ts", oldText, newText);
+ * await hudhod.diff.applyPatch("/src/a.ts", patch);
+ * ```
+ */
+interface DiffApi {
+  /** Compares two strings line by line. */
+  diffText(original: string, modified: string, options?: DiffOptions): Promise<DiffChange[]>;
+  /** Reads both paths and compares their contents. */
+  diffFiles(originalPath: string, modifiedPath: string, options?: DiffOptions): Promise<DiffChange[]>;
+  /** Summarises how many lines a change adds and removes. */
+  diffStat(original: string, modified: string, options?: DiffOptions): Promise<DiffStat>;
+  /** Produces a unified diff, using `path` for the file headers. */
+  createPatch(path: string, original: string, modified: string, options?: DiffOptions): Promise<string>;
+  /**
+   * Applies a unified diff to a file on disk.
+   * @throws A `PatchFailed` error when the patch does not apply cleanly.
+   */
+  applyPatch(path: string, patch: string): Promise<void>;
+}
+//#endregion
+//#region src/fs.d.ts
+/** The kind of entry a path points at. */
+type FileType = "file" | "directory" | "symlink";
+/** Metadata describing a single file system entry. */
+interface FileStat {
+  /** Whether the entry is a file, directory, or symlink. */
+  readonly type: FileType;
+  /** Size in bytes. Always `0` for directories. */
+  readonly size: number;
+  /** Last-modified time, in milliseconds since the Unix epoch. */
+  readonly mtime: number;
+}
+/** A single child returned by {@link FileSystemApi.readDirectory}. */
+interface DirectoryEntry {
+  /** Entry name, without any leading directory component. */
+  readonly name: string;
+  /** Absolute path to the entry. */
+  readonly path: string;
+  /** Whether the entry is a file, directory, or symlink. */
+  readonly type: FileType;
+}
+/** How a watched path changed. */
+type FileChangeType = "created" | "changed" | "deleted";
+/** A single file system change notification. */
+interface FileChangeEvent {
+  /** What happened to the path. */
+  readonly type: FileChangeType;
+  /** Absolute path that changed. */
+  readonly path: string;
+}
+/** Options for {@link FileSystemApi.writeFile} and {@link FileSystemApi.writeTextFile}. */
+interface WriteFileOptions {
+  /**
+   * Create the file when it does not exist.
+   * @defaultValue true
+   */
+  readonly create?: boolean;
+  /**
+   * Overwrite the file when it already exists. When `false` and the file
+   * exists, a `FileExists` error is thrown.
+   * @defaultValue true
+   */
+  readonly overwrite?: boolean;
+  /**
+   * Create missing parent directories.
+   * @defaultValue true
+   */
+  readonly createParents?: boolean;
+}
+/** Options for {@link FileSystemApi.delete}. */
+interface DeleteOptions {
+  /**
+   * Recursively delete directory contents. Deleting a non-empty directory
+   * without this flag throws.
+   * @defaultValue false
+   */
+  readonly recursive?: boolean;
+}
+/** Options for {@link FileSystemApi.rename} and {@link FileSystemApi.copy}. */
+interface MoveOptions {
+  /**
+   * Replace the destination when it already exists.
+   * @defaultValue false
+   */
+  readonly overwrite?: boolean;
+}
+/** Options for {@link FileSystemApi.watch}. */
+interface WatchOptions {
+  /**
+   * Watch nested directories as well.
+   * @defaultValue true
+   */
+  readonly recursive?: boolean;
+  /**
+   * Glob patterns to ignore. Defaults to the workspace `files.watcherExclude`
+   * setting (`node_modules`, `.git`, `dist`, …).
+   */
+  readonly excludes?: readonly string[];
+}
+/**
+ * Read and write the workspace file system.
+ *
+ * Every method is asynchronous and accepts/returns only structured-cloneable
+ * values, so the whole namespace remains usable across a worker boundary.
+ *
+ * @example
+ * ```ts
+ * await hudhod.fs.writeTextFile("/src/greet.ts", "export const hi = () => 'hi';");
+ * const source = await hudhod.fs.readTextFile("/src/greet.ts");
+ * ```
+ */
+interface FileSystemApi {
+  /**
+   * Reads a file as raw bytes.
+   * @throws A `FileNotFound` error when `path` does not exist.
+   * @throws A `NotAFile` error when `path` is a directory.
+   */
+  readFile(path: string): Promise<Uint8Array>;
+  /**
+   * Reads a file and decodes it as UTF-8 text.
+   * @throws A `FileNotFound` error when `path` does not exist.
+   */
+  readTextFile(path: string): Promise<string>;
+  /** Writes raw bytes, creating parent directories by default. */
+  writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+  /** Writes UTF-8 text, creating parent directories by default. */
+  writeTextFile(path: string, content: string, options?: WriteFileOptions): Promise<void>;
+  /**
+   * Creates an empty file.
+   * @throws A `FileExists` error when the file exists and `overwrite` is not set.
+   */
+  createFile(path: string, options?: WriteFileOptions): Promise<void>;
+  /** Creates a directory, including any missing parents. Succeeds if it already exists. */
+  createDirectory(path: string): Promise<void>;
+  /**
+   * Deletes a file or directory.
+   * @throws A `FileNotFound` error when `path` does not exist.
+   */
+  delete(path: string, options?: DeleteOptions): Promise<void>;
+  /** Moves or renames an entry. */
+  rename(from: string, to: string, options?: MoveOptions): Promise<void>;
+  /** Copies a file or directory tree. */
+  copy(from: string, to: string, options?: MoveOptions): Promise<void>;
+  /**
+   * Retrieves metadata for a path.
+   * @throws A `FileNotFound` error when `path` does not exist.
+   */
+  stat(path: string): Promise<FileStat>;
+  /** Resolves to `true` when the path exists. Never throws for missing paths. */
+  exists(path: string): Promise<boolean>;
+  /** Lists the immediate children of a directory, sorted directories-first then by name. */
+  readDirectory(path: string): Promise<DirectoryEntry[]>;
+  /**
+   * Watches a path for changes.
+   *
+   * Events are debounced and delivered in batches, so a single listener call
+   * may describe several changes at once.
+   *
+   * @returns A {@link Disposable} that stops the watch.
+   */
+  watch(path: string, listener: (events: readonly FileChangeEvent[]) => unknown, options?: WatchOptions): Disposable;
+  /** Fires for every change anywhere in the workspace, after exclusion filtering. */
+  readonly onDidChangeFile: Event<readonly FileChangeEvent[]>;
+}
+//#endregion
+//#region src/keybindings.d.ts
+/**
+ * A keybinding declared statically by an extension, binding a key sequence to a command.
+ *
+ * @example
+ * ```ts
+ * { command: "hudhod.newFile.create", key: "ctrl+n", mac: "cmd+n" }
+ * ```
+ */
+interface KeybindingContribution {
+  /** The command id to invoke. */
+  readonly command: string;
+  /** Key sequence (e.g. `"ctrl+n"`, `"ctrl+shift+p"`). Modifiers: `ctrl`, `shift`, `alt`, `cmd`/`meta`. */
+  readonly key: string;
+  /** Optional macOS-specific override. Defaults to `key` on mac if not provided. */
+  readonly mac?: string;
+}
+/**
+ * A resolved keybinding after conflict resolution and platform normalization.
+ *
+ * Multiple extensions may contribute the same key; the last registration wins.
+ */
+interface ResolvedKeybinding {
+  /** The normalized key sequence for the current platform. */
+  readonly key: string;
+  /** The command id to invoke. */
+  readonly command: string;
+  /** Where the keybinding came from. */
+  readonly source: "extension" | "builtin";
+  /** The extension id if source is `"extension"`. */
+  readonly extensionId?: string;
+}
+/**
+ * Register and resolve keybindings.
+ */
+interface KeybindingsApi {
+  /**
+   * Registers a keybinding.
+   *
+   * If the same `key` is already bound, the new binding replaces the old one.
+   * Return the {@link Disposable} to restore the previous binding when disposed.
+   */
+  registerKeybinding(binding: KeybindingContribution): Disposable;
+  /** Lists all registered keybindings. */
+  getKeybindings(): Promise<ResolvedKeybinding[]>;
+}
+//#endregion
+//#region src/process.d.ts
+/** Options shared by {@link ProcessApi.spawn} and {@link ProcessApi.exec}. */
+interface SpawnOptions {
+  /**
+   * Working directory for the process.
+   * @defaultValue The workspace root.
+   */
+  readonly cwd?: string;
+  /** Extra environment variables, merged over the runtime defaults. */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Allocate a pseudo-terminal with these dimensions. Required for programs
+   * that render interactive UI or colourised output.
+   */
+  readonly terminal?: {
+    readonly cols: number;
+    readonly rows: number;
+  };
+}
+/** Options for {@link ProcessApi.exec}. */
+interface ExecOptions extends SpawnOptions {
+  /**
+   * Kill the process after this many milliseconds. Pass `false` to wait
+   * indefinitely — only do this for processes you are certain will terminate.
+   * @defaultValue 60000
+   */
+  readonly timeout?: number | false;
+  /**
+   * Stop buffering after this many bytes of output and kill the process. Pass
+   * `false` to buffer without limit.
+   * @defaultValue 1048576 (1 MiB)
+   */
+  readonly maxOutputBytes?: number | false;
+}
+/** The outcome of a completed {@link ProcessApi.exec} call. */
+interface ExecResult {
+  /** Exit code. `0` conventionally means success. */
+  readonly exitCode: number;
+  /** Merged stdout and stderr, decoded as UTF-8. */
+  readonly output: string;
+  /** Whether `output` was cut short by `maxOutputBytes`. */
+  readonly truncated: boolean;
+  /** Wall-clock duration in milliseconds. */
+  readonly durationMs: number;
+}
+/** Lifecycle state of a tracked process. */
+type ProcessStatus = "running" | "exited" | "killed";
+/** A structured-cloneable snapshot of a process, safe to send across a worker boundary. */
+interface ProcessInfo {
+  /** Host-assigned identifier, unique for the session. */
+  readonly id: string;
+  /** The executable that was spawned. */
+  readonly command: string;
+  /** Arguments passed to the executable. */
+  readonly args: readonly string[];
+  /** Start time in milliseconds since the Unix epoch. */
+  readonly startedAt: number;
+  /** Current lifecycle state. */
+  readonly status: ProcessStatus;
+  /** Exit code, present once the process has finished. */
+  readonly exitCode?: number;
+}
+/**
+ * A live handle to a running process.
+ *
+ * Unlike {@link ProcessInfo} this holds streams, so it cannot cross a worker
+ * boundary and is only available to same-context callers.
+ */
+interface ProcessHandle extends ProcessInfo {
+  /** Merged stdout and stderr, as a stream of decoded text chunks. */
+  readonly output: ReadableStream<string>;
+  /** Standard input. Only writable when the process was spawned with a terminal. */
+  readonly input: WritableStream<string>;
+  /** Resolves with the exit code when the process finishes. */
+  readonly exit: Promise<number>;
+  /** Terminates the process. Safe to call after it has already exited. */
+  kill(): void;
+  /** Resizes the pseudo-terminal. No-op when the process has no terminal. */
+  resize(dimensions: {
+    cols: number;
+    rows: number;
+  }): void;
+}
+/**
+ * Spawn and manage processes inside the workspace container.
+ *
+ * @example Running a one-shot command
+ * ```ts
+ * const { exitCode, output } = await hudhod.process.exec("node", ["-v"]);
+ * ```
+ *
+ * @example Streaming a long-running process
+ * ```ts
+ * const proc = await hudhod.process.spawn("npm", ["run", "build"]);
+ * await proc.output.pipeTo(new WritableStream({ write: (c) => console.log(c) }));
+ * ```
+ */
+interface ProcessApi {
+  /**
+   * Starts a process and returns immediately with a live handle.
+   * The caller owns the handle and is responsible for killing it.
+   */
+  spawn(command: string, args?: readonly string[], options?: SpawnOptions): Promise<ProcessHandle>;
+  /**
+   * Runs a command to completion and buffers its output.
+   *
+   * Guarded by a timeout and an output cap so a runaway command cannot hang
+   * the browser tab. Both guards are overridable, including disabling them.
+   *
+   * @throws A `ProcessTimeout` error when `timeout` elapses. The error carries
+   * the partial output collected so far.
+   * @throws An `OutputLimitExceeded` error when `maxOutputBytes` is exceeded.
+   */
+  exec(command: string, args?: readonly string[], options?: ExecOptions): Promise<ExecResult>;
+  /** Lists every process the host is currently tracking. */
+  list(): Promise<ProcessInfo[]>;
+  /** Kills a process by its {@link ProcessInfo.id}. Resolves `false` if unknown. */
+  kill(id: string): Promise<boolean>;
+  /** Fires whenever a process starts. */
+  readonly onDidStartProcess: Event<ProcessInfo>;
+  /** Fires whenever a process exits, for any reason. */
+  readonly onDidExitProcess: Event<ProcessInfo>;
+}
+//#endregion
+//#region src/search.d.ts
+/** Options for {@link SearchApi.findFiles}. */
+interface FindFilesOptions {
+  /**
+   * Glob patterns to exclude.
+   * @defaultValue The workspace `search.exclude` setting.
+   */
+  readonly exclude?: readonly string[];
+  /**
+   * Stop after this many matches.
+   * @defaultValue 1000
+   */
+  readonly maxResults?: number;
+  /** Abort the walk early. */
+  readonly token?: CancellationToken;
+}
+/** Options for {@link SearchApi.findInFiles}. */
+interface FindInFilesOptions extends FindFilesOptions {
+  /**
+   * Glob patterns to include.
+   * @defaultValue All files.
+   */
+  readonly include?: readonly string[];
+  /**
+   * Treat `query` as a regular expression.
+   * @defaultValue false
+   */
+  readonly isRegex?: boolean;
+  /**
+   * Match case exactly.
+   * @defaultValue false
+   */
+  readonly caseSensitive?: boolean;
+  /**
+   * Only match whole words.
+   * @defaultValue false
+   */
+  readonly wholeWord?: boolean;
+}
+/** A single match within a file. */
+interface SearchMatch {
+  /** Absolute path of the containing file. */
+  readonly path: string;
+  /** One-based line number. */
+  readonly line: number;
+  /** Zero-based column offset of the match start, in UTF-16 code units. */
+  readonly column: number;
+  /** Length of the matched text, in UTF-16 code units. */
+  readonly length: number;
+  /** The full text of the matching line, for display. */
+  readonly preview: string;
+}
+/** The outcome of a {@link SearchApi.findInFiles} call. */
+interface SearchResult {
+  /** Every match found, in file then line order. */
+  readonly matches: readonly SearchMatch[];
+  /** Whether the search stopped early because `maxResults` was reached. */
+  readonly limitHit: boolean;
+}
+/**
+ * Find files by name and text within files.
+ *
+ * @example
+ * ```ts
+ * const paths = await hudhod.search.findFiles("src/**\/*.ts");
+ * const { matches } = await hudhod.search.findInFiles("TODO", { include: ["**\/*.ts"] });
+ * ```
+ */
+interface SearchApi {
+  /**
+   * Returns absolute paths matching a glob pattern.
+   * Honours the workspace exclude settings unless overridden.
+   */
+  findFiles(include: string, options?: FindFilesOptions): Promise<string[]>;
+  /** Searches file contents for `query`. */
+  findInFiles(query: string, options?: FindInFilesOptions): Promise<SearchResult>;
+  /**
+   * Replaces every match of `query` with `replacement`.
+   * @returns The number of files modified.
+   */
+  replaceInFiles(query: string, replacement: string, options?: FindInFilesOptions): Promise<number>;
+}
+//#endregion
+//#region src/terminal.d.ts
+/** Options for {@link TerminalApi.create}. */
+interface CreateTerminalOptions {
+  /**
+   * Tab title.
+   * @defaultValue "Terminal"
+   */
+  readonly name?: string;
+  /**
+   * Working directory.
+   * @defaultValue The workspace root.
+   */
+  readonly cwd?: string;
+}
+/** A shell session backed by a real pseudo-terminal. */
+interface Terminal extends Disposable {
+  /** Host-assigned identifier, unique for the session. */
+  readonly id: string;
+  /** Tab title. */
+  readonly name: string;
+  /** Writes text to the terminal's stdin. */
+  sendText(text: string, addNewline?: boolean): Promise<void>;
+  /** Brings the terminal's panel to the foreground. */
+  show(): Promise<void>;
+}
+/**
+ * Create and control interactive shells.
+ *
+ * @example
+ * ```ts
+ * const term = await hudhod.terminal.create({ name: "Build" });
+ * await term.sendText("npm run build");
+ * ```
+ */
+interface TerminalApi {
+  /** Opens a new shell session. */
+  create(options?: CreateTerminalOptions): Promise<Terminal>;
+  /** Every terminal currently open. */
+  readonly terminals: readonly Terminal[];
+  /** Fires when a terminal is created. */
+  readonly onDidOpenTerminal: Event<Terminal>;
+  /** Fires when a terminal is disposed. */
+  readonly onDidCloseTerminal: Event<Terminal>;
+}
+//#endregion
+//#region src/window.d.ts
+/** Severity of a notification. */
+type MessageSeverity = "info" | "warning" | "error";
+/** Options for {@link WindowApi.showInputBox}. */
+interface InputBoxOptions {
+  /** Dialog heading. */
+  readonly title?: string;
+  /** Placeholder shown while the field is empty. */
+  readonly placeholder?: string;
+  /** Initial field value. */
+  readonly value?: string;
+  /** Label for the confirm button. */
+  readonly confirmLabel?: string;
+  /** Return a message to block submission, or `undefined` to allow it. */
+  readonly validate?: (value: string) => string | undefined;
+}
+/** A selectable entry in a quick pick. */
+interface QuickPickItem {
+  /** Primary text. */
+  readonly label: string;
+  /** Secondary text shown beside the label. */
+  readonly description?: string;
+  /** Opaque value returned on selection. Defaults to `label`. */
+  readonly value?: string;
+}
+/** Options for {@link WindowApi.showQuickPick}. */
+interface QuickPickOptions {
+  /** Dialog heading. */
+  readonly title?: string;
+  /** Placeholder shown in the filter field. */
+  readonly placeholder?: string;
+}
+/** Where a contributed panel should dock by default. */
+type PanelLocation = "left" | "right" | "bottom" | "center";
+/** Options for {@link WindowApi.registerPanel}. */
+interface RegisterPanelOptions {
+  /** Tab title. */
+  readonly title: string;
+  /**
+   * Preferred dock location.
+   * @defaultValue "bottom"
+   */
+  readonly location?: PanelLocation;
+  /** Initial width in pixels, for `left` and `right` panels. */
+  readonly initialWidth?: number;
+  /** Initial height in pixels, for `bottom` panels. */
+  readonly initialHeight?: number;
+  /**
+   * Open the panel as soon as it is registered.
+   * @defaultValue false
+   */
+  readonly openImmediately?: boolean;
+}
+/** Options for {@link WindowApi.registerView}. */
+interface RegisterViewOptions {
+  /** Header title declared by the view contribution. */
+  readonly title: string;
+}
+/**
+ * Renders a contributed panel's content into a host-provided element.
+ *
+ * Returning a cleanup function is optional but recommended; the host calls it
+ * when the panel closes.
+ */
+type PanelRenderer = (container: HTMLElement) => void | (() => void) | Promise<void | (() => void)>;
+/** The file currently focused in the editor. */
+interface ActiveEditor {
+  /** Absolute path of the open file. */
+  readonly path: string;
+  /** Whether the file has unsaved changes. */
+  readonly dirty: boolean;
+}
+/**
+ * Show UI and contribute panels.
+ *
+ * @example
+ * ```ts
+ * hudhod.window.registerPanel("demo.stats", (el) => {
+ *   el.textContent = "Hello from an extension panel";
+ * }, { title: "Stats", location: "right" });
+ * ```
+ */
+interface WindowApi {
+  /** Shows a transient notification. */
+  showMessage(message: string, severity?: MessageSeverity): Promise<void>;
+  /** Prompts for a single line of text. Resolves `undefined` if cancelled. */
+  showInputBox(options?: InputBoxOptions): Promise<string | undefined>;
+  /** Prompts the user to pick one item. Resolves `undefined` if cancelled. */
+  showQuickPick(items: readonly QuickPickItem[], options?: QuickPickOptions): Promise<string | undefined>;
+  /**
+   * Contributes a panel to the workbench layout.
+   * @returns A {@link Disposable} that removes the panel.
+   */
+  registerPanel(id: string, render: PanelRenderer, options: RegisterPanelOptions): Disposable;
+  /** Supplies the body renderer for a contributed view. */
+  registerView(id: string, render: PanelRenderer, options: RegisterViewOptions): Disposable;
+  /** Opens a panel, or focuses it when already open. */
+  openPanel(id: string): Promise<void>;
+  /** Closes a panel. Resolves `false` when it was not open. */
+  closePanel(id: string): Promise<boolean>;
+  /** Opens a file in the editor. */
+  openFile(path: string): Promise<void>;
+  /** The currently focused editor, if any. */
+  readonly activeEditor: ActiveEditor | undefined;
+  /** Fires when editor focus moves to a different file. */
+  readonly onDidChangeActiveEditor: Event<ActiveEditor | undefined>;
+}
+//#endregion
+//#region src/workspace.d.ts
+/** A range within a text document, using zero-based line and character offsets. */
+interface Range {
+  /** Zero-based start line. */
+  readonly startLine: number;
+  /** Zero-based start character offset, in UTF-16 code units. */
+  readonly startCharacter: number;
+  /** Zero-based end line. */
+  readonly endLine: number;
+  /** Zero-based end character offset, in UTF-16 code units. */
+  readonly endCharacter: number;
+}
+/** Replaces `range` with `text`. Omit `range` to replace the whole file. */
+interface TextEdit {
+  /** The region to replace. When absent, the entire file is replaced. */
+  readonly range?: Range;
+  /** The replacement text. Use an empty string to delete. */
+  readonly text: string;
+}
+/** A set of edits applied to one file. */
+interface FileEdit {
+  /** Absolute path of the file to modify. */
+  readonly path: string;
+  /** Edits to apply, resolved against the file's original content. */
+  readonly edits: readonly TextEdit[];
+}
+/**
+ * How an edit should reach the user.
+ *
+ * - `immediate` — apply straight away. The change is recorded in the edit
+ *   history and can be reverted, and lands in the editor's undo stack when the
+ *   file is open.
+ * - `review` — show the user a diff and wait. Nothing is written unless they
+ *   accept.
+ */
+type EditMode = "immediate" | "review";
+/** Options for {@link WorkspaceApi.applyEdit}. */
+interface ApplyEditOptions {
+  /**
+   * Whether to apply the edit directly or ask the user first.
+   * @defaultValue "immediate"
+   */
+  readonly mode?: EditMode;
+  /** Human-readable description, shown in review UI and the edit history. */
+  readonly label?: string;
+}
+/** The outcome of an {@link WorkspaceApi.applyEdit} call. */
+interface ApplyEditResult {
+  /** Whether the edit was written to disk. `false` when the user rejected a review. */
+  readonly applied: boolean;
+  /** Paths that were modified. */
+  readonly paths: readonly string[];
+  /**
+   * Identifier for this change in the edit history. Pass to
+   * {@link WorkspaceApi.revertEdit} to undo it.
+   */
+  readonly editId?: string;
+}
+/** A recorded workspace edit, retained so it can be reverted. */
+interface EditHistoryEntry {
+  /** Unique identifier for the change. */
+  readonly id: string;
+  /** Description supplied when the edit was applied. */
+  readonly label: string;
+  /** When the edit was applied, in milliseconds since the Unix epoch. */
+  readonly timestamp: number;
+  /** Paths the edit touched. */
+  readonly paths: readonly string[];
+  /** Whether the change has since been reverted. */
+  readonly reverted: boolean;
+}
+/**
+ * Workspace-level operations: roots, snapshots, and edits.
+ *
+ * @example Applying an agent edit the user must approve
+ * ```ts
+ * const result = await hudhod.workspace.applyEdit(
+ *   [{ path: "/src/index.ts", edits: [{ text: nextSource }] }],
+ *   { mode: "review", label: "Add error handling" },
+ * );
+ * ```
+ */
+interface WorkspaceApi {
+  /** Absolute path of the workspace root. */
+  readonly rootPath: string;
+  /**
+   * Applies edits across one or more files.
+   *
+   * Edits within a single file are applied bottom-up so earlier ranges stay
+   * valid. The whole set is atomic: if any file fails, none are written.
+   */
+  applyEdit(edits: readonly FileEdit[], options?: ApplyEditOptions): Promise<ApplyEditResult>;
+  /** Undoes a previously applied edit, restoring the prior contents. */
+  revertEdit(editId: string): Promise<boolean>;
+  /** Returns the recorded edit history, newest first. */
+  editHistory(): Promise<EditHistoryEntry[]>;
+  /** Fires after any workspace edit is applied or reverted. */
+  readonly onDidApplyEdit: Event<EditHistoryEntry>;
+}
+//#endregion
+//#region src/api.d.ts
+/**
+ * Everything an extension can reach.
+ *
+ * An instance is passed to {@link ExtensionContext.hudhod} on activation.
+ * The same surface backs the AI agent tool layer, so anything an extension can
+ * do, an agent can do.
+ */
+interface HudhodApi {
+  /** Semver version of the host runtime. */
+  readonly version: string;
+  /** Read and write files. */
+  readonly fs: FileSystemApi;
+  /** Workspace roots, edits, and edit history. */
+  readonly workspace: WorkspaceApi;
+  /** Find files and search their contents. */
+  readonly search: SearchApi;
+  /** Compare text and apply patches. */
+  readonly diff: DiffApi;
+  /** Spawn and manage processes. */
+  readonly process: ProcessApi;
+  /** Create and control interactive shells. */
+  readonly terminal: TerminalApi;
+  /** Register and invoke commands. */
+  readonly commands: CommandsApi;
+  /** Register and resolve keybindings. */
+  readonly keybindings: KeybindingsApi;
+  /** Show UI and contribute panels. */
+  readonly window: WindowApi;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error codes shared between the host and extensions.
+ *
+ * The host throws `HudhodError` instances carrying one of these codes. Matching
+ * on {@link HudhodErrorCode} is stable across versions; matching on message
+ * text is not.
+ *
+ * @packageDocumentation
+ */
+/** Every error code the host can raise. */
+type HudhodErrorCode = /** The requested path does not exist. */
+"FileNotFound"
+/** The path already exists and `overwrite` was not set. */ | "FileExists"
+/** A directory was expected but the path is a file. */ | "NotADirectory"
+/** A file was expected but the path is a directory. */ | "NotAFile"
+/** The directory is not empty and `recursive` was not set. */ | "DirectoryNotEmpty"
+/** The path is malformed, relative, or escapes the workspace root. */ | "InvalidPath"
+/** A command id was invoked but never registered. */ | "CommandNotFound"
+/** A command id was registered twice. */ | "CommandExists"
+/** A process exceeded its configured timeout and was killed. */ | "ProcessTimeout"
+/** A process produced more output than its configured cap allowed. */ | "OutputLimitExceeded"
+/** A unified diff did not apply cleanly. */ | "PatchFailed"
+/** The operation was cancelled by its caller. */ | "Cancelled";
+/** An error raised by the hudhod host. */
+interface HudhodError extends Error {
+  /** Stable, machine-readable classification of the failure. */
+  readonly code: HudhodErrorCode;
+  /** The path involved, for file system errors. */
+  readonly path?: string;
+  /** Output collected before the failure, for process errors. */
+  readonly partialOutput?: string;
+}
+/**
+ * Narrows an unknown caught value to a {@link HudhodError}.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await hudhod.fs.readTextFile("/missing.ts");
+ * } catch (error) {
+ *   if (isHudhodError(error) && error.code === "FileNotFound") {
+ *     // handle it
+ *   }
+ * }
+ * ```
+ */
+declare function isHudhodError(value: unknown): value is HudhodError;
+//#endregion
+//#region src/extension.d.ts
+/**
+ * When an extension should be loaded.
+ *
+ * - `onStartup` — activate as soon as the workbench is ready.
+ * - `onCommand:<id>` — activate the first time a command is invoked.
+ * - `onFileOpen:<glob>` — activate when a matching file is opened.
+ * - `onView:<panelId>` — activate when a contributed panel is opened.
+ *
+ * Prefer lazy events over `onStartup`; every eager extension delays boot.
+ */
+type ActivationEvent = "onStartup" | `onCommand:${string}` | `onFileOpen:${string}` | `onView:${string}`;
+/** A command declared statically, so the palette can list it before activation. */
+interface CommandContribution {
+  /** Unique identifier, matching the id passed to `registerCommand`. */
+  readonly id: string;
+  /** Label shown in the command palette. */
+  readonly title: string;
+  /** Optional grouping shown alongside the title. */
+  readonly category?: string;
+}
+/** A panel declared statically, so the layout can reserve a slot for it. */
+interface PanelContribution {
+  /** Unique identifier, matching the id passed to `registerPanel`. */
+  readonly id: string;
+  /** Tab title. */
+  readonly title: string;
+  /** Opaque to the SDK; the host application defines what a valid icon value is. */
+  readonly icon?: unknown;
+  /**
+   * Preferred dock location.
+   * @defaultValue "bottom"
+   */
+  readonly location?: "left" | "right" | "bottom" | "center";
+}
+/** An activity-bar container that can hold one or more contributed views. */
+interface ViewContainerContribution {
+  /** Unique identifier, matching the id passed to `registerPanel`. */
+  readonly id: string;
+  /** Tab title. */
+  readonly title: string;
+  /** Opaque to the SDK; the host application defines what a valid icon value is. */
+  readonly icon?: unknown;
+  /** Preferred dock location. */
+  readonly location?: "left" | "right" | "bottom" | "center";
+}
+/** A collapsible body section contributed to a view container. */
+interface ViewContribution {
+  /** Unique identifier, matching the id passed to `registerView`. */
+  readonly id: string;
+  /** Header text shown by the workbench. */
+  readonly title: string;
+  /** Id of the view container that owns this view. */
+  readonly container: string;
+  /** Sort order within the container; unordered views follow ordered ones. */
+  readonly order?: number;
+}
+/** Static declarations an extension makes to the workbench. */
+interface Contributions {
+  /** Commands the extension provides. */
+  readonly commands?: readonly CommandContribution[];
+  /** Panels the extension provides. */
+  readonly panels?: readonly PanelContribution[];
+  /** Activity-bar containers the extension provides. */
+  readonly viewContainers?: readonly ViewContainerContribution[];
+  /** Accordion views the extension provides. */
+  readonly views?: readonly ViewContribution[];
+  /** Keybindings the extension provides. */
+  readonly keybindings?: readonly KeybindingContribution[];
+}
+/** Identity and capabilities of an extension. */
+interface ExtensionManifest {
+  /** Unique identifier, conventionally `publisher.name`. */
+  readonly id: string;
+  /** Human-readable name. */
+  readonly name: string;
+  /** Semver version string. */
+  readonly version: string;
+  /** Short summary shown in extension listings. */
+  readonly description?: string;
+  /** Events that trigger activation. Defaults to `["onStartup"]`. */
+  readonly activationEvents?: readonly ActivationEvent[];
+  /** Static contributions to the workbench. */
+  readonly contributes?: Contributions;
+}
+/**
+ * Per-extension state handed to {@link Extension.activate}.
+ */
+interface ExtensionContext {
+  /** The manifest this extension was loaded with. */
+  readonly manifest: ExtensionManifest;
+  /**
+   * Disposables cleaned up automatically on deactivation.
+   * Push every subscription and registration here.
+   */
+  readonly subscriptions: Disposable[];
+  /** The full host API. Identical to the module-scoped `hudhod` object. */
+  readonly hudhod: HudhodApi;
+}
+/** The shape an extension module must export. */
+interface Extension {
+  /** Describes the extension to the host. */
+  readonly manifest: ExtensionManifest;
+  /** Called once, when an activation event fires. */
+  activate(context: ExtensionContext): void | Promise<void>;
+  /** Called once, before the extension is unloaded. */
+  deactivate?(): void | Promise<void>;
+}
+/**
+ * Declares an extension with full type inference.
+ *
+ * This is an identity function — it exists purely so the object literal is
+ * checked against {@link Extension} at the definition site rather than at the
+ * point of use.
+ *
+ * @example
+ * ```ts
+ * export default defineExtension({
+ *   manifest: {
+ *     id: "acme.hello",
+ *     name: "Hello",
+ *     version: "1.0.0",
+ *     activationEvents: ["onCommand:acme.hello.greet"],
+ *     contributes: {
+ *       commands: [{ id: "acme.hello.greet", title: "Say Hello" }],
+ *     },
+ *   },
+ *   activate(context) {
+ *     context.subscriptions.push(
+ *       context.hudhod.commands.registerCommand("acme.hello.greet", () =>
+ *         context.hudhod.window.showMessage("Hello!"),
+ *       ),
+ *     );
+ *   },
+ * });
+ * ```
+ */
+declare function defineExtension(extension: Extension): Extension;
+//#endregion
+export { type ActivationEvent, type ActiveEditor, type ApplyEditOptions, type ApplyEditResult, type CancellationToken, type CommandContribution, type CommandDescriptor, type CommandsApi, type Contributions, type CreateTerminalOptions, type DeleteOptions, type DiffApi, type DiffChange, type DiffOptions, type DiffStat, type DirectoryEntry, type Disposable, type EditHistoryEntry, type EditMode, type Event, type ExecOptions, type ExecResult, type Extension, type ExtensionContext, type ExtensionManifest, type FileChangeEvent, type FileChangeType, type FileEdit, type FileStat, type FileSystemApi, type FileType, type FindFilesOptions, type FindInFilesOptions, type HudhodApi, type HudhodError, type HudhodErrorCode, type InputBoxOptions, type KeybindingContribution, type KeybindingsApi, type MessageSeverity, type MoveOptions, type PanelContribution, type PanelLocation, type PanelRenderer, type ProcessApi, type ProcessHandle, type ProcessInfo, type ProcessStatus, type QuickPickItem, type QuickPickOptions, type Range, type RegisterCommandOptions, type RegisterPanelOptions, type RegisterViewOptions, type ResolvedKeybinding, type SearchApi, type SearchMatch, type SearchResult, type SpawnOptions, type Terminal, type TerminalApi, type TextEdit, type ViewContainerContribution, type ViewContribution, type WatchOptions, type WindowApi, type WorkspaceApi, type WriteFileOptions, defineExtension, isHudhodError };

package/dist/index.js

@@ -0,0 +1,56 @@
+//#region src/errors.ts
+/**
+* Narrows an unknown caught value to a {@link HudhodError}.
+*
+* @example
+* ```ts
+* try {
+*   await hudhod.fs.readTextFile("/missing.ts");
+* } catch (error) {
+*   if (isHudhodError(error) && error.code === "FileNotFound") {
+*     // handle it
+*   }
+* }
+* ```
+*/
+function isHudhodError(value) {
+	return value instanceof Error && typeof value.code === "string";
+}
+
+//#endregion
+//#region src/extension.ts
+/**
+* Declares an extension with full type inference.
+*
+* This is an identity function — it exists purely so the object literal is
+* checked against {@link Extension} at the definition site rather than at the
+* point of use.
+*
+* @example
+* ```ts
+* export default defineExtension({
+*   manifest: {
+*     id: "acme.hello",
+*     name: "Hello",
+*     version: "1.0.0",
+*     activationEvents: ["onCommand:acme.hello.greet"],
+*     contributes: {
+*       commands: [{ id: "acme.hello.greet", title: "Say Hello" }],
+*     },
+*   },
+*   activate(context) {
+*     context.subscriptions.push(
+*       context.hudhod.commands.registerCommand("acme.hello.greet", () =>
+*         context.hudhod.window.showMessage("Hello!"),
+*       ),
+*     );
+*   },
+* });
+* ```
+*/
+function defineExtension(extension) {
+	return extension;
+}
+
+//#endregion
+export { defineExtension, isHudhodError };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hudhod/sdk",
+  "version": "0.1.0",
+  "description": "Public API surface for building hudhod extensions — an in-browser IDE runtime powered by WebContainers.",
+  "keywords": [
+    "browser-ide",
+    "extensions",
+    "hudhod",
+    "ide",
+    "sdk",
+    "webcontainer"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}