@punica/editor 1.0.6 → 1.0.8

package/types/punica.module.runtime.datasets.d.ts

@@ -0,0 +1,234 @@
+declare module 'punica' {
+  export namespace runtime {
+    export namespace datasets {
+      /**
+       * Dataset provider identifier (e.g., "kaggle", "huggingface", "local", "s3").
+       */
+      export type DatasetProviderId = string;
+
+      /**
+       * Reference to a dataset in a specific provider.
+       */
+      export interface DatasetRef {
+        /**
+         * Provider identifier (e.g., "kaggle", "huggingface", "local", "s3").
+         */
+        provider: DatasetProviderId;
+        /**
+         * Dataset identifier within the provider (dataset slug, path, URI, etc.).
+         */
+        id: string;
+        /**
+         * Optional revision/version identifier.
+         * - HuggingFace: git SHA/tag
+         * - S3: versionId
+         * - Kaggle: version
+         * - Local: hash
+         */
+        revision?: string;
+        /**
+         * Optional format hint for the dataset.
+         */
+        format?: 'files' | 'table' | 'parquet' | 'image' | 'audio' | 'video';
+      }
+
+      /**
+       * Metadata about a dataset.
+       */
+      export interface DatasetMetadata {
+        /**
+         * Reference to the dataset.
+         */
+        ref: DatasetRef;
+        /**
+         * Human-readable name.
+         */
+        name: string;
+        /**
+         * Optional description.
+         */
+        description?: string;
+        /**
+         * Optional tags for categorization.
+         */
+        tags?: string[];
+        /**
+         * Optional license information.
+         */
+        license?: string;
+        /**
+         * Optional statistics about the dataset.
+         */
+        stats?: {
+          bytes?: number;
+          files?: number;
+          rows?: number;
+          columns?: number;
+        };
+        /**
+         * Optional schema information.
+         */
+        schema?: {
+          kind: 'table' | 'files';
+          columns?: Array<{
+            name: string;
+            dtype: string;
+            nullable?: boolean;
+          }>;
+        };
+      }
+
+      /**
+       * A mounted dataset that is accessible via a canonical URI.
+       */
+      export interface MountedDataset {
+        /**
+         * Reference to the dataset.
+         */
+        ref: DatasetRef;
+        /**
+         * Canonical URI for accessing the dataset in compute contexts.
+         * Format: "punica://dataset/{provider}/{id}"
+         */
+        uri: string;
+        /**
+         * Whether the dataset is mounted as read-only.
+         */
+        readOnly: boolean;
+        /**
+         * Optional expiration timestamp (ISO 8601).
+         */
+        expiresAt?: string;
+      }
+
+      /**
+       * Options for mounting a dataset.
+       */
+      export interface MountOptions {
+        /**
+         * Whether to mount as read-only (default: true).
+         */
+        readOnly?: boolean;
+      }
+
+      /**
+       * Options for listing datasets.
+       */
+      export interface ListOptions {
+        /**
+         * Optional search query.
+         */
+        query?: string;
+        /**
+         * Optional tags to filter by.
+         */
+        tags?: string[];
+      }
+
+      /**
+       * Dataset provider interface (implemented by extensions).
+       */
+      export interface DatasetProvider {
+        /**
+         * Unique provider identifier.
+         */
+        id: DatasetProviderId;
+        /**
+         * Resolve dataset metadata from a reference.
+         */
+        resolve(ref: DatasetRef): Promise<DatasetMetadata>;
+        /**
+         * Mount a dataset and return a canonical URI for access.
+         */
+        mount(ref: DatasetRef, opts?: MountOptions): Promise<MountedDataset>;
+        /**
+         * Unmount a dataset by URI.
+         */
+        unmount(uri: string): Promise<void>;
+        /**
+         * List available datasets from this provider.
+         */
+        list(opts?: ListOptions): Promise<DatasetMetadata[]>;
+      }
+
+      /**
+       * Registry for dataset providers.
+       */
+      export interface DatasetRegistry {
+        /**
+         * Register a dataset provider.
+         */
+        registerProvider(provider: DatasetProvider): void;
+        /**
+         * Get a provider by ID.
+         */
+        getProvider(id: DatasetProviderId): DatasetProvider | undefined;
+        /**
+         * List all registered providers.
+         */
+        listProviders(): DatasetProvider[];
+      }
+
+      /**
+       * Main datasets API surface.
+       */
+      export interface DatasetsApi {
+        /**
+         * Resolve dataset metadata from a reference.
+         */
+        resolve(ref: DatasetRef): Promise<DatasetMetadata>;
+        /**
+         * Mount a dataset and return a canonical URI for access.
+         */
+        mount(ref: DatasetRef, opts?: MountOptions): Promise<MountedDataset>;
+        /**
+         * Unmount a dataset by URI.
+         */
+        unmount(uri: string): Promise<void>;
+        /**
+         * List available datasets.
+         * If provider is specified, only lists from that provider.
+         * Otherwise, aggregates results from all providers.
+         */
+        list(opts?: {
+          provider?: DatasetProviderId;
+          query?: string;
+          tags?: string[];
+        }): Promise<DatasetMetadata[]>;
+        /**
+         * Registry for providers.
+         */
+        registry: DatasetRegistry;
+      }
+
+      /**
+       * Local storage format for workspace datasets.
+       * Used by LocalDatasetProvider for .punica/datasets.json
+       */
+      export interface LocalDatasetRecord {
+        id: string;
+        platform: string;
+        name: string;
+        identifier: string;
+        description?: string | null;
+        owner?: string | null;
+        size?: string | null;
+        fileTypes?: string[] | null;
+        url?: string | null;
+        filePaths?: string[] | null;
+        metadata?: any;
+        status?: string | null;
+        createdAt?: string | null;
+        updatedAt?: string | null;
+      }
+
+      /**
+       * Index file format for local datasets storage.
+       */
+      export interface LocalDatasetsIndexFile {
+        version?: number;
+        datasets?: LocalDatasetRecord[];
+      }
+    }
+  }
+}

package/types/punica.module.runtime.fs.d.ts

@@ -0,0 +1,385 @@
+declare module 'punica' {
+  export namespace runtime {
+    interface FileEntry {
+      path: string;
+      name: string;
+      isDirectory: boolean;
+      children?: FileEntry[];
+    }
+
+    /**
+     * Provider capability surface flags for `FileSystemProvider`. A
+     * provider advertises which features it supports; the substrate
+     * uses this set to decide what it can dispatch through a given
+     * provider (and to reject requests that require a feature the
+     * provider has not declared).
+     *
+     *  - 'streaming'         : opt-in chunked read/write for large files
+     *  - 'watch'             : path-scoped change notifications
+     *  - 'versioning'        : per-path history + time-travel reads
+     *  - 'encrypted-at-rest' : payloads stored encrypted by the host
+     *  - 'snapshot'          : whole-tree point-in-time copies
+     */
+    export type FileSystemProviderCapability =
+      | 'streaming'
+      | 'watch'
+      | 'versioning'
+      | 'encrypted-at-rest'
+      | 'snapshot';
+
+    /**
+     * Data classification used by the capability gateway's encryption
+     * routing. Sensitive payloads are only dispatched through a
+     * provider that advertises the `'encrypted-at-rest'` capability;
+     * if none is registered, the call is rejected at the gateway. The
+     * substrate never holds encryption keys — key management is host
+     * territory.
+     */
+    export type EncryptionRequirement = 'public' | 'internal' | 'sensitive';
+
+    /**
+     * Per-path metadata returned by `FileSystemProvider.stat`. All
+     * timestamps are milliseconds since epoch. `mode` follows the
+     * POSIX rwx triplet convention but is provider-defined and may
+     * be `undefined` on backends that do not expose it (HTTP,
+     * IndexedDB). `isSymlink` is provider-defined; in-memory and
+     * HTTP/Kubernetes shapes typically leave it false.
+     */
+    export interface FileStat {
+      size: number;
+      mtimeMs: number;
+      ctimeMs: number;
+      mode?: number;
+      isDirectory: boolean;
+      isSymlink: boolean;
+    }
+
+    /**
+     * Path-scoped change notification surfaced by an optional
+     * `FileSystemProvider.watch` subscription. Discriminated by
+     * `kind`; the `previousPath` payload only appears on `renamed`.
+     */
+    export type WatchEvent =
+      | { kind: 'created'; path: string; isDirectory: boolean }
+      | { kind: 'modified'; path: string }
+      | { kind: 'deleted'; path: string }
+      | { kind: 'renamed'; path: string; previousPath: string };
+
+    /**
+     * Snapshot of an in-flight `fs.migrate` run. Substrate ships
+     * this shape + the state machine; persistent storage of progress
+     * is host territory.
+     */
+    export interface FsMigrationProgress {
+      migrationId: string;
+      sourceProviderId: string;
+      targetProviderId: string;
+      position: number;
+      transferred: number;
+      remaining: number;
+      lastError?: string;
+      terminal: boolean;
+      pendingResume: boolean;
+    }
+
+    /**
+     * Metadata for a snapshot produced by `fs.snapshot`. The actual
+     * bytes are persisted by the host (substrate concern is the
+     * sozlesme + state machine, not storage).
+     */
+    export interface FsSnapshotMeta {
+      snapshotId: string;
+      providerId: string;
+      scope?: string;
+      createdAtMs: number;
+      bytes?: number;
+    }
+
+    /**
+     * Optional flags accepted by `FileSystemProvider.deleteFile`. The
+     * legacy FS contract was "missing file throws"; with
+     * `ifExists: true` callers can request idempotent delete without
+     * a wrapping try/catch. Other fields remain provider-defined.
+     */
+    export interface FileDeleteOptions {
+      ifExists?: boolean;
+    }
+
+    /**
+     * Optional flags accepted by `FileSystemProvider.mkdir`. Mirrors
+     * POSIX `mkdir -p`; when `recursive` is omitted the contract is
+     * provider-defined (in-memory + HTTP/Kubernetes shapes default
+     * to non-recursive create).
+     */
+    export interface MkdirOptions {
+      recursive?: boolean;
+    }
+
+    /**
+     * Optional flags accepted by `FileSystemProvider.list`. `recursive`
+     * walks descendants; the default is direct-children only.
+     * Substrate returns a flat array of `FileEntry` so callers can
+     * paginate on top — no nested `children` arrays in `list`
+     * responses (unlike `getFileTree`).
+     */
+    export interface ListOptions {
+      recursive?: boolean;
+    }
+
+    /**
+     * Per-version metadata returned by `FileSystemProvider.history`.
+     * One entry per write at a path; the substrate uses these to
+     * surface "what's in my history" timelines and to drive
+     * `readAtVersion(path, versionId)` time-travel reads.
+     *
+     * Content bytes are NOT carried here — the substrate keeps
+     * `history()` cheap so a thousand-version log fits in one
+     * response. Callers fetch content via `readAtVersion`.
+     */
+    export interface FileVersion {
+      /** Opaque, monotonic-per-path identifier. */
+      versionId: string;
+      /** Wall-clock timestamp this version was written. */
+      mtimeMs: number;
+      /** Content size in bytes (UTF-8 length proxy). */
+      sizeBytes: number;
+      /** Content hash at write time (FNV-1a 32-bit hex). */
+      hash: string;
+    }
+
+    /**
+     * Abstraction over the host filesystem / workspace. Implemented by the host
+     * (Electron, browser + HTTP, etc.) and exposed to extensions via
+     * `punica.Runtime.fs` (and thus `window.punica.Runtime.fs` in the browser).
+     */
+    /**
+     * Filesystem capability: basic file and folder operations for the current workspace.
+     *
+     * The interface grew along two axes during data plane / FS providers:
+     *  - the original 9 methods stayed required (existing hosts keep
+     *    working without changes);
+     *  - a `capabilities` set + optional methods (stat / exists /
+     *    copy / mkdir / chmod / symlink / watch) were added so hosts
+     *    can incrementally adopt richer surfaces while the substrate
+     *    gates dispatch based on declared capabilities.
+     *
+     * `cwd` is the workspace-root path that all relative paths are
+     * resolved against. The substrate canonicalizes against this root
+     * inside the path-traversal middleware (path-traversal guard); providers
+     * receive normalized paths and may treat them as opaque.
+     */
+    interface FileSystemProvider {
+      /**
+       * Set of capabilities this provider exposes. Substrate consults
+       * this to gate which dispatches the provider can serve (e.g.
+       * streaming reads only routed when 'streaming' is declared;
+       * sensitive writes only routed when 'encrypted-at-rest' is
+       * declared). Optional for backward compatibility with hosts
+       * that pre-date data plane / FS providers; absent ≡ empty set.
+       */
+      capabilities?: Set<FileSystemProviderCapability>;
+
+      /**
+       * Workspace root path. Optional and provider-defined. When
+       * supplied, the substrate canonicalizes incoming paths against
+       * this root (path-traversal guard) and rejects
+       * out-of-root targets. Legacy hosts may omit it; the
+       * substrate then falls back to the legacy "trust the path"
+       * behaviour.
+       */
+      cwd?: string;
+
+      /**
+       * Returns the full file tree for the current workspace root.
+       */
+      getFileTree(): Promise<FileEntry[]>;
+
+      /**
+       * Create a new folder at the given path.
+       */
+      createFolder(path: string): Promise<void>;
+
+      /**
+       * Delete a folder (and optionally its contents).
+       */
+      deleteFolder(path: string): Promise<void>;
+
+      /**
+       * Rename / move a folder from oldPath to newPath.
+       */
+      renameFolder(oldPath: string, newPath: string): Promise<void>;
+
+      /**
+       * Read a file's textual content.
+       */
+      readFile(path: string): Promise<string>;
+
+      /**
+       * Create a new file with the given textual content.
+       */
+      createFileWithContent(path: string, content: string): Promise<void>;
+
+      /**
+       * Update an existing file's textual content.
+       */
+      updateFileContent(path: string, content: string): Promise<void>;
+
+      /**
+       * Delete a file at the given path. By default a missing path
+       * throws; pass `{ ifExists: true }` for idempotent delete.
+       */
+      deleteFile(path: string, opts?: FileDeleteOptions): Promise<void>;
+
+      /**
+       * Rename / move a file from oldPath to newPath.
+       */
+      renameFile(oldPath: string, newPath: string): Promise<void>;
+
+      /**
+       * Per-path metadata (size, timestamps, mode, isDirectory).
+       * Optional: providers that omit this surface should not declare
+       * any capability that requires it. Throws when the path does
+       * not exist (no silent null).
+       */
+      stat?(path: string): Promise<FileStat>;
+
+      /**
+       * Existence probe that never throws. Returns true for files
+       * AND folders. Optional but recommended — callers presently
+       * try/catch readFile() as a workaround.
+       */
+      exists?(path: string): Promise<boolean>;
+
+      /**
+       * Copy a file or directory tree from src to dst. Optional —
+       * legacy hosts that only support rename (= move) should omit.
+       */
+      copy?(src: string, dst: string): Promise<void>;
+
+      /**
+       * Create a folder, optionally recursive (`mkdir -p`). When the
+       * target already exists, behaviour depends on `recursive`:
+       * non-recursive throws, recursive is a no-op.
+       */
+      mkdir?(path: string, opts?: MkdirOptions): Promise<void>;
+
+      /**
+       * Change the POSIX-style permission bits. Optional — most
+       * non-native backends (HTTP, IndexedDB) cannot honor this and
+       * should omit the method rather than silently no-op.
+       */
+      chmod?(path: string, mode: number): Promise<void>;
+
+      /**
+       * Create a symbolic link at `linkPath` pointing to `target`.
+       * Optional — non-native backends typically omit this.
+       */
+      symlink?(target: string, linkPath: string): Promise<void>;
+
+      /**
+       * Subscribe to change notifications under `path`. Returns an
+       * unsubscribe function. Optional — providers that omit this
+       * MUST NOT declare the `'watch'` capability flag. Implementation
+       * is host territory (chokidar / fs.watch / IndexedDB observer).
+       */
+      watch?(path: string, listener: (event: WatchEvent) => void): () => void;
+
+      /**
+       * List entries under `path`. With no args lists root entries;
+       * with a `path` lists its direct children; pass
+       * `{ recursive: true }` to walk descendants. Returns a flat
+       * array — unlike `getFileTree`, entries do NOT carry nested
+       * `children`. Callers paginate the array on the consumer side.
+       * Throws when the path does not exist or names a file.
+       */
+      list?(path?: string, opts?: ListOptions): Promise<FileEntry[]>;
+
+      /**
+       * Return the write history for `path`, oldest first. Optional
+       * surface gated by the `'versioning'` capability flag — a
+       * provider that does not declare `'versioning'` MUST throw
+       * when called. Substrate `fs.history` adapter rejects via
+       * the gateway before reaching the provider whenever the
+       * capability flag is absent.
+       */
+      history?(path: string): Promise<FileVersion[]>;
+
+      /**
+       * Read the contents `path` had at version `versionId` — the
+       * time-travel companion to `history`. Optional surface gated
+       * by the `'versioning'` capability flag. Throws when the
+       * version id is unknown for the path.
+       */
+      readAtVersion?(path: string, versionId: string): Promise<string>;
+    }
+
+    type FileMatchMode = 'extension' | 'mime' | 'glob';
+
+    interface FileMatch {
+      /**
+       * Matching strategy:
+       * - "extension": pattern is compared (case-insensitive) to the file's extension without dot, e.g. "ts", "png".
+       * - "mime": pattern is compared to a mime-type, e.g. "image/png" or "text/*".
+       * - "glob": simple glob pattern against the full path, e.g. `*.log`.
+       */
+      mode: FileMatchMode;
+      pattern: string;
+    }
+
+    interface FileOpenContext {
+      path: string;
+      mimeType?: string;
+      size?: number;
+    }
+
+    interface FileOpener {
+      /**
+       * Unique identifier for this opener within the runtime.
+       */
+      id: string;
+      /**
+       * Command id that will be executed when this opener is selected.
+       * The convention is that commands accept at least (path: string, content: string, ctx?: FileOpenContext).
+       */
+      command: string;
+      /**
+       * Matching rules for this opener. When omitted or empty, the opener is considered a "fallback" candidate.
+       */
+      matches?: FileMatch[];
+      /**
+       * Higher priority openers win when multiple candidates match the same file.
+       * Default is 0.
+       */
+      priority?: number;
+    }
+
+    interface ResolvedOpener {
+      opener: FileOpener;
+      command: string;
+    }
+
+    /**
+     * File opener registry capability: maps file types to commands.
+     */
+    interface FileOpenersApi {
+      /**
+       * Register or replace a file opener. If another opener with the same id already
+       * exists, it will be replaced.
+       */
+      register(opener: FileOpener): void;
+      /**
+       * Unregister a previously registered opener.
+       */
+      unregister(id: string): void;
+      /**
+       * Remove all registered openers.
+       */
+      clear(): void;
+      /**
+       * Resolve the most appropriate opener for the given file context.
+       * Returns null when no suitable opener is found.
+       */
+      resolve(ctx: FileOpenContext): ResolvedOpener | null;
+    }
+  }
+}