kustom-mc 0.1.2 → 0.1.4

package/dist/runtime.d.ts

@@ -8,7 +8,7 @@
  * plain objects with __type property injected.
  */
 import './types/globals.js';
-import type { ScriptConfig, ExportedScript, PropSchema, EventSchema, EmptyEventSchema, BlockConfig, BlockDefinition, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, PropsAPI, CellStateUtils } from './types/index.js';
+import type { ScriptConfig, ScriptConfigWithMethods, ExportedScript, PropSchema, EventSchema, EmptyEventSchema, BlockConfig, BlockDefinition, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, PropsAPI, CellStateUtils, MethodMap } from './types/index.js';
 /**
  * Screen constructor - create new screens for GUIs.
  * Actual value is injected by Java at runtime.
@@ -59,13 +59,31 @@ export declare const ScriptableLocation: ScriptableLocationFactory;
  *     onSuccess: Props.Boolean(),
  *     onError: Props.String(),
  *   },
- *   run({ process, props }) {
+ *   methods: {
+ *     greet({ executor, props }) {
+ *       executor.asPlayer()?.sendMessage(props.message);
+ *     },
+ *   },
+ *   run({ process, props, methods }) {
  *     const player = process.getPlayer(props.player);
  *     player.sendMessage(props.message);
+ *     methods.greet();  // ctx auto-injected!
  *     process.emit("onSuccess", true);  // Typed!
  *   }
  * });
  */
+/**
+ * Define a kustom script with type safety and strongly-typed methods.
+ *
+ * Overload 1: Script WITH methods — M is inferred from the methods object,
+ * providing full autocomplete and type safety for ctx.methods.
+ */
+export declare function defineScript<P extends PropSchema, E extends EventSchema, M extends MethodMap<P, E>>(config: ScriptConfigWithMethods<P, E, M>): ExportedScript<P, E>;
+/**
+ * Define a kustom script with type safety.
+ *
+ * Overload 2: Script WITHOUT methods — simpler signature, backward compatible.
+ */
 export declare function defineScript<P extends PropSchema = Record<string, never>, E extends EventSchema = EmptyEventSchema>(config: ScriptConfig<P, E>): ExportedScript<P, E>;
 /**
  * Define a custom block with type safety.
@@ -113,4 +131,4 @@ export declare function defineBlock(config: BlockConfig): BlockDefinition;
  * });
  */
 export declare function defineItem(config: ItemConfig): ItemDefinition;
-export type { ScriptConfig, ScriptDefinition, ExportedScript, ScriptContext, PropSchema, PropAPI, InferProps, PropsAPI, EventSchema, EmptyEventSchema, InferEventPayload, ScriptModule, ScriptProcess, TypedScriptProcess, InferScriptModule, McModuleAPI, TypedMcModuleAPI, ProcessExecutorAPI, CameraAPI, SessionAPI, ChatGUIAPI, CommandManager, BetterModelEntityAPI, ShaperAPI, ItemAPI, DefinitionBuilder, ScriptablePlayer, BlockConfig, BlockDefinition, BlockClickEvent, BlockBreakEvent, BlockPlaceEvent, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, CellStateUtils, } from './types/index.js';
+export type { ScriptConfig, ScriptDefinition, ExportedScript, BaseScriptContext, ScriptContext, PropSchema, PropAPI, InferProps, PropsAPI, WrappedMethods, MethodMap, EventSchema, EmptyEventSchema, InferEventPayload, ScriptModule, ScriptProcess, TypedScriptProcess, InferScriptModule, McModuleAPI, TypedMcModuleAPI, ProcessExecutorAPI, CameraAPI, SessionAPI, ChatGUIAPI, CommandManager, BetterModelEntityAPI, ShaperAPI, ItemAPI, DefinitionBuilder, ScriptablePlayer, BlockConfig, BlockDefinition, BlockClickEvent, BlockBreakEvent, BlockPlaceEvent, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, CellStateUtils, } from './types/index.js';

package/dist/runtime.js

@@ -9,36 +9,11 @@
  */
 // Import globals for side effects - makes console, setTimeout, etc. available
 import './types/globals.js';
-/**
- * Define a kustom script with type safety.
- *
- * This is a type-only helper that returns its input unchanged.
- * The Java ProcessManager extracts the `run` function and calls it
- * with the ScriptContext.
- *
- * @example
- * import { defineScript, Props } from 'kustom-mc';
- *
- * export default defineScript({
- *   props: {
- *     player: Props.String(),
- *     message: Props.String("Hello!"),
- *   },
- *   events: {
- *     onSuccess: Props.Boolean(),
- *     onError: Props.String(),
- *   },
- *   run({ process, props }) {
- *     const player = process.getPlayer(props.player);
- *     player.sendMessage(props.message);
- *     process.emit("onSuccess", true);  // Typed!
- *   }
- * });
- */
+// Implementation
 export function defineScript(config) {
     // Simply return the config - the Java side will handle execution
     // The return type is ExportedScript which combines:
-    // - Definition metadata (props, events, __type) for the Java runtime
+    // - Definition metadata (props, events, methods, __type) for the Java runtime
     // - ScriptModule interface with .run(props) method for TypeScript imports
     return config;
 }

package/dist/types/__tests__/debug-inference.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Debug: Check what M resolves to
+ */
+export {};

package/dist/types/__tests__/debug-inference.js

@@ -0,0 +1,25 @@
+/**
+ * Debug: Check what M resolves to
+ */
+import { defineScript } from '../../runtime.js';
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+};
+const result = defineScript({
+    props: {
+        message: Props.String("Hello!"),
+    },
+    methods: {
+        toto({ executor }) {
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+    },
+    run({ methods }) {
+        // Let's see what type methods is
+        const m = methods;
+        const _check = m;
+        console.log(_check);
+    },
+});
+const _r = result;
+console.log(_r);

package/dist/types/__tests__/defineScript-methods-dx-test.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DX test for strongly-typed defineScript methods.
+ *
+ * This simulates the EXACT user experience — calling defineScript()
+ * with methods and verifying autocomplete/type safety.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the DX is correct.
+ */
+declare const _default: import("../index.js").ExportedScript<{
+    message: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+    count: {
+        __brand: "NumberPropAPI";
+        defaultValue: number | undefined;
+    };
+}, import("../index.js").EventSchema>;
+export default _default;
+export declare const noMethodsScript: import("../index.js").ExportedScript<{
+    name: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+}, import("../index.js").EmptyEventSchema>;
+export declare const bareScript: import("../index.js").ExportedScript<Record<string, never>, import("../index.js").EmptyEventSchema>;

package/dist/types/__tests__/defineScript-methods-dx-test.js

@@ -0,0 +1,76 @@
+/**
+ * DX test for strongly-typed defineScript methods.
+ *
+ * This simulates the EXACT user experience — calling defineScript()
+ * with methods and verifying autocomplete/type safety.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the DX is correct.
+ */
+import { defineScript } from '../../runtime.js';
+// Simulate Props (these are runtime-injected, so we cast)
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+    Number: (defaultValue) => ({ __brand: 'NumberPropAPI', defaultValue }),
+    Boolean: (defaultValue) => ({ __brand: 'BooleanPropAPI', defaultValue }),
+};
+// ============================================
+// Test: Full DX with methods
+// ============================================
+export default defineScript({
+    props: {
+        message: Props.String("Hello!"),
+        count: Props.Number(5),
+    },
+    methods: {
+        toto({ executor }) {
+            // ✅ executor is typed as ProcessExecutorAPI
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet({ executor, props }) {
+            // ✅ props is typed: props.message is string, props.count is number
+            const _msg = props.message;
+            const _cnt = props.count;
+            // Note: methods receive BaseScriptContext (no `methods` field)
+            // to avoid circular generic inference. Only run() gets methods.
+            executor.asPlayer()?.sendMessage("greet!");
+        },
+        doSomething({ executor }) {
+            // ✅ Methods receive BaseScriptContext with all subsystems
+            executor.asPlayer()?.sendMessage("doSomething!");
+        },
+    },
+    run({ executor, props, methods }) {
+        // ✅ props is typed
+        const _msg = props.message;
+        const _cnt = props.count;
+        // ✅ methods are typed with autocomplete
+        methods.toto();
+        methods.greet();
+        methods.doSomething();
+        // ✅ executor is typed
+        executor.asPlayer()?.sendMessage(props.message);
+    },
+});
+// ============================================
+// Test: Script without methods (backward compat)
+// ============================================
+export const noMethodsScript = defineScript({
+    props: {
+        name: Props.String("World"),
+    },
+    run({ props }) {
+        // ✅ props is typed
+        const _name = props.name;
+        console.log(_name);
+    },
+});
+// ============================================
+// Test: Script with no props and no methods
+// ============================================
+export const bareScript = defineScript({
+    run() {
+        // ✅ Compiles fine with no props/methods
+        console.log("bare script");
+    },
+});

package/dist/types/__tests__/defineScript-methods-negative-test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Negative type test for strongly-typed defineScript methods.
+ *
+ * Uses @ts-expect-error to verify that invalid method calls
+ * produce type errors. If a @ts-expect-error line does NOT
+ * produce an error, tsc will report "Unused '@ts-expect-error' directive".
+ *
+ * Run: npx tsc --noEmit
+ */
+declare const _default: import("../index.js").ExportedScript<{
+    message: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+}, import("../index.js").EventSchema>;
+export default _default;

package/dist/types/__tests__/defineScript-methods-negative-test.js

@@ -0,0 +1,36 @@
+/**
+ * Negative type test for strongly-typed defineScript methods.
+ *
+ * Uses @ts-expect-error to verify that invalid method calls
+ * produce type errors. If a @ts-expect-error line does NOT
+ * produce an error, tsc will report "Unused '@ts-expect-error' directive".
+ *
+ * Run: npx tsc --noEmit
+ */
+import { defineScript } from '../../runtime.js';
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+};
+export default defineScript({
+    props: {
+        message: Props.String("Hello!"),
+    },
+    methods: {
+        toto({ executor }) {
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet({ executor }) {
+            // Methods receive BaseScriptContext — no `methods` field.
+            // This avoids circular generic inference.
+            executor.asPlayer()?.sendMessage("greet!");
+        },
+    },
+    run({ methods }) {
+        methods.toto(); // ✅ valid
+        methods.greet(); // ✅ valid
+        // @ts-expect-error — 'nope' does not exist on methods
+        methods.nope();
+        // @ts-expect-error — 'doesNotExist' does not exist on methods
+        methods.doesNotExist();
+    },
+});

package/dist/types/__tests__/methods-type-test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type-level test for strongly-typed defineScript methods.
+ *
+ * This file is NOT executed — it only verifies that TypeScript
+ * correctly infers method types and provides autocomplete.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the types are correct.
+ */
+export {};

package/dist/types/__tests__/methods-type-test.js

@@ -0,0 +1,39 @@
+/**
+ * Type-level test for strongly-typed defineScript methods.
+ *
+ * This file is NOT executed — it only verifies that TypeScript
+ * correctly infers method types and provides autocomplete.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the types are correct.
+ */
+// These should be the stripped signatures:
+const _test1 = {
+    greet: (name) => name, // ctx stripped, (name: string) => string
+    wave: () => { }, // ctx stripped, () => void
+};
+// Verify the config type accepts methods and that ctx.methods inside run() is strongly typed.
+const _config = {
+    props: undefined,
+    methods: {
+        toto(ctx) {
+            ctx.executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet(ctx) {
+            // Methods receive BaseScriptContext — no `methods` field
+            ctx.executor.asPlayer()?.sendMessage("greet!");
+        },
+    },
+    run(ctx) {
+        ctx.methods.toto();
+        ctx.methods.greet();
+        // ctx.props should be typed
+        const _msg = ctx.props.message;
+        const _cnt = ctx.props.count;
+    },
+};
+const _emptyCtx = {};
+// Should be Record<string, never> — no methods
+const _emptyWrapped = {};
+console.log("Type tests passed (compile-time only)", _test1, _config, _emptyCtx, _emptyWrapped);
+export {};

package/dist/types/index.d.ts

@@ -97,6 +97,22 @@ export type EmptyEventSchema = Record<string, never>;
  * Infer the event payload type from an EventSchema.
  */
 export type InferEventPayload<E extends EventSchema, K extends keyof E> = InferPropType<E[K]>;
+/**
+ * Strips the first ctx parameter from each method, producing the type
+ * available as ctx.methods inside scripts.
+ *
+ * Given methods like `{ greet(ctx: ScriptContext, ...args): void }`,
+ * produces `{ greet(...args): void }` — ctx is auto-injected at runtime.
+ */
+export type WrappedMethods<M> = {
+    [K in keyof M]: M[K] extends (ctx: never, ...args: infer A) => infer R ? (...args: A) => R : () => unknown;
+};
+/**
+ * Script configuration for defineScript() — without methods.
+ *
+ * @typeParam P - Props schema type
+ * @typeParam E - Events schema type
+ */
 export interface ScriptConfig<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
     /** Props schema with types and defaults */
     props?: P;
@@ -124,6 +140,47 @@ export interface ScriptConfig<P extends PropSchema, E extends EventSchema = Empt
      */
     run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E>) => void;
 }
+/**
+ * Script configuration for defineScript() — with strongly-typed methods.
+ *
+ * Uses a generic `M` to capture the literal shape of the methods object.
+ * Each method receives a `ScriptContext` with `WrappedMethods<M>` providing
+ * full autocomplete for `ctx.methods.*`.
+ *
+ * The `methods` field uses a mapped type over `keyof M` so TypeScript
+ * can infer `M` from the object literal keys, then constrains each
+ * method's signature.
+ *
+ * @typeParam P - Props schema type
+ * @typeParam E - Events schema type
+ * @typeParam M - Methods record type (inferred from the methods object literal)
+ */
+/** Constraint for the methods record — each method receives BaseScriptContext */
+export type MethodMap<P extends PropSchema, E extends EventSchema> = Record<string, (ctx: BaseScriptContext<InferProps<P>, E>, ...args: unknown[]) => unknown>;
+export type ScriptConfigWithMethods<P extends PropSchema, E extends EventSchema, M extends MethodMap<P, E>> = {
+    props?: P;
+    events?: E;
+    /**
+     * Named methods that can be called externally via `process.call("methodName", ...args)`
+     * or internally via `ctx.methods.methodName()`.
+     *
+     * Each method receives `(ctx: BaseScriptContext, ...extraArgs)` — a context without `methods`
+     * to avoid circular generic inference. At runtime, Java injects the full context.
+     *
+     * When called via `ctx.methods` in `run()`, the `ctx` parameter is auto-injected.
+     *
+     * @example
+     * ```typescript
+     * methods: {
+     *   greet({ executor }) {
+     *     executor.asPlayer()?.sendMessage("Hello!");
+     *   },
+     * }
+     * ```
+     */
+    methods: M;
+    run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E, WrappedMethods<M>>) => void;
+};
 export interface ScriptDefinition<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
     props?: P;
     events?: E;
@@ -260,10 +317,14 @@ export interface ItemDefinition extends ItemConfig {
     readonly __type: "item";
 }
 /**
- * Context passed to script run function.
- * Contains all APIs and subsystems available to scripts.
+ * Base context passed to method functions.
+ * Same as ScriptContext but without `methods` to avoid circular generic inference.
+ * At runtime, Java actually injects the full context including methods.
+ *
+ * @typeParam P - Inferred props type
+ * @typeParam E - Event schema type
  */
-export interface ScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema> {
+export interface BaseScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema> {
     /** Process API for script management (typed for events if declared) */
     process: TypedMcModuleAPI<E>;
     /** Validated props */
@@ -289,6 +350,33 @@ export interface ScriptContext<P = Record<string, unknown>, E extends EventSchem
     /** Persistent storage system */
     storage: StorageAPI;
 }
+/**
+ * Full context passed to the script `run()` function.
+ * Extends BaseScriptContext with strongly-typed `methods`.
+ *
+ * @typeParam P - Inferred props type
+ * @typeParam E - Event schema type
+ * @typeParam Methods - Strongly-typed methods map (auto-inferred from defineScript)
+ */
+export interface ScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema, Methods = Record<string, never>> extends BaseScriptContext<P, E> {
+    /**
+     * Callable methods defined in defineScript({ methods: { ... } }).
+     * These are wrapped so `ctx` is auto-injected — call them directly without passing ctx.
+     *
+     * Fully typed: autocomplete shows only the methods you defined,
+     * and calling a non-existent method is a type error.
+     *
+     * @example
+     * ```typescript
+     * run({ methods }) {
+     *   methods.greet();        // ✅ ctx is auto-injected, autocomplete works
+     *   methods.farewell("arg"); // ✅ extra args passed through
+     *   methods.nope();          // ❌ type error — not defined
+     * }
+     * ```
+     */
+    methods: Methods;
+}
 export interface PropSchema {
     [key: string]: PropAPI;
 }

package/dist/upload.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Response from the /packs/upload endpoint.
+ */
+export interface UploadResponse {
+    success: boolean;
+    packId?: string;
+    version?: string;
+    message?: string;
+    error?: string;
+}
+/**
+ * Upload a pack zip to the server via HTTP POST.
+ *
+ * Sends raw zip bytes with application/zip content type.
+ * The server saves the zip and hot-loads the pack.
+ *
+ * @param serverUrl - Server base URL (e.g. "http://localhost:8765")
+ * @param token - Authentication token (from `kustom login`)
+ * @param buffer - Raw zip bytes
+ * @param packId - Pack ID hint for the server
+ */
+export declare function uploadPack(serverUrl: string, token: string, buffer: Buffer, packId: string): Promise<UploadResponse>;

package/dist/upload.js

@@ -0,0 +1,35 @@
+import { normalizeServerUrl } from './credentials.js';
+/**
+ * Upload a pack zip to the server via HTTP POST.
+ *
+ * Sends raw zip bytes with application/zip content type.
+ * The server saves the zip and hot-loads the pack.
+ *
+ * @param serverUrl - Server base URL (e.g. "http://localhost:8765")
+ * @param token - Authentication token (from `kustom login`)
+ * @param buffer - Raw zip bytes
+ * @param packId - Pack ID hint for the server
+ */
+export async function uploadPack(serverUrl, token, buffer, packId) {
+    const url = `${normalizeServerUrl(serverUrl)}/packs/upload`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/zip',
+            'X-Pack-Id': packId
+        },
+        body: buffer
+    });
+    if (response.status === 401) {
+        throw new Error('Authentication failed. Token may be invalid or expired. Run: npx kustom-mc login');
+    }
+    if (response.status === 403) {
+        throw new Error('Permission denied. You may not have upload permissions.');
+    }
+    const result = await response.json();
+    if (!response.ok) {
+        throw new Error(result.error || result.message || `Server returned ${response.status}`);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kustom-mc",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI and type library for kustompack development",
   "type": "module",
   "main": "dist/runtime.js",