@pimote/sdk 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Lennartz
+
+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,193 @@
+# @pimote/sdk
+
+Pimote's extensibility SDK — everything a [pi](https://github.com/mariozechner/pi-coding-agent) extension imports to talk to [pimote](https://github.com/alennartz/pimote). One subpath module per extension seam:
+
+- **`@pimote/sdk/panels`** — push structured card data to the pimote web client
+- **`@pimote/sdk/projects`** — contribute project discovery and creation to pimote's project layer
+
+The root `@pimote/sdk` import re-exports both modules.
+
+## Install
+
+```bash
+npm install @pimote/sdk
+```
+
+Requires `@earendil-works/pi-coding-agent` as an optional peer dependency (already present in any pi extension; only the panels seam imports from it).
+
+## Panels — `@pimote/sdk/panels`
+
+Push structured card data from pi extensions to the pimote web client.
+
+When your extension is running inside pimote, `detect()` returns a handle for sending cards to the panel UI. When running in a normal pi terminal session, it returns `null` — your extension keeps working either way.
+
+### Usage
+
+```ts
+import { detect } from '@pimote/sdk/panels';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+
+const extension: ExtensionFactory = (pi) => {
+  const panels = detect(pi, 'my-extension');
+
+  if (panels) {
+    // Running inside pimote — push cards to the web UI
+    panels.updateCards([
+      {
+        id: 'status',
+        color: 'success',
+        header: { title: 'Build', tag: 'passed' },
+        body: [{ content: 'All 42 tests passed', style: 'text' }],
+        footer: ['2.3s'],
+      },
+    ]);
+  }
+
+  // Rest of your extension — works in both pimote and regular pi
+};
+
+export default extension;
+```
+
+### API
+
+#### `detect(pi, key)`
+
+Detects whether the extension is running inside pimote.
+
+- **`pi`** — The `ExtensionAPI` object passed to your extension factory.
+- **`key`** — A unique namespace string for your extension's cards. Cards from different keys don't interfere with each other.
+
+Returns a `PanelHandle` if running inside pimote, or `null` otherwise.
+
+Calling `detect()` again with the same key deactivates the previous handle (its methods become no-ops) and returns a new one.
+
+#### `PanelHandle`
+
+```ts
+interface PanelHandle {
+  /** Replace all cards for this namespace. Previous cards are discarded. */
+  updateCards(cards: Card[]): void;
+  /** Remove all cards for this namespace. */
+  clear(): void;
+}
+```
+
+#### `Card`
+
+```ts
+interface Card {
+  id: string;
+  color?: 'accent' | 'success' | 'warning' | 'error' | 'muted';
+  header: {
+    title: string;
+    tag?: string;
+  };
+  body?: BodySection[];
+  footer?: string[];
+  href?: string;
+}
+
+interface BodySection {
+  content: string;
+  style: 'text' | 'code' | 'secondary';
+}
+```
+
+- **`id`** — Unique identifier for the card within your namespace.
+- **`color`** — Optional color theme for the card.
+- **`header.title`** — Card title, always visible.
+- **`header.tag`** — Optional short label displayed next to the title.
+- **`body`** — Optional content sections, each with a style (`text`, `code`, or `secondary`).
+- **`footer`** — Optional array of short strings displayed at the bottom.
+- **`href`** — Optional same-origin URL. When set, the client renders the
+  entire card as a clickable link (same-tab navigation). Use for cards
+  that point at a hosted resource — e.g. a bundle served by pimote's
+  static-host tool.
+
+### How it works
+
+Detection uses pi's EventBus for a synchronous in-process round-trip — pimote's server listens for `pimote:detect:request` and responds on `pimote:detect:response`. Card updates are emitted on the `pimote:panels` channel, which pimote's session manager picks up and pushes to the web client over WebSocket.
+
+When pimote isn't present, the EventBus emit fires with no listener, `detect()` returns `null`, and there's zero overhead.
+
+## Projects — `@pimote/sdk/projects`
+
+Type-only module for user-authored project-source modules: pimote scans a project-sources directory (default `~/.config/pimote/project-sources`, configurable via `projectSourcesDir`), dynamic-imports every JS/TS module it finds, and collects each module's exported `sources` and `creators` arrays. Sources contribute repos and multi-repo projects to pimote's project layer; creators make new project directories from user-supplied form params.
+
+### Writing a module
+
+```ts
+// ~/.config/pimote/project-sources/my-source.ts
+import type { ProjectSource, ProjectCreator } from '@pimote/sdk/projects';
+
+export const sources: ProjectSource[] = [
+  {
+    id: 'my-source',
+    async list() {
+      return [
+        {
+          kind: 'repo',
+          path: '/home/me/work/api',
+          name: 'api',
+          branch: 'main',
+          dirty: false,
+          ahead: 0,
+          behind: 0,
+        },
+      ];
+    },
+  },
+];
+
+export const creators: ProjectCreator[] = [
+  {
+    id: 'my-creator',
+    describe() {
+      return { label: 'New API project', paramSchema: { name: 'string', tags: 'string[]' } };
+    },
+    async create(params) {
+      const path = `/home/me/work/${String(params.name)}`;
+      // ... scaffold the project directory ...
+      return { path };
+    },
+  },
+];
+```
+
+### `ProjectSource`
+
+The discovery seam. `list()` is called on cache miss and must return the current entries without mutating anything. The optional `onProjectOpen(projectPath)` hook is awaited before any open of a listed entry proceeds — whether the target exists on disk or not, and from every open path (row click, new session, manager tool). Sources self-filter by path: probe the disk and scaffold if the entry is theirs and missing; do other open-time work otherwise. A thrown error aborts the open and surfaces the message to the user.
+
+### `ProjectCreator`
+
+The creation seam. `describe()` returns the human-readable form for the creation UI — a `label` plus a `paramSchema` mapping param names to `'string' | 'string[]'`. `create(params)` receives the user-supplied params, makes the project directory, and returns its `{ path }`.
+
+### Entry shapes
+
+`list()` returns `SourceEntry[]` — a repo or a multi-repo project:
+
+```ts
+/** Feeds a single-repo project. Extends `RepoInfo`. */
+interface RepoSourceEntry extends RepoInfo {
+  kind: 'repo';
+}
+
+/** Feeds a multi-repo project over member paths. */
+interface MultiRepoSourceEntry {
+  kind: 'project';
+  path: string;
+  name: string;
+  memberPaths: string[];
+  /** Source-contributed tags; shown to the user but not user-removable. */
+  tags?: string[];
+}
+```
+
+### `RepoInfo`
+
+Repo facts as contributed by sources: `path`, `name`, `branch` (`string | null`), `dirty`, `ahead`, `behind`, and optional `lastActivity` (epoch ms), `missing` (repo path no longer exists on disk), and `tags`. It mirrors pimote's wire `RepoInfo` type — same name, same fields — so extension authors can write `interface MyEntry extends RepoInfo` against the SDK alone.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './panels/index.js';
+export * from './projects/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './panels/index.js';
+export * from './projects/index.js';

package/dist/panels/detect.d.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PanelHandle } from './types.js';
+/**
+ * Detect whether running inside pimote. Returns a scoped handle for pushing
+ * card data, or null if not in pimote.
+ *
+ * Each key gets an independent namespace — cards from different keys don't
+ * interfere. Calling detect() again with the same key deactivates the
+ * previous handle (its methods become no-ops) and returns a new one.
+ */
+export declare function detect(pi: ExtensionAPI, key: string): PanelHandle | null;

package/dist/panels/detect.js

@@ -0,0 +1,48 @@
+/** Tracks active state per key so re-detection deactivates the old handle.
+ *  Scoped per ExtensionAPI instance (one per pi session) via a WeakMap, so two
+ *  sessions in the same process that detect() the same key don't deactivate
+ *  each other's handles. */
+const handlesByApi = new WeakMap();
+/**
+ * Detect whether running inside pimote. Returns a scoped handle for pushing
+ * card data, or null if not in pimote.
+ *
+ * Each key gets an independent namespace — cards from different keys don't
+ * interfere. Calling detect() again with the same key deactivates the
+ * previous handle (its methods become no-ops) and returns a new one.
+ */
+export function detect(pi, key) {
+    // Synchronous detection round-trip
+    let detected = false;
+    const unsub = pi.events.on('pimote:detect:response', () => {
+        detected = true;
+    });
+    pi.events.emit('pimote:detect:request', {});
+    unsub();
+    if (!detected)
+        return null;
+    // Deactivate previous handle for this key (scoped to this pi instance)
+    let handles = handlesByApi.get(pi);
+    if (!handles) {
+        handles = new Map();
+        handlesByApi.set(pi, handles);
+    }
+    const prev = handles.get(key);
+    if (prev)
+        prev.active = false;
+    // Create new handle state
+    const state = { active: true };
+    handles.set(key, state);
+    return {
+        updateCards(cards) {
+            if (!state.active)
+                return;
+            pi.events.emit('pimote:panels', { type: 'cards', namespace: key, cards });
+        },
+        clear() {
+            if (!state.active)
+                return;
+            pi.events.emit('pimote:panels', { type: 'clear', namespace: key });
+        },
+    };
+}

package/dist/panels/index.d.ts

@@ -0,0 +1,2 @@
+export type { Card, CardColor, BodySection, BodySectionStyle, PanelHandle, PanelMessage } from './types.js';
+export { detect } from './detect.js';

package/dist/panels/index.js

@@ -0,0 +1 @@
+export { detect } from './detect.js';

package/dist/panels/types.d.ts

@@ -0,0 +1,37 @@
+export type CardColor = 'accent' | 'success' | 'warning' | 'error' | 'muted';
+export type BodySectionStyle = 'text' | 'code' | 'secondary';
+export interface BodySection {
+    content: string;
+    style: BodySectionStyle;
+}
+export interface Card {
+    id: string;
+    color?: CardColor;
+    header: {
+        title: string;
+        tag?: string;
+    };
+    body?: BodySection[];
+    footer?: string[];
+    /**
+     * Optional same-origin URL. When present, the client renders the entire
+     * card as a clickable link (same-tab navigation). Kept in lock-step with
+     * the protocol `Card` type in `shared/src/protocol.ts`.
+     */
+    href?: string;
+}
+export interface PanelHandle {
+    /** Replace this handle's cards. Full snapshot — previous cards for this namespace are discarded. */
+    updateCards(cards: Card[]): void;
+    /** Remove all cards for this namespace. */
+    clear(): void;
+}
+/** Message shapes emitted on the 'pimote:panels' EventBus channel. */
+export type PanelMessage = {
+    type: 'cards';
+    namespace: string;
+    cards: Card[];
+} | {
+    type: 'clear';
+    namespace: string;
+};

package/dist/panels/types.js

@@ -0,0 +1 @@
+export {};

package/dist/projects/index.d.ts

@@ -0,0 +1 @@
+export type { ProjectSource, ProjectCreator, ProjectCreatorDescriptor, ProjectCreatorParamType, SourceEntry, RepoSourceEntry, MultiRepoSourceEntry, RepoInfo } from './types.js';

package/dist/projects/index.js

@@ -0,0 +1 @@
+export {};

package/dist/projects/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Repo facts as contributed by sources. Twin of the wire `RepoInfo` in
+ * shared/src/protocol.ts — drift-guarded by server/src/sdk-twins.ts.
+ */
+export interface RepoInfo {
+    path: string;
+    name: string;
+    branch: string | null;
+    dirty: boolean;
+    /** Commits ahead of upstream; 0 when unknown. */
+    ahead: number;
+    behind: number;
+    /** Epoch ms of last session activity in this repo, when known. */
+    lastActivity?: number;
+    /** True when the repo path no longer exists on disk (deleted member, broken symlink). */
+    missing?: boolean;
+    /** Effective tags (user + source-contributed). Absent when untagged. */
+    tags?: string[];
+}
+/** Human-readable parameter type for a creator form field. */
+export type ProjectCreatorParamType = 'string' | 'string[]';
+/** A repo entry contributed to the discovery index (feeds single-repo projects). */
+export interface RepoSourceEntry extends RepoInfo {
+    kind: 'repo';
+}
+/**
+ * A multi-repo project entry contributed to the project layer. `memberPaths`
+ * are concrete paths that may not exist on disk yet; the server derives
+ * existence state itself — sources never flag "virtual".
+ */
+export interface MultiRepoSourceEntry {
+    kind: 'project';
+    path: string;
+    name: string;
+    memberPaths: string[];
+    /** Source-contributed tags; shown to the user but not user-removable. */
+    tags?: string[];
+}
+/** Anything a source lists: a repo, or a multi-repo project over member paths. */
+export type SourceEntry = RepoSourceEntry | MultiRepoSourceEntry;
+/**
+ * Extensible discovery seam: a source contributes repos and multi-repo
+ * projects to the project layer. Built in: the filesystem walker over
+ * configured roots. User-authored sources are dynamic-imported from the
+ * configured project-sources directory.
+ */
+export interface ProjectSource {
+    readonly id: string;
+    /** Discover entries; called on cache miss. Must not mutate anything. */
+    list(): Promise<SourceEntry[]>;
+    /**
+     * Awaited before any open of a listed entry proceeds — whether the target
+     * exists on disk or not, and from every open path (row click, new session,
+     * manager tool). Sources self-filter by path: probe the disk and scaffold
+     * if the entry is theirs and missing; do other open-time work otherwise.
+     * A thrown error aborts the open and surfaces the message to the user.
+     */
+    onProjectOpen?(projectPath: string): Promise<void>;
+}
+/** Human-readable description of a creator's form, for the creation UI. */
+export interface ProjectCreatorDescriptor {
+    label: string;
+    paramSchema: Record<string, ProjectCreatorParamType>;
+}
+/**
+ * Extensible creation seam: a creator makes a new project directory from
+ * user-supplied params. Built in: mkdir + git init. User-authored creators
+ * are dynamic-imported from the configured project-sources directory.
+ */
+export interface ProjectCreator {
+    readonly id: string;
+    /** Human-readable description for the creation UI. */
+    describe(): ProjectCreatorDescriptor;
+    create(params: Record<string, unknown>): Promise<{
+        path: string;
+    }>;
+}

package/dist/projects/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pimote/sdk",
+  "version": "0.13.0",
+  "description": "Pimote extensibility SDK: panel cards and project discovery/creation seams for pi extensions",
+  "type": "module",
+  "license": "MIT",
+  "author": "Antoine Lennartz <alennartz@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alennartz/pimote.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/alennartz/pimote/tree/main/packages/sdk#readme",
+  "bugs": "https://github.com/alennartz/pimote/issues",
+  "keywords": [
+    "pi",
+    "pimote",
+    "extension",
+    "sdk",
+    "projects",
+    "panels",
+    "cards"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./panels": "./dist/panels/index.js",
+    "./projects": "./dist/projects/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.99.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.99.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}