@punica/editor 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.12.0",
+  "version": "1.14.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.kernel.policy.d.ts

@@ -266,6 +266,48 @@ declare module 'punica' {
       approvals: ApprovalRecord[];
     }
 
+    /**
+     * A signed approval grant. The gate matches a grant by (kind, id) plus
+     * scope and workspace; the token is what lets a later reader prove the
+     * grant was really issued and not edited afterwards.
+     */
+    export interface ApprovalTokenPayload {
+      scope: ApprovalScope;
+      capabilityId: string;
+      expiry: number;
+      jti: string;
+      issuer: string;
+      workspaceId?: string;
+      delegatedFrom?: string;
+      delegationDepth?: number;
+      approval?: PolicyApproval;
+      risk?: PolicyRisk;
+    }
+
+    /**
+     * Signs approval grants. The substrate default is HMAC-SHA256 over an
+     * in-memory ephemeral key, which does not survive a restart; a
+     * production host injects its own through
+     * `punica.runtime.setApprovalTokenSigner`.
+     */
+    export interface ApprovalTokenSigner {
+      /** Sign `payload`; returns the compact token string. */
+      sign(payload: ApprovalTokenPayload): Promise<string>;
+    }
+
+    /** Verifies (and revokes) approval tokens. */
+    export interface ApprovalTokenVerifier {
+      /**
+       * Parse, check the header and signature, check expiry and jti
+       * revocation. Returns the payload, or throws with a stable code.
+       */
+      verify(token: string): Promise<ApprovalTokenPayload>;
+      /** Mark a jti revoked; tokens carrying it then fail verification. */
+      revoke(jti: string): void;
+      /** Is a jti currently revoked? */
+      isRevoked(jti: string): boolean;
+    }
+
     export namespace Policy {
       const manager: PolicyApi;
     }

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;
@@ -181,7 +187,50 @@ declare module 'punica' {
       setResourcesProvider: (provider: ResourcesApi) => void;
       setTasksProvider: (provider: TaskRunnerApi) => void;
       setSecretsProvider: (provider: SecretsApi) => void;
+
+      /**
+       * Approval-token signing. The substrate default mints an in-memory
+       * ephemeral HMAC key on the first signature and loses it when the
+       * process exits, so a token signed before a restart no longer
+       * verifies after one — fine for dev and demo, useless as evidence.
+       * A production host installs a stable secret from the OS keychain
+       * during bootstrap, before `initialize()`:
+       *
+       *   punica.runtime.installDefaultApprovalTokenPair(secret)
+       *
+       * The two setters are the same seam for a host that brings its own
+       * signer (KMS, HSM); passing `undefined` restores the substrate
+       * default. The key belongs to the host and never to an extension —
+       * an extension that can reach the signing key can also produce the
+       * thing it signs.
+       */
+      installDefaultApprovalTokenPair: (secret: Uint8Array | string) => void;
+      setApprovalTokenSigner: (
+        signer: kernel.ApprovalTokenSigner | undefined
+      ) => void;
+      setApprovalTokenVerifier: (
+        verifier: kernel.ApprovalTokenVerifier | undefined
+      ) => void;
+
+      /**
+       * Who is at this workstation, so a user-initiated call's audit record
+       * names a subject instead of leaving `actor.id` empty. Absent is a
+       * normal state — a trial licence has no account — and the substrate
+       * invents nothing to fill it. Passing `undefined` clears it.
+       */
+      setHostIdentity: (identity: HostIdentity | undefined) => void;
+    }
+
+    /**
+     * The person a licence belongs to, as the host knows them. `email` is
+     * the identifier (a registry guarantees it unique and present);
+     * `displayName` is presentation and may be absent.
+     */
+    export interface HostIdentity {
+      email: string;
+      displayName?: string | null;
     }
+
   }
 
   export const runtime: runtime.RuntimeApi;

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.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[];
     }
 
     /**