@oh-my-pi/pi-natives 18.3.0 → 18.3.1

package/THIRD-PARTY-NOTICES.txt

@@ -78,8 +78,8 @@ below.
 uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
-b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cut,
-date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
+b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
 printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
 truncate, uname, uniq, wc, whoami, yes.
 

package/native/index.d.ts

@@ -103,8 +103,10 @@ export declare class EditSession {
   /**
    * Open a session. `onPreview` (optional) receives every settled preview
    * batch; batches are delivered one at a time, in generation order.
+   * `resolveUrl` (optional) maps an internal URL target to its backing
+   * file; without it such targets fail as unresolved.
    */
-  constructor(store: EditStore, policy: EditPolicy, onPreview?: ((error: Error | null, batch: EditPreviewBatch) => void) | undefined | null)
+  constructor(store: EditStore, policy: EditPolicy, onPreview?: ((error: Error | null, batch: EditPreviewBatch) => void) | undefined | null, resolveUrl?: ((error: Error | null, url: string) => Promise<EditUrlResolution>) | undefined | null)
   /** Append a raw streamed argument fragment. */
   push(delta: string): void
   /** Replace the buffer with the complete argument JSON (no-delta path). */
@@ -648,7 +650,7 @@ export declare function __ompInstallTokioRuntime(): void
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV18_3_0(): void
+export declare function __piNativesV18_3_1(): void
 
 /**
  * Reports whether the on-device model can generate, as an `availability`
@@ -704,7 +706,10 @@ export interface AstFindOptions {
   patterns?: Array<string>
   /** Language override; otherwise inferred from file extension per candidate. */
   lang?: string
-  /** Single file or directory to scan (combined with `glob` when set). */
+  /**
+   * Single file or directory to scan (combined with `glob` when set): a
+   * host path or an absolute `scheme://` URL.
+   */
   path?: string
   /** Optional glob filter relative to the search root. */
   glob?: string
@@ -727,6 +732,11 @@ export interface AstFindOptions {
   signal?: unknown
   /** Wall-clock timeout for the worker task in milliseconds. */
   timeoutMs?: number
+  /**
+   * Filesystem candidates are resolved, walked, and read through (native
+   * when absent).
+   */
+  filesystem?: ShellFilesystem
 }
 
 /** Aggregated search statistics and any parse or compile diagnostics. */
@@ -867,7 +877,10 @@ export interface AstReplaceOptions {
    * mixed-language paths rewrite each file in its own language.
    */
   lang?: string
-  /** Single file or directory to rewrite. */
+  /**
+   * Single file or directory to rewrite: a host path or an absolute
+   * `scheme://` URL.
+   */
   path?: string
   /** Optional glob filter within the search root. */
   glob?: string
@@ -887,6 +900,11 @@ export interface AstReplaceOptions {
   signal?: unknown
   /** Wall-clock timeout for the worker task in milliseconds. */
   timeoutMs?: number
+  /**
+   * Filesystem candidates are resolved, walked, read, and written through
+   * (native when absent).
+   */
+  filesystem?: ShellFilesystem
 }
 
 /** Summary of an ast-grep rewrite pass, including whether disk writes occurred. */
@@ -1355,10 +1373,15 @@ export interface EditPolicy {
   enforceSeenLines: boolean
   blockAutoGenerated: boolean
   planActive: boolean
-  /** Root of the `local://` artifact sandbox; null when the session has none. */
-  localSandboxRoot?: string
-  /** Cached vault roots; null when the vault protocol is disabled. */
-  vaultRoots?: Array<EditVaultRoot>
+  /** Registered internal URL schemes (router spec keys). */
+  urlSchemes: Array<string>
+  /**
+   * The `urlSchemes` whose single-slash `scheme:/x` spelling aliases
+   * `scheme://x` (spec `singleSlashAlias`).
+   */
+  urlAliasSchemes: Array<string>
+  /** Plain-path roots writable in plan mode. */
+  planWritableRoots: Array<string>
   homeDir: string
   /** The payload is a verbatim custom-format string, not JSON. */
   rawInput: boolean
@@ -1373,11 +1396,14 @@ export interface EditPreviewBatch {
   files: Array<EditFilePreview>
 }
 
-/** A cached `vault://` root. */
-export interface EditVaultRoot {
-  /** Vault name; `_` is the active vault. */
-  name: string
-  root: string
+/** Host answer for one internal URL (`resolveUrl`). */
+export interface EditUrlResolution {
+  /** Absolute backing file; null when no local file backs the URL. */
+  path?: string
+  /** Model-facing refusal (read-only, disabled…); wins over `path`. */
+  error?: string
+  /** Writable while plan mode is active (sandbox-scoped scheme). */
+  planWritable: boolean
 }
 
 /** Host write request; the host owns the bytes. */
@@ -1619,7 +1645,7 @@ export interface GlobMatch {
 export interface GlobOptions {
   /** Glob pattern to match (e.g., "*.ts"). */
   pattern: string
-  /** Directory to search. */
+  /** Directory to search: a host path or an absolute `scheme://` URL. */
   path: string
   /**
    * Filter by file type: "file", "dir", or "symlink". Symlinks are
@@ -1647,6 +1673,11 @@ export interface GlobOptions {
   signal?: unknown
   /** Timeout in milliseconds for the operation. */
   timeoutMs?: number
+  /**
+   * Filesystem the search root is resolved and walked through (native when
+   * absent).
+   */
+  filesystem?: ShellFilesystem
 }
 
 /** Result payload returned by a glob operation. */
@@ -1691,7 +1722,7 @@ export interface GrepMatch {
 export interface GrepOptions {
   /** Regex pattern to search for. */
   pattern: string
-  /** Directory or file to search. */
+  /** Directory or file to search: a host path or an absolute `scheme://` URL. */
   path: string
   /** Glob filter for filenames (e.g., "*.ts"). */
   glob?: string
@@ -1729,6 +1760,11 @@ export interface GrepOptions {
   signal?: unknown
   /** Timeout in milliseconds for the operation. */
   timeoutMs?: number
+  /**
+   * Filesystem every path is stat'ed, walked, and read through (native when
+   * absent).
+   */
+  filesystem?: ShellFilesystem
 }
 
 /** Output mode for [`search`] and [`grep`] (string values match JS callers). */
@@ -2586,6 +2622,325 @@ export interface ShellExecuteOptions {
   minimizer?: MinimizerOptions
   /** Abort signal for cancelling the operation. */
   signal?: unknown
+  /** Filesystem backing the command (native when absent). */
+  filesystem?: ShellFilesystem
+}
+
+/** Host filesystem injected into shell sessions. */
+export interface ShellFilesystem {
+  /**
+   * Services every routed operation; failures are returned as `error`
+   * data rather than thrown.
+   */
+  handler: (error: Error | null, request: ShellFsRequest) => Promise<ShellFsResponse>
+  /**
+   * When true, every path without a `scheme://` prefix — and everything
+   * beneath it — is the ordinary host filesystem: operations there run
+   * natively (including recursive traversal and removal) and `handler` is
+   * never consulted, so it cannot intercept any host subtree. Only URL
+   * paths reach `handler`. When false or absent, `handler` is a fully
+   * injected filesystem and receives every path, host paths included.
+   */
+  nativeLocalPaths?: boolean
+}
+
+/** Permissions probed by an `access` request. */
+export interface ShellFsAccess {
+  read: boolean
+  write: boolean
+  execute: boolean
+}
+
+/** One directory entry. */
+export interface ShellFsDirEntry {
+  name: string
+  fileType: ShellFsFileType
+  /** Entry metadata without following a final symlink, when already known. */
+  metadata?: ShellFsMetadata
+}
+
+/** A failed operation, reported as data so its errno identity survives. */
+export interface ShellFsError {
+  /** Errno name such as `ENOENT`, `EACCES`, `EROFS`, `ENOTSUP`. */
+  code: string
+  message?: string
+}
+
+/** File type on the filesystem wire. */
+export declare enum ShellFsFileType {
+  /** Regular file. */
+  File = 'file',
+  /** Directory. */
+  Dir = 'dir',
+  /** Symbolic link. */
+  Symlink = 'symlink',
+  /** Named pipe. */
+  Fifo = 'fifo',
+  /** Unix domain socket. */
+  Socket = 'socket',
+  /** Character device. */
+  Char = 'char',
+  /** Block device. */
+  Block = 'block'
+}
+
+/**
+ * File metadata. Absent optional fields mean the provider has no such value;
+ * they are never fabricated.
+ */
+export interface ShellFsMetadata {
+  fileType: ShellFsFileType
+  size: number | bigint
+  /** Permission bits (`0o7777`). */
+  mode: number
+  /** Modification time, nanoseconds since the Unix epoch. */
+  mtimeNs?: number | bigint
+  /** Access time, nanoseconds since the Unix epoch. */
+  atimeNs?: number | bigint
+  /** Status change time, nanoseconds since the Unix epoch. */
+  ctimeNs?: number | bigint
+  /** Creation time, nanoseconds since the Unix epoch. */
+  birthtimeNs?: number | bigint
+  /** Device id; given together with `ino`. */
+  dev?: number | bigint
+  /** Inode number; given together with `dev`. */
+  ino?: number | bigint
+  nlink?: number | bigint
+  rdev?: number | bigint
+  /** Allocated 512-byte blocks; given together with `blksize`. */
+  blocks?: number | bigint
+  /** Preferred I/O block size; given together with `blocks`. */
+  blksize?: number | bigint
+  /** Owner user id; given together with `gid`. */
+  uid?: number
+  /** Owner group id; given together with `uid`. */
+  gid?: number
+}
+
+/** Which path components `canonicalize` requires to exist. */
+export declare enum ShellFsMissing {
+  /** Every component must exist (`realpath`). */
+  Existing = 'existing',
+  /** Every component but the last must exist. */
+  Normal = 'normal',
+  /** No component needs to exist. */
+  Missing = 'missing'
+}
+
+/** Filesystem operation requested from a host [`ShellFilesystem`]. */
+export declare enum ShellFsOp {
+  /** Metadata of `path`, following symlinks. Answer: `metadata`. */
+  Metadata = 'metadata',
+  /**
+   * Metadata of `path` itself, not following a final symlink. Answer:
+   * `metadata`.
+   */
+  SymlinkMetadata = 'symlinkMetadata',
+  /** Entries of directory `path`. Answer: `entries`. */
+  ReadDir = 'readDir',
+  /** Canonical spelling of `path` per `missing`/`resolve`. Answer: `path`. */
+  Canonicalize = 'canonicalize',
+  /**
+   * Host file or directory backing `path`, for user-facing commands that
+   * print real locations (`realpath`, `readlink -f`). Answer: `path`, or
+   * no `path` when nothing on the host backs it. Grants no access.
+   */
+  BackingPath = 'backingPath',
+  /** Contents of symlink `path`. Answer: `path`. */
+  ReadLink = 'readLink',
+  /** Check `access` permissions on `path` (all false: existence). */
+  Access = 'access',
+  /** Open `path` with `open` flags. Answer: `handle`. */
+  Open = 'open',
+  /**
+   * Read up to `length` bytes of `handle` at `offset`. Answer: `data`
+   * (empty at end of file).
+   */
+  Read = 'read',
+  /**
+   * Write `data` to `handle` at `offset`, or at the end when `offset` is
+   * absent (append handles). Answer: `written`, plus `offset` (end
+   * position after the write) for appends.
+   */
+  Write = 'write',
+  /** Flush buffered writes of `handle`. */
+  Flush = 'flush',
+  /** Release `handle`. Sent exactly once per opened handle. */
+  Close = 'close',
+  /** Metadata of the file behind `handle`. Answer: `metadata`. */
+  FileMetadata = 'fileMetadata',
+  /**
+   * Query whether `handle` has a conflicting advisory write lock. Answer:
+   * `locked`.
+   */
+  IsLocked = 'isLocked',
+  /** Truncate or extend `handle` to `size` bytes. */
+  SetLen = 'setLen',
+  /** Set times of `handle` (`atimeNs`/`mtimeNs`; absent = unchanged). */
+  FileSetTimes = 'fileSetTimes',
+  /** Set permission bits `mode` of `handle`. */
+  FileSetPermissions = 'fileSetPermissions',
+  /** Persist `handle` (`dataOnly`: data without metadata). */
+  Sync = 'sync',
+  /** Create directory `path` (`recursive`, optional `mode`). */
+  CreateDir = 'createDir',
+  /** Remove non-directory `path`. */
+  RemoveFile = 'removeFile',
+  /** Remove empty directory `path`. */
+  RemoveDir = 'removeDir',
+  /** Remove directory `path` and everything below it. */
+  RemoveDirAll = 'removeDirAll',
+  /** Rename `path` to `target`. */
+  Rename = 'rename',
+  /** Create hard link `target` to existing `path`. */
+  HardLink = 'hardLink',
+  /** Create symlink `path` whose contents are `target` (verbatim). */
+  Symlink = 'symlink',
+  /** Set permission bits `mode` of `path` (following symlinks). */
+  SetPermissions = 'setPermissions',
+  /**
+   * Set times of `path` (`atimeNs`/`mtimeNs`; absent = unchanged;
+   * `follow`).
+   */
+  SetTimes = 'setTimes',
+  /** Change owner `uid`/`gid` of `path` (absent = unchanged; `follow`). */
+  Chown = 'chown',
+  /** Statistics of the filesystem holding `path`. Answer: `statFs`. */
+  StatFs = 'statFs',
+  /**
+   * Extended attribute `name` of `path`. Answer: `data`, or no `data`
+   * when the attribute is absent.
+   */
+  GetXattr = 'getXattr',
+  /** Set extended attribute `name` of `path` to `data`. */
+  SetXattr = 'setXattr',
+  /** Extended attribute names of `path`. Answer: `names`. */
+  ListXattr = 'listXattr',
+  /** Remove extended attribute `name` of `path`. */
+  RemoveXattr = 'removeXattr',
+  /**
+   * Create node `path` of `fileType` with `mode` (and `device` for
+   * character/block devices).
+   */
+  Mknod = 'mknod'
+}
+
+/** Open flags for an `open` request (std `OpenOptions` semantics). */
+export interface ShellFsOpenFlags {
+  read: boolean
+  write: boolean
+  append: boolean
+  truncate: boolean
+  create: boolean
+  createNew: boolean
+  /** Permission bits for a newly created file. */
+  mode?: number
+  /** Platform open flags beyond the portable set (`O_*`); absent when none. */
+  customFlags?: number
+}
+
+/** One filesystem request. Only the fields documented for `op` are set. */
+export interface ShellFsRequest {
+  op: ShellFsOp
+  /** Subject path, verbatim (URL spellings keep their authority). */
+  path?: string
+  /** Second path: rename/hard-link destination or symlink contents. */
+  target?: string
+  /** Provider handle id from a previous `open`. */
+  handle?: number
+  /** Byte offset for positional handle I/O. */
+  offset?: bigint
+  /** Maximum bytes to read. */
+  length?: number
+  /** New length for `setLen`. */
+  size?: bigint
+  /** Bytes to write (`write`) or attribute value (`setXattr`). */
+  data?: Buffer
+  open?: ShellFsOpenFlags
+  access?: ShellFsAccess
+  recursive?: boolean
+  /** Permission bits (`0o7777`). */
+  mode?: number
+  /** Whether a final symlink is followed. */
+  follow?: boolean
+  /** Access time in nanoseconds since the Unix epoch. */
+  atimeNs?: bigint
+  /** Modification time in nanoseconds since the Unix epoch. */
+  mtimeNs?: bigint
+  uid?: number
+  gid?: number
+  /** `sync` persists data only, not metadata. */
+  dataOnly?: boolean
+  /** Extended attribute name. */
+  name?: string
+  /** Node type for `mknod`. */
+  fileType?: ShellFsFileType
+  /** Device number for character/block `mknod`. */
+  device?: bigint
+  missing?: ShellFsMissing
+  resolve?: ShellFsResolve
+  /**
+   * Removal of temporary files the shell itself created, issued even after
+   * the run was aborted. Serve it under the same policy, but without the
+   * run's abort signal. Not a retry of a cancelled request.
+   */
+  cleanup?: boolean
+}
+
+/** How `canonicalize` treats symlinks. */
+export declare enum ShellFsResolve {
+  /** Resolve symlinks as encountered. */
+  Physical = 'physical',
+  /** Apply `..` lexically before resolving symlinks. */
+  Logical = 'logical',
+  /** Never resolve symlinks; normalize lexically only. */
+  None = 'none'
+}
+
+/**
+ * Provider answer. Carries `error`, a native redirect (`local` /
+ * `localTarget`), or the op's result fields.
+ */
+export interface ShellFsResponse {
+  error?: ShellFsError
+  /** Run this operation natively on this host path instead. */
+  local?: string
+  /** Native host path replacing `target` (rename/hard-link destination). */
+  localTarget?: string
+  handle?: number
+  /**
+   * With an `open` redirect: the host file backs an immutable mount, so
+   * the opened file refuses every mutation (EROFS), duplicates included.
+   */
+  readonly?: boolean
+  data?: Uint8Array
+  written?: number
+  /** Result of an `isLocked` advisory-lock query. */
+  locked?: boolean
+  /** Handle position after an append write. */
+  offset?: number | bigint
+  path?: string
+  metadata?: ShellFsMetadata
+  entries?: Array<ShellFsDirEntry>
+  names?: Array<string>
+  statFs?: ShellFsStatFs
+}
+
+/** Filesystem statistics. */
+export interface ShellFsStatFs {
+  blockSize: number | bigint
+  /** Optimal transfer size; defaults to `blockSize`. */
+  ioSize?: number | bigint
+  blocks: number | bigint
+  blocksFree: number | bigint
+  blocksAvailable: number | bigint
+  files: number | bigint
+  filesFree: number | bigint
+  /** Filesystem type magic number. */
+  fsType?: number | bigint
+  fsTypeName?: string
+  fsid?: number | bigint
+  nameMax?: number | bigint
 }
 
 /** Options for configuring a persistent shell session. */
@@ -2596,6 +2951,8 @@ export interface ShellOptions {
   snapshotPath?: string
   /** Optional per-command output minimizer configuration. */
   minimizer?: MinimizerOptions
+  /** Filesystem backing every run of this session (native when absent). */
+  filesystem?: ShellFilesystem
 }
 
 /** Options for running a shell command. */
@@ -2610,6 +2967,11 @@ export interface ShellRunOptions {
   timeoutMs?: number
   /** Abort signal for cancelling the operation. */
   signal?: unknown
+  /**
+   * Filesystem for this run only, replacing the session's; the session's
+   * filesystem applies again to later runs.
+   */
+  filesystem?: ShellFilesystem
 }
 
 /** Result of running a shell command. */

package/native/index.js

@@ -45,7 +45,7 @@ export const VcsRepo = nativeBindings.VcsRepo;
 
 // functions
 export const __ompInstallTokioRuntime = nativeBindings.__ompInstallTokioRuntime ?? missingNativeExport("__ompInstallTokioRuntime");
-export const __piNativesV18_3_0 = nativeBindings.__piNativesV18_3_0;
+export const __piNativesV18_3_1 = nativeBindings.__piNativesV18_3_1;
 export const appleFmAvailability = nativeBindings.appleFmAvailability ?? missingNativeExport("appleFmAvailability");
 export const appleFmCancel = nativeBindings.appleFmCancel ?? missingNativeExport("appleFmCancel");
 export const appleFmGenerate = nativeBindings.appleFmGenerate ?? missingNativeExport("appleFmGenerate");
@@ -206,4 +206,59 @@ export const ProcessStatus = {
 	Running: "running",
 	Exited: "exited",
 };
+export const ShellFsFileType = {
+	File: "file",
+	Dir: "dir",
+	Symlink: "symlink",
+	Fifo: "fifo",
+	Socket: "socket",
+	Char: "char",
+	Block: "block",
+};
+export const ShellFsMissing = {
+	Existing: "existing",
+	Normal: "normal",
+	Missing: "missing",
+};
+export const ShellFsOp = {
+	Metadata: "metadata",
+	SymlinkMetadata: "symlinkMetadata",
+	ReadDir: "readDir",
+	Canonicalize: "canonicalize",
+	BackingPath: "backingPath",
+	ReadLink: "readLink",
+	Access: "access",
+	Open: "open",
+	Read: "read",
+	Write: "write",
+	Flush: "flush",
+	Close: "close",
+	FileMetadata: "fileMetadata",
+	IsLocked: "isLocked",
+	SetLen: "setLen",
+	FileSetTimes: "fileSetTimes",
+	FileSetPermissions: "fileSetPermissions",
+	Sync: "sync",
+	CreateDir: "createDir",
+	RemoveFile: "removeFile",
+	RemoveDir: "removeDir",
+	RemoveDirAll: "removeDirAll",
+	Rename: "rename",
+	HardLink: "hardLink",
+	Symlink: "symlink",
+	SetPermissions: "setPermissions",
+	SetTimes: "setTimes",
+	Chown: "chown",
+	StatFs: "statFs",
+	GetXattr: "getXattr",
+	SetXattr: "setXattr",
+	ListXattr: "listXattr",
+	RemoveXattr: "removeXattr",
+	Mknod: "mknod",
+};
+export const ShellFsResolve = {
+	Physical: "physical",
+	Logical: "logical",
+	None: "none",
+};
 // --- end generated native exports ---

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "18.3.0",
+	"version": "18.3.1",
 	"description": "Native Rust bindings for PDF conversion, audio, WebRTC, grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://omp.sh",
@@ -107,11 +107,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@oh-my-pi/pi-natives-linux-x64": "18.3.0",
-		"@oh-my-pi/pi-natives-linux-arm64": "18.3.0",
-		"@oh-my-pi/pi-natives-darwin-x64": "18.3.0",
-		"@oh-my-pi/pi-natives-darwin-arm64": "18.3.0",
-		"@oh-my-pi/pi-natives-win32-x64": "18.3.0",
-		"@oh-my-pi/pi-natives-win32-arm64": "18.3.0"
+		"@oh-my-pi/pi-natives-linux-x64": "18.3.1",
+		"@oh-my-pi/pi-natives-linux-arm64": "18.3.1",
+		"@oh-my-pi/pi-natives-darwin-x64": "18.3.1",
+		"@oh-my-pi/pi-natives-darwin-arm64": "18.3.1",
+		"@oh-my-pi/pi-natives-win32-x64": "18.3.1",
+		"@oh-my-pi/pi-natives-win32-arm64": "18.3.1"
 	}
 }