@punica/editor 1.11.2 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/index.d.ts

@@ -25,6 +25,7 @@
 /// <reference path="punica.module.extensions.settings.d.ts" />
 /// <reference path="punica.module.extensions.i18n.d.ts" />
 /// <reference path="punica.module.runtime.fs.d.ts" />
+/// <reference path="punica.module.runtime.fileOperations.d.ts" />
 /// <reference path="punica.module.runtime.search.d.ts" />
 /// <reference path="punica.module.runtime.vcs.d.ts" />
 /// <reference path="punica.module.runtime.workspace.d.ts" />

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

@@ -70,6 +70,12 @@ declare module 'punica' {
       lifecyclePhase?: LifecyclePhase;
       fs: FileSystemProvider;
       fileOpeners: FileOpenersApi;
+      /**
+       * Rename/move and delete, announced to the layers that key state by
+       * path (content tabs, editors). Prefer this over calling the
+       * equivalent `fs` methods directly.
+       */
+      fileOperations: FileOperationsApi;
       search: SearchApi;
       vcs: VcsApi;
       terminals: TerminalApi;

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

@@ -0,0 +1,141 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * A rename (or move — the same thing at the filesystem level) that is
+     * about to happen, or has just happened. Both paths are
+     * workspace-relative, the same shape `FileSystemProvider` takes.
+     */
+    export interface FileRenameEvent {
+      oldPath: string;
+      newPath: string;
+      isDirectory: boolean;
+    }
+
+    /** A delete that is about to happen, or has just happened. */
+    export interface FileDeleteEvent {
+      path: string;
+      isDirectory: boolean;
+    }
+
+    /**
+     * A `will*` hook's refusal. Returning this aborts the operation before
+     * the filesystem is touched; `reason` becomes the thrown error's message,
+     * so it is read by a human and should say what the user can do about it.
+     */
+    export interface ParticipantVeto {
+      veto: true;
+      reason?: string;
+    }
+
+    /**
+     * A layer that needs to know about — or object to — file operations.
+     *
+     * This exists because a path is an identity, not just an argument. The
+     * shell keys open content tabs by path, the code editor keys its Monaco
+     * instances by path, notebook controllers key their models by path. When
+     * a file is renamed underneath them they are all holding a key that no
+     * longer names anything, and the failure is silent: a save writes to the
+     * old name, or finds no editor and writes nothing at all.
+     *
+     * So the operation cannot just be `fs.renameFile`. It has to be a
+     * transaction the interested layers take part in:
+     *
+     *  - `will*` runs BEFORE the filesystem call and may veto (returning
+     *    `{ veto: true }` or throwing). Use it for "this must not happen
+     *    yet" — not for cleanup.
+     *  - `did*` runs AFTER the filesystem call succeeded, awaited and in
+     *    registration order. Use it to re-key state. A throwing `did*` hook
+     *    is logged and skipped; it does not fail the operation, because the
+     *    file has already moved and reporting failure would be a lie.
+     *
+     * Participants are host/shell territory. A headless boot registers none,
+     * and then an operation is exactly the filesystem call plus its event.
+     */
+    export interface FileOperationParticipant {
+      /** Stable id, used in logs and to make double-registration visible. */
+      id: string;
+      willRename?(
+        event: FileRenameEvent
+      ): Promise<void | ParticipantVeto> | void | ParticipantVeto;
+      didRename?(event: FileRenameEvent): Promise<void> | void;
+      willDelete?(
+        event: FileDeleteEvent
+      ): Promise<void | ParticipantVeto> | void | ParticipantVeto;
+      didDelete?(event: FileDeleteEvent): Promise<void> | void;
+    }
+
+    /** Options for `FileOperationsApi.rename`. */
+    export interface FileRenameOptions {
+      /**
+       * Whether the target is a directory. Callers that already know (the
+       * explorer reads it off its tree) should pass it; otherwise it is
+       * resolved via `fs.stat` and, on providers without `stat`, assumed to
+       * be a file.
+       */
+      isDirectory?: boolean;
+    }
+
+    /** Options for `FileOperationsApi.delete`. */
+    export interface FileDeleteOperationOptions {
+      isDirectory?: boolean;
+      /** Passed through to `FileSystemProvider.deleteFile` for idempotency. */
+      ifExists?: boolean;
+    }
+
+    /**
+     * The single seam every file mutation that changes a path should go
+     * through: rename/move and delete.
+     *
+     * `runtime.fs` stays the raw filesystem surface and is still the right
+     * call for reads and for content writes, where the path is unchanged and
+     * nobody's key breaks. Creating and deleting a path, or moving one, is
+     * different: it invalidates state held elsewhere in the app, and the
+     * whole point of routing it here is that the invalidation is announced
+     * instead of discovered.
+     *
+     * Two consumers, one code path: the explorer's context menu and an agent
+     * invoking the `file-explorer.rename` capability both land here, so tab
+     * state stays correct whether a human or a model moved the file.
+     *
+     * ## Dirty (unsaved) tracking
+     *
+     * `setDirty` / `isDirty` / `getDirtyPaths` are a working-copy registry.
+     * The shell mirrors its content tabs into it, which lets a caller ask
+     * "would deleting this lose unsaved work?" without knowing that content
+     * tabs exist — the explorer's delete confirmation reads it to say so in
+     * the dialog, in one prompt rather than two.
+     */
+    export interface FileOperationsApi {
+      /**
+       * Add a participant. Registering the same `id` twice replaces the
+       * first. Dispose to remove it — a shell that is torn down must not
+       * leave a hook pointing at dead state.
+       */
+      registerParticipant(participant: FileOperationParticipant): {
+        dispose(): void;
+      };
+
+      /** Record (or clear) unsaved-changes state for a path. */
+      setDirty(path: string, dirty: boolean): void;
+      isDirty(path: string): boolean;
+      /**
+       * Every path with unsaved changes; with `prefix`, only that path and
+       * its descendants (so a folder delete can name what it would lose).
+       */
+      getDirtyPaths(prefix?: string): string[];
+
+      /**
+       * Move `oldPath` to `newPath`, announcing it. Rejects if a participant
+       * vetoes or the filesystem call fails; in both cases nothing has moved.
+       */
+      rename(
+        oldPath: string,
+        newPath: string,
+        opts?: FileRenameOptions
+      ): Promise<void>;
+
+      /** Delete `path`, announcing it. Same failure contract as `rename`. */
+      delete(path: string, opts?: FileDeleteOperationOptions): Promise<void>;
+    }
+  }
+}

package/types/punica.module.shell.appBar.d.ts

@@ -55,11 +55,32 @@ declare module 'punica' {
         command?: string;
         menu?: AppBarMenuItem[];
         /**
-         * Command id returning a one-line summary rendered as the menu header
-         * (e.g. the licence state). Dropped when the command is not registered,
-         * which is how a host without the surface stays quiet.
+         * Command id returning the summary rendered as the menu header (e.g. the
+         * licence state, or who the app is licensed to). Dropped when the
+         * command is not registered, which is how a host without the surface
+         * stays quiet.
+         *
+         * A returned string may carry newlines, and each line is rendered as its
+         * own row with the first one emphasised — enough for a name over an
+         * address. Lines are clipped rather than wrapped, so a long address
+         * cannot widen the menu.
          */
         summaryCommand?: string;
+        /**
+         * Command id returning the avatar's glyph, at most two characters (a
+         * user's initials). Avatar items only.
+         *
+         * This exists because the glyph is identity and identity is not known
+         * when a profile is written: `label` is static, and a host cannot patch
+         * one item without re-declaring the whole thing, menu included. So the
+         * profile names a command and the host answers it.
+         *
+         * Called when the item renders and again whenever its menu opens, which
+         * is what makes a licence activated mid-session show up. Anything other
+         * than a non-empty string leaves the glyph as `label`'s first letter, so
+         * a host with no account has nothing to implement.
+         */
+        initialsCommand?: string;
       }
 
       /** A profile's app bar composition (see `ProfileShellSpec.appBar`). */

package/types/punica.module.shell.contentTabs.d.ts

@@ -1,7 +1,24 @@
 declare module 'punica' {
   export namespace shell {
+    /** One open content tab, as reported by `ContentTabsApi.list`. */
+    export interface ContentTabInfo {
+      /** Workspace-relative file path, or a scheme URI for command-only views. */
+      path: string;
+      /** Label shown on the tab (without the unsaved-changes marker). */
+      title: string;
+      /** Set by whichever extension opened it (e.g. "code", "markdown"). */
+      viewType?: string;
+      /** Whether the tab holds unsaved edits. */
+      dirty: boolean;
+    }
+
     /**
      * Content tab management capability for the main editor area.
+     *
+     * Tabs are identified by `path` — the same workspace-relative path the
+     * filesystem uses — which is what makes `rename` necessary rather than
+     * cosmetic: after a file moves, every tab keyed by the old path is
+     * holding an identity that no longer exists.
      */
     export interface ContentTabsApi {
       open(options: {
@@ -9,9 +26,18 @@ declare module 'punica' {
         title?: string;
         viewType?: string;
       }): HTMLElement | null;
-      close(path: string): void;
-      closeOthers(path: string): void;
-      closeAll(): void;
+      /**
+       * Close the tab at `path`, prompting first when it has unsaved changes
+       * (Save / Don't Save / Cancel). Resolves when the tab is gone or the
+       * user cancelled — check `list()` if you need to know which.
+       */
+      close(path: string): Promise<void>;
+      /** As `close`, addressed by tab id rather than path. */
+      closeById(id: string): Promise<void>;
+      closeOthers(path: string): Promise<void>;
+      /** As `closeOthers`, addressed by tab id rather than path. */
+      closeOthersById(id: string): Promise<void>;
+      closeAll(): Promise<void>;
       setDirty(path: string, dirty: boolean): void;
       /**
        * Returns the path of the currently active content tab, or null if none.
@@ -23,6 +49,34 @@ declare module 'punica' {
        * (e.g. "code", "flow-book", "markdown").
        */
       getActiveViewType(): string | null;
+
+      /**
+       * Re-key the tab at `oldPath` to `newPath`, keeping its content,
+       * dirty marker and selection. When `oldPath` names a directory, every
+       * tab beneath it moves too — renaming `src/` has to carry
+       * `src/app.ts` with it.
+       *
+       * This does not touch the filesystem; it is the tab half of a rename
+       * that already happened. Callers should not invoke it directly —
+       * `runtime.fileOperations.rename` drives it through the shell's
+       * participant, so an agent-initiated rename syncs the same way a
+       * context-menu one does.
+       */
+      rename(oldPath: string, newPath: string): void;
+
+      /**
+       * Close the tab at `path` (and, for a directory, everything beneath it)
+       * without prompting. For when the file is already gone: there is
+       * nothing left to save, so the unsaved-changes dialog would offer a
+       * choice that cannot be honored.
+       */
+      forceClose(path: string): void;
+
+      /** Whether the tab at `path` holds unsaved edits. False when no such tab. */
+      isDirty(path: string): boolean;
+
+      /** Every open tab, in the order they appear in the tab strip. */
+      list(): readonly ContentTabInfo[];
     }
 
     /**