@mutka-explorer/module 1.0.0-rc.2 → 1.0.0-rc.3

package/README.md

@@ -1,15 +1,18 @@
 # @mutka-explorer/module
 
-TypeScript types for authoring [Mutka](https://github.com/ilianAZZ/mutka) modules.
+Types + the `defineModule()` helper for authoring [Mutka](https://github.com/ilianAZZ/mutka) modules.
 
 A Mutka module is a single self-contained ESM file that
-`export default`s a module definition. It **imports nothing at runtime** — it
-reaches the system only through the `host` object passed to `setup(host)`, and
-every `host.*` call is checked against the permissions it declares.
+`export default`s a module definition. It reaches the system only through the
+`host` object passed to `setup(host)`, and every `host.*` call is checked against
+the permissions it declares.
 
-This package ships **only type definitions** (`.d.ts`, zero runtime code). You
-`import type` from it, TypeScript erases the import at compile time, and your
-built `index.js` stays self-contained — exactly what Mutka loads.
+This package is **types plus one tiny runtime export**: `defineModule`, an identity
+function (`def => def`). Everything else is types, erased at compile time. The only
+reason `defineModule` exists at runtime is type inference — it captures your
+`commands[].id`s so `host.onCommand` only accepts ids you declared (a typo or stale
+id is a compile error). A bundler inlines the call, so your built `index.js` stays
+import-free — exactly what Mutka loads.
 
 ## Install
 
@@ -20,9 +23,9 @@ npm i -D @mutka-explorer/module
 ## Usage
 
 ```ts
-import type { SandboxModuleDef } from "@mutka-explorer/module";
+import { defineModule } from "@mutka-explorer/module";
 
-const mod: SandboxModuleDef = {
+export default defineModule({
   id: "you.hello",
   name: "Hello",
   version: "1.0.0",
@@ -31,19 +34,22 @@ const mod: SandboxModuleDef = {
     { id: "you.hello.count", label: "Count items", contextMenu: true, when: { selection: "any" } },
   ],
   setup(host) {
-    host.onCommand("you.hello.count", async (snap) => {
+    host.onCommand("you.hello.count", async (snap) => {   // ✓ autocompleted from commands[]
       const items = await host.fs.readDir(snap.currentDirectory);
       host.log(`${items.length} items`);
     });
+    // host.onCommand("you.hello.typo", …)   ← compile error: not a declared command id
   },
-};
-
-export default mod;
+});
 ```
 
 `host` is fully typed (`host.fs`, `host.ui`, `host.net`, `host.dialog`, …), as
 are permissions, `when` clauses, the declarative `UINode` tree, and `FormSchema`.
 
+> Prefer no runtime import at all? `import type { SandboxModuleDef } from
+> "@mutka-explorer/module"` and annotate `const mod: SandboxModuleDef<"you.hello.count">
+> = { … }` — the generic param enforces the same command-id matching, purely in types.
+
 ### Build to a single file
 
 Mutka loads one ESM file with the default export intact. Bundle your TypeScript

package/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for @mutka-explorer/module v1.0.0-rc.2
+// Type definitions for @mutka-explorer/module v1.0.0-rc.3
 // Mutka module SDK — author-facing types only (no runtime code).
 // Generated from the Mutka app source; do not edit by hand.
 
@@ -99,8 +99,8 @@ export interface WhenClause {
 	 *  e.g. ["js"]). */
 	extensions?: string[];
 }
-export interface SandboxCommand {
-	id: string;
+export interface SandboxCommand<Id extends string = string> {
+	id: Id;
 	label: string;
 	icon?: string;
 	shortcut?: string;
@@ -456,7 +456,7 @@ export interface ClipboardFiles {
 }
 /** Whether a file's data is materialized locally or still cloud-only. */
 export type CloudStatus = "downloaded" | "cloud";
-export interface SandboxHostApi {
+export interface SandboxHostApi<TCommandId extends string = string> {
 	fs: {
 		/** List a directory's entries (works for local paths and provider schemes). */
 		readDir(path: string): Promise<FileItem[]>;
@@ -614,8 +614,10 @@ export interface SandboxHostApi {
 	refresh(): Promise<void>;
 	/** Run an item through the open-resolution pipeline (keyboard double-click). */
 	activate(item: FileItem): Promise<void>;
-	/** Register the function that runs when one of this module's commands fires. */
-	onCommand(commandId: string, handler: CommandHandler): void;
+	/** Register the function that runs when one of this module's commands fires.
+	 *  When you use `defineModule`, `commandId` is constrained to the ids you
+	 *  declared in `commands[]`, so a typo or stale id is a compile error. */
+	onCommand(commandId: TCommandId, handler: CommandHandler): void;
 	/** Register the function that runs when an item matches one of this module's open handlers. */
 	onOpen(handlerId: string, handler: OpenHandler): void;
 	/** Register the value provider for one of this module's custom columns. */
@@ -653,7 +655,7 @@ export interface SandboxHostApi {
 	/** Forwarded to the host console, prefixed with the module id. */
 	log(...args: unknown[]): void;
 }
-export interface SandboxModuleDef {
+export interface SandboxModuleDef<TCommandId extends string = string> {
 	/** Unique module id, "author.name" convention. */
 	id: string;
 	name?: string;
@@ -674,8 +676,10 @@ export interface SandboxModuleDef {
 	tags?: string[];
 	/** Every privileged capability this module uses MUST be listed here. */
 	permissions?: ModulePermission[];
-	/** Commands surfaced into the app's menus / toolbar. */
-	commands?: SandboxCommand[];
+	/** Commands surfaced into the app's menus / toolbar. The literal `id`s here are
+	 *  captured (via `defineModule`) and become the only values `host.onCommand`
+	 *  accepts in `setup`. */
+	commands?: SandboxCommand<TCommandId>[];
 	/** Open handlers (double-click behavior) by item type. */
 	openHandlers?: SandboxOpenHandler[];
 	/** Declarative entries in the left "Places" sidebar, grouped by category. */
@@ -730,8 +734,16 @@ export interface SandboxModuleDef {
 	/**
 	 * Runs once after load. Register command/open handlers and event subscriptions
 	 * here. Reaches the system only through `host.*` (each gated by permissions).
+	 * `host.onCommand` is typed to the `commands[].id`s declared above.
 	 */
-	setup?: (host: SandboxHostApi) => void | Promise<void>;
+	setup?: (host: SandboxHostApi<TCommandId>) => void | Promise<void>;
 }
+/**
+ * Author-facing helper. At runtime it returns its argument unchanged (so the
+ * built file is import-free once bundled); at the type level it infers the union
+ * of `commands[].id` literals and threads it into `host.onCommand`, so a typo'd
+ * or stale command id is a compile error. With no `commands`, ids stay `string`.
+ */
+export declare function defineModule<const TCommandId extends string = string>(def: SandboxModuleDef<TCommandId>): SandboxModuleDef<TCommandId>;
 
 export {};

package/index.js

@@ -0,0 +1,7 @@
+// Runtime for @mutka-explorer/module.
+//
+// The ONLY runtime export is `defineModule`, an identity function — it exists
+// purely so TypeScript can infer your `commands[].id`s and type `host.onCommand`
+// to them (all the typing lives in index.d.ts). A bundler inlines this call, so
+// an authored module's built `index.js` stays import-free and self-contained.
+export const defineModule = (def) => def;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mutka-explorer/module",
-  "version": "1.0.0-rc.2",
-  "description": "TypeScript types for authoring Mutka modules — the SandboxModuleDef shape plus the full host API. Types only, no runtime code.",
+  "version": "1.0.0-rc.3",
+  "description": "Types + the defineModule() helper for authoring Mutka modules — the SandboxModuleDef shape, the full typed host API, and command-id inference.",
   "license": "MIT",
   "author": "Mutka contributors",
   "homepage": "https://github.com/ilianAZZ/mutka",
@@ -17,14 +17,18 @@
     "sdk",
     "file-explorer"
   ],
+  "type": "module",
   "types": "./index.d.ts",
+  "main": "./index.js",
   "exports": {
     ".": {
-      "types": "./index.d.ts"
+      "types": "./index.d.ts",
+      "import": "./index.js"
     }
   },
   "files": [
     "index.d.ts",
+    "index.js",
     "README.md"
   ],
   "publishConfig": {