@bendyline/docblocks 1.1.2 → 2.0.0

package/src/host/index.ts

@@ -7,17 +7,63 @@
 export type {
   DocBlocksHostAPI,
   DocBlocksHostFsAPI,
+  DocBlocksHostExternalAPI,
   DocBlocksHostWorkspacesAPI,
   DocBlocksHostShellAPI,
+  DocBlocksHostExportAPI,
   DocBlocksHostFfmpegAPI,
   DocBlocksHostUpdaterAPI,
+  DocBlocksHostLifecycleAPI,
   ElectronWorkspaceInfo,
+  ExternalBinaryCommitResult,
+  HostCloseReason,
   HostEnvironment,
+  HostExportTargetGrant,
+  HostPrepareCloseRequest,
+  HostPrepareCloseResult,
   MenuCommand,
   OpenRequest,
+  UpdateInstallResult,
   UpdaterStatus,
 } from './types.js';
 
+export type {
+  DocBlocksHostGitAPI,
+  GitBranchInfo,
+  GitCapabilities,
+  GitCloneHandle,
+  GitCloneProgress,
+  GitError,
+  GitErrorCode,
+  GitFileAtRevision,
+  GitFileChange,
+  GitFileStatusCode,
+  GitLogEntry,
+  GitLogOptions,
+  GitRemoteInfo,
+  GitRepoDetection,
+  GitResult,
+  GitRevision,
+  GitStatus,
+} from './git.js';
+
+export {
+  ELECTRON_FILE_SYSTEM_V2_CAPABILITIES,
+  type DocBlocksHostFsV2API,
+  type HostFileSystemV2OpenRequest,
+  type HostFileSystemV2Result,
+  type HostFileSystemV2WatchMessage,
+} from './filesystem-v2.js';
+
+export {
+  HOST_WIRE_LIMITS,
+  isBoundedBytePayload,
+  isBoundedString,
+  isTrustedRendererUrl,
+  parseExternalHttpUrl,
+  parseOpenRequest,
+} from './wire-policy.js';
+
 import type { DocBlocksHostAPI } from './types.js';
 
 /** True when running inside the Electron desktop shell. */

package/src/host/types.ts

@@ -7,39 +7,50 @@
  * this shape; the React renderer calls it through `window.docBlocksHost`.
  */
 
-import type { FileSystemEntry, FileMeta } from '../filesystem/types.js';
+import type { FileCommitResult, FileSystemEntry, FileMeta } from '../filesystem/types.js';
+import type { DocBlocksHostFsV2API } from './filesystem-v2.js';
+import type { DocBlocksHostGitAPI } from './git.js';
 
-/** Filesystem operations scoped to a registered absolute root path. */
+/** Filesystem operations scoped to a main-owned registered workspace id. */
 export interface DocBlocksHostFsAPI {
-  readFile(rootPath: string, path: string): Promise<string | null>;
-  writeFile(rootPath: string, path: string, content: string): Promise<void>;
-  delete(rootPath: string, path: string): Promise<void>;
-  rename(rootPath: string, oldPath: string, newPath: string): Promise<void>;
-  readDirectory(rootPath: string, path: string): Promise<FileSystemEntry[]>;
-  exists(rootPath: string, path: string): Promise<boolean>;
-  createDirectory(rootPath: string, path: string): Promise<void>;
-  stat(rootPath: string, path: string): Promise<FileMeta | null>;
-  readBinary(rootPath: string, path: string): Promise<ArrayBuffer | null>;
-  writeBinary(rootPath: string, path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+  readFile(workspaceId: string, path: string): Promise<string | null>;
+  writeFile(workspaceId: string, path: string, content: string): Promise<void>;
+  commitFile(
+    workspaceId: string,
+    path: string,
+    content: string,
+    expectedContent: string | null,
+  ): Promise<FileCommitResult>;
+  delete(workspaceId: string, path: string): Promise<void>;
+  rename(workspaceId: string, oldPath: string, newPath: string): Promise<void>;
+  readDirectory(workspaceId: string, path: string): Promise<FileSystemEntry[]>;
+  exists(workspaceId: string, path: string): Promise<boolean>;
+  createDirectory(workspaceId: string, path: string): Promise<void>;
+  stat(workspaceId: string, path: string): Promise<FileMeta | null>;
+  readBinary(workspaceId: string, path: string): Promise<ArrayBuffer | null>;
+  writeBinary(workspaceId: string, path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
   /**
    * Subscribe to change notifications for a watched root. Returns an
    * unsubscribe function. The main process uses chokidar under the hood.
    */
-  watch(rootPath: string, onChange: (path: string) => void): () => void;
+  watch(workspaceId: string, onChange: (path: string) => void): () => void;
 }
 
 /** Descriptor returned for an Electron-managed workspace (backed by a folder). */
 export interface ElectronWorkspaceInfo {
   id: string;
   name: string;
+  /** Display/persistence metadata only. Privileged host calls accept `id`, never this path. */
   rootPath: string;
 }
 
 /** Workspace-management operations exposed to the renderer. */
 export interface DocBlocksHostWorkspacesAPI {
+  /** List only folders already persisted as trusted main-process roots. */
+  list(): Promise<ElectronWorkspaceInfo[]>;
   /**
-   * Return the default workspace (creating ~/Documents/DocBlocks on first
-   * call, or the user's configured default).
+   * Return the default workspace (creating DocBlocks inside the operating
+   * system's Documents folder on first call, or the user's configured default).
    */
   getDefault(): Promise<ElectronWorkspaceInfo>;
   /**
@@ -48,36 +59,58 @@ export interface DocBlocksHostWorkspacesAPI {
    */
   pickFolder(): Promise<ElectronWorkspaceInfo | null>;
   /**
-   * Re-register a previously known workspace so its rootPath is trusted
-   * for subsequent fs calls. Called on app startup for persisted
-   * electron-native workspaces before any fs operation.
+   * Re-register a previously picker-approved workspace by main-owned id.
+   * Called on app startup before any filesystem operation.
    */
-  register(info: ElectronWorkspaceInfo): Promise<void>;
+  register(workspaceId: string): Promise<void>;
   /** Remove a workspace from the trusted whitelist. */
   unregister(id: string): Promise<void>;
 }
 
 /** Shell operations — reveal in Finder/Explorer, open external URLs. */
 export interface DocBlocksHostShellAPI {
-  /** Reveal a file (by absolute path) in the OS file manager. */
-  revealInFolder(absolutePath: string): Promise<void>;
+  /** Reveal a registered workspace root or one root-relative entry. */
+  revealInFolder(workspaceId: string, workspacePath?: string): Promise<void>;
   /** Open a URL in the default browser. */
   openExternal(url: string): Promise<void>;
 }
 
+/** Exact, main-owned export authority. The display path is never authority. */
+export interface HostExportTargetGrant {
+  /** Null means this is a display-only suggestion and save must show a picker. */
+  grantId: string | null;
+  displayPath: string;
+}
+
+/** Native export target selection and binary file writing. */
+export interface DocBlocksHostExportAPI {
+  /** Resolve an exact remembered grant or a display-only host suggestion. */
+  resolveTarget(documentId: string, filename: string): Promise<HostExportTargetGrant>;
+  /** Open the native Save dialog and remember the selected target. */
+  pickTarget(
+    documentId: string,
+    filename: string,
+    currentGrantId?: string | null,
+  ): Promise<HostExportTargetGrant | null>;
+  /** Write only to an exact target granted by the main process. */
+  save(
+    documentId: string,
+    filename: string,
+    grantId: string | null,
+    data: ArrayBuffer | Uint8Array,
+  ): Promise<HostExportTargetGrant | null>;
+}
+
 /** System ffmpeg detection and invocation. */
 export interface DocBlocksHostFfmpegAPI {
   /** True if `ffmpeg` is available on PATH (or bundled). */
   available(): Promise<boolean>;
   /** Version string from `ffmpeg -version`, or null if unavailable. */
   version(): Promise<string | null>;
-  /**
-   * Render a markdown file at the given absolute path to MP4 using the
-   * existing squisq-video CLI pipeline. Returns the absolute path to the
-   * produced MP4 file, or throws on failure.
-   */
+  /** Render a physically contained workspace-relative Markdown file to MP4. */
   renderVideo(
-    markdownAbsolutePath: string,
+    workspaceId: string,
+    markdownPath: string,
     options: { fps?: number; quality?: 'draft' | 'normal' | 'high' },
   ): Promise<string>;
 }
@@ -92,13 +125,15 @@ export interface DocBlocksHostUpdaterAPI {
    * Quit the app and apply a downloaded update. Should only be called
    * after an `UpdaterStatus` of kind `'downloaded'` has been observed.
    */
-  quitAndInstall(): Promise<void>;
+  quitAndInstall(): Promise<UpdateInstallResult>;
   /**
    * Subscribe to updater status events. Returns an unsubscribe function.
    */
   onStatus(listener: (status: UpdaterStatus) => void): () => void;
 }
 
+export type UpdateInstallResult = 'installing' | 'cancelled' | 'not-ready';
+
 export type UpdaterStatus =
   | { kind: 'checking' }
   | { kind: 'available'; version: string; releaseNotes?: string; releaseUrl?: string }
@@ -113,18 +148,66 @@ export type MenuCommand =
   | 'file:openFolder'
   | 'file:revealWorkspace'
   | 'file:settings'
+  | 'git:commit'
+  | 'git:push'
+  | 'git:pull'
+  | 'git:fetch'
+  | 'git:newBranch'
+  | 'git:switchBranch'
+  | 'git:history'
+  | 'git:clone'
+  | 'git:openOnRemote'
+  | 'git:createPullRequest'
   | 'help:about'
   | 'help:checkForUpdates'
   | 'help:viewOnGitHub';
 
-/** Deep-link event resolved by the host into a trusted workspace file. */
-export interface OpenRequest {
-  kind: 'workspace-file';
-  workspaceId: string;
-  /** Slash-prefixed path relative to the workspace root. */
-  path: string;
+/**
+ * OS open-file / deep-link event resolved by the host.
+ * - 'workspace-file': a file inside an already-registered workspace.
+ * - 'external-file': a loose markdown file outside any workspace — opened in a
+ *   transient workspace and saved through an opaque resource grant.
+ * - 'external-bundle': a `.dbk`/zip bundle — unpacked into a transient
+ *   workspace and re-zipped through an opaque resource grant on save.
+ */
+export type OpenRequest =
+  | {
+      kind: 'workspace-file';
+      workspaceId: string;
+      /** Slash-prefixed path relative to the workspace root. */
+      path: string;
+    }
+  | { kind: 'external-file'; resourceId: string; name: string }
+  | { kind: 'external-bundle'; resourceId: string; name: string };
+
+/**
+ * Read/write access to individual OS files the user has explicitly opened
+ * (via "Open With" / deep link), outside the workspace-root whitelist. The
+ * main process gates these with owner-scoped, exact-file capabilities.
+ */
+export interface DocBlocksHostExternalAPI {
+  readText(resourceId: string): Promise<string | null>;
+  readBinary(resourceId: string): Promise<ArrayBuffer | null>;
+  writeText(resourceId: string, content: string): Promise<void>;
+  writeBinary(resourceId: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+  commitText(
+    resourceId: string,
+    content: string,
+    expectedContent: string | null,
+  ): Promise<FileCommitResult>;
+  commitBinary(
+    resourceId: string,
+    data: ArrayBuffer | Uint8Array,
+    expectedVersion: string | null,
+  ): Promise<ExternalBinaryCommitResult>;
+  /** Revoke one external resource when its transient document is closed. */
+  revoke(resourceId: string): Promise<void>;
 }
 
+export type ExternalBinaryCommitResult =
+  | { status: 'committed'; version: string }
+  | { status: 'conflict'; version: string | null; data: ArrayBuffer | null };
+
 /** Environment metadata provided by the host. */
 export interface HostEnvironment {
   platform: 'darwin' | 'win32' | 'linux';
@@ -132,14 +215,52 @@ export interface HostEnvironment {
   isDev: boolean;
 }
 
+export type HostCloseReason =
+  | 'window-close'
+  | 'app-quit'
+  | 'update-install'
+  | 'reload'
+  | 'force-reload';
+
+export interface HostPrepareCloseRequest {
+  requestId: string;
+  reason: HostCloseReason;
+  /** Absolute epoch-millisecond deadline chosen by the main process. */
+  deadline: number;
+}
+
+export type HostPrepareCloseResult =
+  | { status: 'ready'; persistedRevision: number }
+  | {
+      status: 'blocked';
+      code: 'save-failed' | 'external-conflict' | 'not-ready';
+      message: string;
+    };
+
+/**
+ * Main-owned close handshake. Preload privately correlates replies; the
+ * renderer never chooses request or window identifiers.
+ */
+export interface DocBlocksHostLifecycleAPI {
+  onPrepareClose(
+    listener: (request: HostPrepareCloseRequest) => Promise<HostPrepareCloseResult>,
+  ): () => void;
+  onCancelClose(listener: (requestId: string) => void): () => void;
+}
+
 /** The full DocBlocks desktop host API. */
 export interface DocBlocksHostAPI {
   env: HostEnvironment;
   fs: DocBlocksHostFsAPI;
+  fsV2: DocBlocksHostFsV2API;
+  external: DocBlocksHostExternalAPI;
   workspaces: DocBlocksHostWorkspacesAPI;
   shell: DocBlocksHostShellAPI;
+  exports: DocBlocksHostExportAPI;
   ffmpeg: DocBlocksHostFfmpegAPI;
+  git: DocBlocksHostGitAPI;
   updater: DocBlocksHostUpdaterAPI;
+  lifecycle: DocBlocksHostLifecycleAPI;
   /**
    * Subscribe to menu commands dispatched by the native menu.
    * Returns an unsubscribe function.

package/src/host/wire-policy.ts

@@ -0,0 +1,103 @@
+import type { OpenRequest } from './types.js';
+
+/** Quantitative limits shared by privileged host boundaries. */
+export const HOST_WIRE_LIMITS = Object.freeze({
+  identifierCharacters: 256,
+  labelCharacters: 1_024,
+  pathCharacters: 4_096,
+  urlCharacters: 8_192,
+  messageCharacters: 2_000,
+  documentCharacters: 20 * 1024 * 1024,
+  binaryBytes: 100 * 1024 * 1024,
+  base64Characters: 140 * 1024 * 1024,
+  arrayEntries: 10_000,
+});
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value);
+  return (
+    actual.length === keys.length &&
+    keys.every((key) => Object.prototype.hasOwnProperty.call(value, key))
+  );
+}
+
+export function isBoundedString(
+  value: unknown,
+  maximumCharacters: number,
+  minimumCharacters = 0,
+): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length >= minimumCharacters &&
+    value.length <= maximumCharacters &&
+    !value.includes('\0')
+  );
+}
+
+export function isBoundedBytePayload(
+  value: unknown,
+  maximumBytes = HOST_WIRE_LIMITS.binaryBytes,
+): value is ArrayBuffer | Uint8Array {
+  return (
+    (value instanceof ArrayBuffer || value instanceof Uint8Array) &&
+    value.byteLength <= maximumBytes
+  );
+}
+
+/** Parse one exact, bounded main-to-renderer open request. */
+export function parseOpenRequest(value: unknown): OpenRequest | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+
+  if (record.kind === 'workspace-file') {
+    if (!hasExactKeys(record, ['kind', 'workspaceId', 'path'])) return null;
+    if (!isBoundedString(record.workspaceId, HOST_WIRE_LIMITS.identifierCharacters, 1)) return null;
+    if (!isBoundedString(record.path, HOST_WIRE_LIMITS.pathCharacters, 1)) return null;
+    return { kind: 'workspace-file', workspaceId: record.workspaceId, path: record.path };
+  }
+
+  if (record.kind === 'external-file' || record.kind === 'external-bundle') {
+    if (!hasExactKeys(record, ['kind', 'resourceId', 'name'])) return null;
+    if (!isBoundedString(record.resourceId, HOST_WIRE_LIMITS.identifierCharacters, 1)) return null;
+    if (!isBoundedString(record.name, HOST_WIRE_LIMITS.labelCharacters, 1)) return null;
+    return { kind: record.kind, resourceId: record.resourceId, name: record.name };
+  }
+
+  return null;
+}
+
+/** Return one canonical HTTP(S) URL, or null when external navigation is unsafe. */
+export function parseExternalHttpUrl(value: unknown): string | null {
+  if (!isBoundedString(value, HOST_WIRE_LIMITS.urlCharacters, 1)) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+    if (url.username || url.password) return null;
+    const canonical = url.href;
+    return canonical.length <= HOST_WIRE_LIMITS.urlCharacters ? canonical : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True only for the packaged renderer origin or the exact configured dev origin. */
+export function isTrustedRendererUrl(value: unknown, developmentOrigin?: string): boolean {
+  if (!isBoundedString(value, HOST_WIRE_LIMITS.urlCharacters, 1)) return false;
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol === 'app:' &&
+      url.hostname === 'docblocks' &&
+      url.port === '' &&
+      url.username === '' &&
+      url.password === ''
+    ) {
+      return true;
+    }
+    if (!developmentOrigin) return false;
+    const trustedDevelopmentOrigin = new URL(developmentOrigin);
+    return url.origin === trustedDevelopmentOrigin.origin;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -1,9 +1,10 @@
 /**
  * @bendyline/docblocks — Core package
  *
- * Re-exports filesystem, workspace, and host modules for convenience.
+ * Re-exports filesystem, document, workspace, and host modules for convenience.
  */
 
 export * from './filesystem/index.js';
+export * from './document/index.js';
 export * from './workspace/index.js';
 export * from './host/index.js';

package/src/mcp/index.ts

@@ -0,0 +1,3 @@
+/** Exact, bounded wire contracts shared by DocBlocks MCP implementations. */
+export * from './types.js';
+export * from './wire.js';