@justscale/core 0.1.0

package/dist/cli/build/process-plugin.js

@@ -0,0 +1,66 @@
+/**
+ * esbuild plugin that routes `.process.ts` files (and `.ts` files that
+ * contain `createProcess` against `@justscale/core/process`) through the
+ * JustScale process compiler before esbuild bundles them. Non-process
+ * TypeScript is left alone — esbuild's built-in TS support handles it.
+ *
+ * The plugin relies on `PtsCompiler` producing an inline base64 source
+ * map; esbuild auto-detects that and folds it into the final bundle's
+ * map when the build is configured with `sourcemap: true`.
+ *
+ * `@justscale/typescript` is loaded dynamically so apps that don't use
+ * process features (or don't build via `just build --env`) aren't forced
+ * to pull the TypeScript compiler into their dep tree.
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+function looksLikeProcessFile(filePath, source) {
+    if (basename(filePath).includes('.process.'))
+        return true;
+    return (source.includes('@justscale/core/process') &&
+        source.includes('createProcess'));
+}
+/**
+ * Create the esbuild plugin. Instantiate once per build — the plugin holds
+ * a `PtsCompiler` instance internally and reuses it across `onLoad` calls.
+ */
+export function justscaleProcessPlugin(opts) {
+    return {
+        name: 'justscale-process',
+        async setup(build) {
+            let compiler = null;
+            async function getCompiler() {
+                if (compiler)
+                    return compiler;
+                let mod;
+                try {
+                    mod = await import('@justscale/typescript/loader');
+                }
+                catch (err) {
+                    throw new Error("Process files were found but '@justscale/typescript' is not installed. " +
+                        "Install it to bundle apps that use '@justscale/core/process': " +
+                        'pnpm add -D @justscale/typescript\n' +
+                        `Underlying error: ${err.message}`, { cause: err });
+                }
+                compiler = new mod.PtsCompiler({
+                    rootDir: opts.rootDir,
+                    sourceMap: opts.sourceMap ?? true,
+                    verbose: opts.verbose ?? false,
+                });
+                return compiler;
+            }
+            build.onLoad({ filter: /\.ts$/, namespace: 'file' }, async (args) => {
+                const source = readFileSync(args.path, 'utf-8');
+                if (!looksLikeProcessFile(args.path, source))
+                    return null;
+                const c = await getCompiler();
+                const { code } = c.compile(args.path);
+                // Return as JS so esbuild doesn't reapply TS transforms on our
+                // already-compiled output. The inline sourceMappingURL in `code`
+                // threads through to the final bundle map automatically.
+                return { contents: code, loader: 'js' };
+            });
+        },
+    };
+}
+//# sourceMappingURL=process-plugin.js.map

package/dist/cli/build/process-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-plugin.js","sourceRoot":"","sources":["../../../src/cli/build/process-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,SAAS,oBAAoB,CAAC,QAAgB,EAAE,MAAc;IAC5D,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,OAAO,CACL,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAC1C,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CACjC,CAAC;AACJ,CAAC;AAWD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAA0B;IAC/D,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,KAAK,CAAC,KAAK,CAAC,KAAK;YACf,IAAI,QAAQ,GAAuD,IAAI,CAAC;YAExE,KAAK,UAAU,WAAW;gBACxB,IAAI,QAAQ;oBAAE,OAAO,QAAQ,CAAC;gBAC9B,IAAI,GAAkD,CAAC;gBACvD,IAAI,CAAC;oBACH,GAAG,GAAG,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC;gBACrD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,IAAI,KAAK,CACb,yEAAyE;wBACzE,gEAAgE;wBAChE,qCAAqC;wBACrC,qBAAsB,GAAa,CAAC,OAAO,EAAE,EAC7C,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;gBACJ,CAAC;gBACD,QAAQ,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC;oBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;oBACjC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,KAAK;iBAC/B,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,CAAC;YAED,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAClE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAChD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;oBAAE,OAAO,IAAI,CAAC;gBAE1D,MAAM,CAAC,GAAG,MAAM,WAAW,EAAE,CAAC;gBAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtC,+DAA+D;gBAC/D,iEAAiE;gBACjE,yDAAyD;gBACzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC1C,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/builder/create-cli-builder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CLI Route Builder Factory
+ *
+ * Creates CLI route builders that extend the core builder with CLI-specific methods.
+ */
+import type { z } from 'zod';
+import type { CliBaseContext, CliRouteBuilder } from './types.js';
+/** Symbol to store input schema on route */
+export declare const INPUT_SCHEMA: unique symbol;
+/** Symbol to store one-line description on route (for top-level `--help`). */
+export declare const CLI_DESCRIPTION: unique symbol;
+/** Read the input schema from a route definition. */
+export declare function getInputSchema(route: unknown): z.ZodType | undefined;
+/** Read the one-line command description from a route definition. */
+export declare function getCliDescription(route: unknown): string | undefined;
+/**
+ * Create a CLI route builder.
+ * Extends the core builder with CLI-specific methods.
+ */
+export declare function createCliRouteBuilder<TCommand extends string>(command: TCommand): CliRouteBuilder<CliBaseContext, never, {}, TCommand>;
+/**
+ * CLI command factory.
+ * Creates a builder for the given command name.
+ *
+ * @example
+ * ```typescript
+ * const buildRoute = Cli('build')
+ *   .input(z.object({ src: z.string() }))
+ *   .use(ctx => ({ srcPath: resolve(ctx.args.src) }))
+ *   .guard(ctx => {
+ *     if (!existsSync(ctx.srcPath)) {
+ *       ctx.io.error('Source not found')
+ *       return ctx.stop()
+ *     }
+ *   })
+ *   .handle(ctx => {
+ *     ctx.io.log(`Building from ${ctx.srcPath}`)
+ *   })
+ * ```
+ */
+export declare const Cli: <TCommand extends string>(command: TCommand) => CliRouteBuilder<CliBaseContext<Record<string, unknown>, void>, never, {}, TCommand>;
+//# sourceMappingURL=create-cli-builder.d.ts.map

package/dist/cli/builder/create-cli-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli-builder.d.ts","sourceRoot":"","sources":["../../../src/cli/builder/create-cli-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAE/E,4CAA4C;AAC5C,eAAO,MAAM,YAAY,eAA4B,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,GAAG,SAAS,CAEpE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,SAAS,MAAM,EAC3D,OAAO,EAAE,QAAQ,GAChB,eAAe,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,CAAC,CA+DtD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,GAAG,GAAI,QAAQ,SAAS,MAAM,EAAE,SAAS,QAAQ,wFAC9B,CAAC"}

package/dist/cli/builder/create-cli-builder.js

@@ -0,0 +1,104 @@
+/**
+ * CLI Route Builder Factory
+ *
+ * Creates CLI route builders that extend the core builder with CLI-specific methods.
+ */
+// Import from the leaf builder module rather than the package barrel
+// `../../index.js` — the barrel re-exports features/config/cli, which
+// pulls in Cli from cli/index.ts. Going through it here would put
+// cli/service.ts back into the TDZ by the time cluster.ts reads
+// CliService.
+import { createBaseBuilder, createBuilderState } from '../../builder/create-builder.js';
+/** Symbol to store input schema on route */
+export const INPUT_SCHEMA = Symbol('cli.inputSchema');
+/** Symbol to store one-line description on route (for top-level `--help`). */
+export const CLI_DESCRIPTION = Symbol('cli.description');
+/** Read the input schema from a route definition. */
+export function getInputSchema(route) {
+    return route?.[INPUT_SCHEMA];
+}
+/** Read the one-line command description from a route definition. */
+export function getCliDescription(route) {
+    return route?.[CLI_DESCRIPTION];
+}
+/**
+ * Create a CLI route builder.
+ * Extends the core builder with CLI-specific methods.
+ */
+export function createCliRouteBuilder(command) {
+    const state = createBuilderState();
+    const base = createBaseBuilder(state, command);
+    // Track input schema + optional description
+    let inputSchema;
+    let description;
+    const builder = {
+        // Delegate core methods to base builder
+        use(middleware) {
+            base.use(middleware);
+            return builder;
+        },
+        guard(check) {
+            base.guard(check);
+            return builder;
+        },
+        apply(plugin) {
+            // Plugin transforms builder
+            return plugin(builder);
+        },
+        returns(status, schema, permission) {
+            base.returns(status, schema, permission);
+            return builder;
+        },
+        types(types) {
+            base.types(types);
+            return builder;
+        },
+        // CLI-specific: input schema for arguments
+        input(schema) {
+            inputSchema = schema;
+            return builder;
+        },
+        // One-line summary shown by top-level `--help` and the per-command
+        // help header. Keep it short — a usage sentence, not a paragraph.
+        describe(text) {
+            description = text;
+            return builder;
+        },
+        handle(handler) {
+            const routeDef = base.handle(handler);
+            const cliRouteDef = {
+                ...routeDef,
+                method: 'CLI',
+                inputSchema,
+                description,
+            };
+            cliRouteDef[INPUT_SCHEMA] = inputSchema;
+            ;
+            cliRouteDef[CLI_DESCRIPTION] = description;
+            return cliRouteDef;
+        },
+    };
+    return builder;
+}
+/**
+ * CLI command factory.
+ * Creates a builder for the given command name.
+ *
+ * @example
+ * ```typescript
+ * const buildRoute = Cli('build')
+ *   .input(z.object({ src: z.string() }))
+ *   .use(ctx => ({ srcPath: resolve(ctx.args.src) }))
+ *   .guard(ctx => {
+ *     if (!existsSync(ctx.srcPath)) {
+ *       ctx.io.error('Source not found')
+ *       return ctx.stop()
+ *     }
+ *   })
+ *   .handle(ctx => {
+ *     ctx.io.log(`Building from ${ctx.srcPath}`)
+ *   })
+ * ```
+ */
+export const Cli = (command) => createCliRouteBuilder(command);
+//# sourceMappingURL=create-cli-builder.js.map

package/dist/cli/builder/create-cli-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli-builder.js","sourceRoot":"","sources":["../../../src/cli/builder/create-cli-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qEAAqE;AACrE,sEAAsE;AACtE,kEAAkE;AAClE,gEAAgE;AAChE,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAIxF,4CAA4C;AAC5C,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAQ,KAAiC,EAAE,CAAC,YAAY,CAA0B,CAAC;AACrF,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAQ,KAAiC,EAAE,CAAC,eAAe,CAAuB,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAiB;IAEjB,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAE/C,4CAA4C;IAC5C,IAAI,WAAkC,CAAC;IACvC,IAAI,WAA+B,CAAC;IAEpC,MAAM,OAAO,GAAwC;QACnD,wCAAwC;QACxC,GAAG,CAAC,UAAU;YACZ,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACrB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,MAAM;YACV,4BAA4B;YAC5B,OAAO,MAAM,CAAC,OAAc,CAAQ,CAAC;QACvC,CAAC;QAED,OAAO,CAAC,MAAc,EAAE,MAAkB,EAAE,UAAgB;YAC1D,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAa,EAAE,UAAU,CAAC,CAAC;YAChD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,2CAA2C;QAC3C,KAAK,CAAC,MAAM;YACV,WAAW,GAAG,MAAM,CAAC;YACrB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,mEAAmE;QACnE,kEAAkE;QAClE,QAAQ,CAAC,IAAI;YACX,WAAW,GAAG,IAAI,CAAC;YACnB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,CAAC,OAAO;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,WAAW,GAAoC;gBACnD,GAAG,QAAQ;gBACX,MAAM,EAAE,KAAK;gBACb,WAAW;gBACX,WAAW;aACZ,CACA;YAAC,WAAmB,CAAC,YAAY,CAAC,GAAG,WAAW,CAAC;YAClD,CAAC;YAAC,WAAmB,CAAC,eAAe,CAAC,GAAG,WAAW,CAAC;YACrD,OAAO,WAAW,CAAC;QACrB,CAAC;KACF,CAAC;IAEF,OAAO,OAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAA0B,OAAiB,EAAE,EAAE,CAChE,qBAAqB,CAAC,OAAO,CAAC,CAAC"}

package/dist/cli/builder/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI Builder Module
+ *
+ * Exports CLI-specific route builder types and factories.
+ */
+export type { CliRouteBuilder, CliRouteDef, CliMethod, CliBaseContext, } from './types.js';
+export { createCliRouteBuilder, Cli, INPUT_SCHEMA, getInputSchema, } from './create-cli-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,eAAe,EACf,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,GAAG,EACH,YAAY,EACZ,cAAc,GACf,MAAM,yBAAyB,CAAC"}

package/dist/cli/builder/index.js

@@ -0,0 +1,7 @@
+/**
+ * CLI Builder Module
+ *
+ * Exports CLI-specific route builder types and factories.
+ */
+export { createCliRouteBuilder, Cli, INPUT_SCHEMA, getInputSchema, } from './create-cli-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EACL,qBAAqB,EACrB,GAAG,EACH,YAAY,EACZ,cAAc,GACf,MAAM,yBAAyB,CAAC"}

package/dist/cli/builder/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * CLI Route Builder Types
+ *
+ * Extends core RouteBuilder with CLI-specific methods.
+ */
+import type { BuilderPlugin, ExtractAddedFromMiddleware, ExtractStepDeps, ResponseEntry, RouteBuilderV2 as RouteBuilder, RouteDefV2 as RouteDef, Stop } from '../../index.js';
+import type { GuardDef, MiddlewareDef } from '../../core/middleware.js';
+import type { ServiceToken } from '../../core/service.js';
+import type { z } from 'zod';
+import type { CliIO } from '../io.js';
+/**
+ * CLI method type - used as route method identifier.
+ */
+export type CliMethod = 'CLI';
+/**
+ * CLI-specific base context provided by the protocol.
+ * This is what the runner injects before route execution.
+ */
+export interface CliBaseContext<TArgs = Record<string, unknown>, TResult = void> {
+    /** Parsed command arguments */
+    args: TArgs;
+    /** CLI I/O interface for input/output */
+    io: CliIO<TResult>;
+}
+/**
+ * CLI Route Builder - extends core RouteBuilder with CLI-specific methods.
+ *
+ * @typeParam TContext - Accumulated context from middleware
+ * @typeParam TReturns - Union of possible responses (ResponseEntry union)
+ * @typeParam TRequirements - Accumulated DI requirements from plugins
+ * @typeParam TCommand - Command name literal
+ */
+export interface CliRouteBuilder<TContext, TReturns, TRequirements, TCommand extends string> extends RouteBuilder<TContext, TReturns, TRequirements, TCommand> {
+    /**
+     * Add middleware that extends context.
+     * Cannot stop execution - always returns additions.
+     * Accepts either a plain function or a MiddlewareDef (with DI).
+     * DI-aware middleware accumulates its inject deps into TRequirements,
+     * which flows through `RequiresOf<ControllerDef>` for type-level check.
+     */
+    use<TMw extends ((ctx: TContext) => object | Promise<object>) | MiddlewareDef<object, any>>(middleware: TMw): CliRouteBuilder<TContext & ExtractAddedFromMiddleware<TMw>, TReturns, TRequirements | ExtractStepDeps<TMw>, TCommand>;
+    /**
+     * Add guard that can stop execution.
+     * Cannot add to context - only checks and potentially stops.
+     * Accepts a guard function, a GuardDef (with DI), or an array of
+     * GuardDefs (any-match semantics).
+     */
+    guard<TG extends ((ctx: TContext & {
+        stop(): Stop;
+    }) => void | Stop | boolean | Promise<void | Stop | boolean>) | GuardDef<Record<string, ServiceToken>> | readonly GuardDef<Record<string, ServiceToken>>[]>(check: TG): CliRouteBuilder<TContext, TReturns, TRequirements | ExtractStepDeps<TG>, TCommand>;
+    /**
+     * Apply a plugin that can chain multiple operations.
+     * Plugins can add use/guard/returns in any combination.
+     */
+    apply<TCtxOut, TRetOut, TReqOut>(plugin: BuilderPlugin<TContext, TCtxOut, TReturns, TRetOut, TRequirements, TReqOut, TCommand>): CliRouteBuilder<TCtxOut, TRetOut, TReqOut, TCommand>;
+    /**
+     * Declare a possible response with schema.
+     */
+    returns<TStatus extends number, TSchema extends z.ZodType>(status: TStatus, schema: TSchema): CliRouteBuilder<TContext, TReturns | ResponseEntry<TStatus, z.infer<TSchema>>, TRequirements, TCommand>;
+    /**
+     * Declare a possible response without body.
+     */
+    returns<TStatus extends number>(status: TStatus): CliRouteBuilder<TContext, TReturns | ResponseEntry<TStatus, void>, TRequirements, TCommand>;
+    /**
+     * Specify the input schema for arguments.
+     * Uses convention-based parsing:
+     * - Required fields = positional args (in declaration order)
+     * - Optional/defaulted fields = named flags
+     *
+     * @example
+     * ```typescript
+     * Cli('build')
+     *   .input(z.object({
+     *     src: z.string(),           // positional: build <src>
+     *     verbose: z.boolean().default(false)  // flag: --verbose
+     *   }))
+     *   .handle(({ args }) => {
+     *     // args is typed as { src: string, verbose: boolean }
+     *   })
+     * ```
+     */
+    input<TSchema extends z.ZodType>(schema: TSchema): CliRouteBuilder<Omit<TContext, 'args'> & {
+        args: z.infer<TSchema>;
+    }, TReturns, TRequirements, TCommand>;
+    /**
+     * One-line summary surfaced by `just --help` and prefixed to the
+     * per-command `--help` output.
+     *
+     * @example
+     * ```typescript
+     * Cli('user add')
+     *   .describe('Create a new user account')
+     *   .input(...)
+     * ```
+     */
+    describe(text: string): CliRouteBuilder<TContext, TReturns, TRequirements, TCommand>;
+    /**
+     * Set final handler.
+     */
+    handle(handler: (ctx: TContext) => void | Promise<void>): CliRouteDef<TCommand, TReturns, TRequirements>;
+}
+/**
+ * CLI-specific route definition.
+ * Extends core RouteDef with CLI method and optional input schema.
+ */
+export interface CliRouteDef<TCommand extends string, TReturns, TRequirements> extends RouteDef<TCommand, TReturns, TRequirements> {
+    method: CliMethod;
+    /** Input schema for argument validation */
+    inputSchema?: z.ZodType;
+    /** One-line summary from `.describe()` — surfaced in `--help`. */
+    description?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/builder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cli/builder/types.ts"],"names":[],"mappings":"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"}

package/dist/cli/builder/types.js

@@ -0,0 +1,7 @@
+/**
+ * CLI Route Builder Types
+ *
+ * Extends core RouteBuilder with CLI-specific methods.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/builder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/builder/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/cli/cluster.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registers CLI method handlers on the cluster server.
+ * Auto-registers as a transport plugin when imported.
+ */
+import type { ClusterServer } from '../cluster/index.js';
+/** Register CLI method handlers on a cluster server. */
+export declare function registerCliHandlers(server: ClusterServer): void;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/cli/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/cli/cluster.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAW7B,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAqE/D"}

package/dist/cli/cluster.js

@@ -0,0 +1,145 @@
+/**
+ * Registers CLI method handlers on the cluster server.
+ * Auto-registers as a transport plugin when imported.
+ */
+import { Methods, registerTransport, } from '../cluster/index.js';
+import { CliService, LazyCliService, createCliService } from './service.js';
+/** @internal */
+let lazyCliService = null;
+/** Register CLI method handlers on a cluster server. */
+export function registerCliHandlers(server) {
+    server.handle(Methods.CLI_LIST, async (_, { app }) => {
+        if (!app) {
+            throw new Error('No app attached to cluster server');
+        }
+        const commands = [];
+        for (const controller of app.controllers) {
+            for (const route of controller.routes) {
+                if (route.method === 'CLI') {
+                    const command = route.path.replace(/\//g, ' ').trim();
+                    commands.push(command);
+                }
+            }
+        }
+        return { commands };
+    });
+    server.handle(Methods.CLI_INVOKE, async (params, ctx) => {
+        const { app, stream, prompt } = ctx;
+        if (!app) {
+            throw new Error('No app attached to cluster server');
+        }
+        const { command, args = {} } = params;
+        if (!command) {
+            throw new Error('Missing command parameter');
+        }
+        const commandAsPath = command.replace(/ /g, '/');
+        let targetRoute = null;
+        let targetDeps = {};
+        for (const controller of app.controllers) {
+            for (const route of controller.routes) {
+                if (route.method !== 'CLI')
+                    continue;
+                if (route.path === commandAsPath) {
+                    targetRoute = route;
+                    targetDeps = controller.deps;
+                    break;
+                }
+            }
+            if (targetRoute)
+                break;
+        }
+        if (!targetRoute) {
+            throw new Error(`Unknown command: ${command}`);
+        }
+        let result;
+        const io = createStreamingIO(stream, prompt, (data) => {
+            result = data;
+        });
+        const context = { args, io };
+        await app.execute({ route: targetRoute, deps: targetDeps, params: {} }, context);
+        return result;
+    });
+}
+/**
+ * Create a CLI IO implementation that streams output over cluster.
+ */
+function createStreamingIO(stream, prompt, onResult) {
+    return {
+        log: (msg) => stream('stdout', msg),
+        error: (msg) => stream('stderr', msg),
+        warn: (msg) => stream('stderr', msg),
+        result: onResult,
+        prompt: async (message, defaultValue) => {
+            const result = await prompt('text', message, { defaultValue });
+            if (result === null) {
+                throw new Error('Prompt cancelled');
+            }
+            return result;
+        },
+        confirm: async (message) => {
+            const result = await prompt('confirm', message);
+            if (result === null) {
+                return false; // Cancelled = no
+            }
+            return result;
+        },
+        select: async (message, choices) => {
+            const choicesForPrompt = choices.map((c) => ({
+                label: c.label,
+                value: String(c.value),
+            }));
+            const result = await prompt('select', message, {
+                choices: choicesForPrompt,
+            });
+            if (result === null) {
+                throw new Error('Selection cancelled');
+            }
+            const selected = choices.find((c) => String(c.value) === result);
+            if (!selected) {
+                throw new Error('Invalid selection');
+            }
+            return selected.value;
+        },
+        spinner: (message) => {
+            stream('spinner', { action: 'start', message });
+            return {
+                start: () => stream('spinner', { action: 'start', message }),
+                stop: () => stream('spinner', { action: 'stop' }),
+                success: (msg) => stream('spinner', { action: 'success', message: msg }),
+                fail: (msg) => stream('spinner', { action: 'fail', message: msg }),
+            };
+        },
+        progress: (total, message) => {
+            stream('progress', { action: 'start', total, message });
+            return {
+                update: (current) => stream('progress', { action: 'update', current }),
+                finish: () => stream('progress', { action: 'finish' }),
+            };
+        },
+        table: (data, columns) => {
+            stream('table', { data, columns });
+        },
+    };
+}
+/** CLI transport plugin - auto-registers CLI handlers on serve(). */
+const cliTransportPlugin = {
+    name: 'cli',
+    provides: [CliService],
+    beforeControllerResolution(container, _controllers) {
+        lazyCliService = new LazyCliService();
+        container.registerInstance(CliService, lazyCliService);
+    },
+    onAppCreated(app) {
+        const cliServiceImpl = createCliService(app);
+        if (lazyCliService) {
+            lazyCliService.setImplementation(cliServiceImpl);
+        }
+    },
+    registerHandlers(server, _app) {
+        registerCliHandlers(server);
+    },
+};
+registerTransport(cliTransportPlugin);
+import { registerPluginProvides } from '../builder/validation.js';
+registerPluginProvides(CliService);
+//# sourceMappingURL=cluster.js.map

package/dist/cli/cluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../../src/cli/cluster.ts"],"names":[],"mappings":"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"}

package/dist/cli/current-app.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime registry for the currently-running `defineApp` callable.
+ *
+ * `defineApp(meta, factory)` stashes its callable + the env it was
+ * invoked with here, after the kernel has successfully booted the
+ * app. Dev-mode packages (e.g. `@justscale/hmr`) read this to
+ * re-invoke the factory on file changes — rebuilding the app in a
+ * throwaway graph, diffing against the live container, and applying
+ * targeted replacements.
+ *
+ * Only one app is tracked per process. If several `defineApp`
+ * callables run (rare outside tests), the latest wins.
+ */
+import type { Environment } from '../features/environment/types.js';
+import type { App } from '../app.js';
+export interface CurrentApp {
+    /** The defineApp callable — invoke with the same env to rebuild. */
+    readonly callable: (env: Environment) => Promise<unknown>;
+    /** The env the app was last built with. */
+    readonly env: Environment;
+    /** File-URL of the entry module (from `defineApp(meta, ...)`); dev
+     * tooling re-imports this URL with a cache-bust to force re-linking
+     * of the entry's static imports when upstream files have changed. */
+    readonly entryUrl: string;
+    /**
+     * The live App instance. HMR reads this to push newly-appeared
+     * controllers into `app.controllers` after it has resolved them
+     * against the live container, so routes added via a new `.add()` in
+     * the user's factory light up without a process restart. Not set
+     * until the kernel has booted successfully.
+     */
+    readonly app: App;
+}
+export declare function setCurrentApp(app: CurrentApp): void;
+export declare function getCurrentApp(): CurrentApp | null;
+//# sourceMappingURL=current-app.d.ts.map

package/dist/cli/current-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-app.d.ts","sourceRoot":"","sources":["../../src/cli/current-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB;;yEAEqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAClB;AAID,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAEnD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD"}

package/dist/cli/current-app.js

@@ -0,0 +1,21 @@
+/**
+ * Runtime registry for the currently-running `defineApp` callable.
+ *
+ * `defineApp(meta, factory)` stashes its callable + the env it was
+ * invoked with here, after the kernel has successfully booted the
+ * app. Dev-mode packages (e.g. `@justscale/hmr`) read this to
+ * re-invoke the factory on file changes — rebuilding the app in a
+ * throwaway graph, diffing against the live container, and applying
+ * targeted replacements.
+ *
+ * Only one app is tracked per process. If several `defineApp`
+ * callables run (rare outside tests), the latest wins.
+ */
+let current = null;
+export function setCurrentApp(app) {
+    current = app;
+}
+export function getCurrentApp() {
+    return current;
+}
+//# sourceMappingURL=current-app.js.map

package/dist/cli/current-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-app.js","sourceRoot":"","sources":["../../src/cli/current-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH,IAAI,OAAO,GAAsB,IAAI,CAAC;AAEtC,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,OAAO,GAAG,GAAG,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}