@justscale/core 0.1.0

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

@@ -0,0 +1,35 @@
+/**
+ * @example
+ * ```ts
+ * import { defineApp } from '@justscale/core';
+ *
+ * export default defineApp(import.meta, (env) =>
+ *   JustScale()
+ *     .add(env)
+ *     .add(PostgresFeature)
+ *     .add(OrderController)
+ * );
+ * ```
+ */
+import type { Environment } from '../features/environment/types.js';
+/** User factory: `(env) => builder`. May be sync or async. */
+export type AppFactory<TEnv extends Environment, TBuilder> = (env: TEnv) => TBuilder | Promise<TBuilder>;
+/**
+ * Callable returned by `defineApp`. Called with no args, loads env automatically.
+ * Pass an explicit Environment to skip loading (useful in tests).
+ */
+export interface DefinedApp<TEnv extends Environment, TBuilder> {
+    (env?: TEnv): Promise<TBuilder>;
+}
+/**
+ * Define an application's entrypoint.
+ *
+ * Returns a callable the CLI and tests can import and invoke.
+ * When the calling module is the Node entrypoint (`argv[1]`), schedules
+ * an autorun: builds, compiles, awaits ready, then dispatches `Cli.run`
+ * (if invoked with CLI args) or `BuiltApp.serve()`.
+ */
+export declare function defineApp<TEnv extends Environment, TBuilder>(meta: ImportMeta | {
+    url: string;
+}, factory: AppFactory<TEnv, TBuilder>): DefinedApp<TEnv, TBuilder>;
+//# sourceMappingURL=define-app.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../../src/cli/define-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAMpE,8DAA8D;AAC9D,MAAM,MAAM,UAAU,CAAC,IAAI,SAAS,WAAW,EAAE,QAAQ,IAAI,CAC3D,GAAG,EAAE,IAAI,KACN,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,IAAI,SAAS,WAAW,EAAE,QAAQ;IAC5D,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAS,WAAW,EAAE,QAAQ,EAC1D,IAAI,EAAE,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAClC,OAAO,EAAE,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,GAClC,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC"}

package/dist/cli/define-app.js

@@ -0,0 +1,79 @@
+/**
+ * @example
+ * ```ts
+ * import { defineApp } from '@justscale/core';
+ *
+ * export default defineApp(import.meta, (env) =>
+ *   JustScale()
+ *     .add(env)
+ *     .add(PostgresFeature)
+ *     .add(OrderController)
+ * );
+ * ```
+ */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { loadEnvironment } from '../features/environment/load.js';
+import { setCurrentApp } from './current-app.js';
+let autorunFired = false;
+export function defineApp(meta, factory) {
+    const callable = (async (envOverride) => {
+        const env = envOverride ?? (await loadEnvironment({ from: meta }));
+        return await factory(env);
+    });
+    if (isEntrypoint(meta) && !autorunFired) {
+        autorunFired = true;
+        // Don't block the caller's module evaluation - schedule a microtask.
+        void (async () => {
+            try {
+                const env = (await loadEnvironment({ from: meta }));
+                const builderLike = await callable(env);
+                const built = builderLike.build();
+                const app = built.compile();
+                await app.ready;
+                setCurrentApp({
+                    callable: callable,
+                    env: env,
+                    entryUrl: meta.url,
+                    app: app,
+                });
+                const { Cli } = await import('./factory.js');
+                if (Cli.isCommandLineRun()) {
+                    await Cli.run(app);
+                    return;
+                }
+                const noSocket = process.env.JUSTSCALE_NO_SOCKET === '1'
+                    || process.env.JUSTSCALE_NO_SOCKET === 'true';
+                const socketPath = process.env.JUSTSCALE_SOCKET_PATH;
+                await built.serve(noSocket ? { noSocket: true } : socketPath ? { socketPath } : undefined);
+            }
+            catch (err) {
+                setImmediate(() => {
+                    throw err;
+                });
+            }
+        })();
+    }
+    return callable;
+}
+function isEntrypoint(meta) {
+    const entrypointArg = process.argv[1];
+    if (!entrypointArg)
+        return false;
+    let metaPath;
+    try {
+        metaPath = fileURLToPath(meta.url);
+    }
+    catch {
+        return false;
+    }
+    let entrypointReal;
+    try {
+        entrypointReal = realpathSync(entrypointArg);
+    }
+    catch {
+        entrypointReal = entrypointArg;
+    }
+    return metaPath === entrypointArg || metaPath === entrypointReal;
+}
+//# sourceMappingURL=define-app.js.map

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

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

package/dist/cli/define-main.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Helper for the standard "run only when invoked directly" entrypoint guard.
+ *
+ * Without this, importing a file that calls `main()` at module top level
+ * causes side effects during `just`-style command discovery. The guard
+ * checks whether the current file is the Node entrypoint (argv[1]) and
+ * only runs the function if so.
+ */
+/**
+ * Run `fn` only when the calling module is the Node entrypoint.
+ *
+ * Pass `import.meta` (or an equivalent `{ url }` object) so the helper can
+ * compare the caller's file URL to `process.argv[1]`. When imported by
+ * another module (e.g. during CLI command discovery), `fn` is skipped.
+ *
+ * Errors thrown by `fn` are re-thrown so the process exits non-zero via
+ * Node's default unhandled-rejection behaviour.
+ *
+ * @example
+ * ```typescript
+ * import { defineMain } from '@justscale/core'
+ *
+ * defineMain(import.meta, async () => {
+ *   const env = await loadEnvironment({ from: import.meta })
+ *   const app = createApp(env)
+ *   await app.serve({ http: 3000 })
+ * })
+ * ```
+ */
+export declare function defineMain(meta: ImportMeta | {
+    url: string;
+}, fn: () => void | Promise<void>): void;
+//# sourceMappingURL=define-main.d.ts.map

package/dist/cli/define-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-main.d.ts","sourceRoot":"","sources":["../../src/cli/define-main.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAClC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC7B,IAAI,CAiCN"}

package/dist/cli/define-main.js

@@ -0,0 +1,67 @@
+/**
+ * Helper for the standard "run only when invoked directly" entrypoint guard.
+ *
+ * Without this, importing a file that calls `main()` at module top level
+ * causes side effects during `just`-style command discovery. The guard
+ * checks whether the current file is the Node entrypoint (argv[1]) and
+ * only runs the function if so.
+ */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * Run `fn` only when the calling module is the Node entrypoint.
+ *
+ * Pass `import.meta` (or an equivalent `{ url }` object) so the helper can
+ * compare the caller's file URL to `process.argv[1]`. When imported by
+ * another module (e.g. during CLI command discovery), `fn` is skipped.
+ *
+ * Errors thrown by `fn` are re-thrown so the process exits non-zero via
+ * Node's default unhandled-rejection behaviour.
+ *
+ * @example
+ * ```typescript
+ * import { defineMain } from '@justscale/core'
+ *
+ * defineMain(import.meta, async () => {
+ *   const env = await loadEnvironment({ from: import.meta })
+ *   const app = createApp(env)
+ *   await app.serve({ http: 3000 })
+ * })
+ * ```
+ */
+export function defineMain(meta, fn) {
+    const entrypointArg = process.argv[1];
+    if (!entrypointArg)
+        return;
+    let metaPath;
+    try {
+        metaPath = fileURLToPath(meta.url);
+    }
+    catch {
+        return;
+    }
+    // Compare realpaths — `fileURLToPath(import.meta.url)` returns the
+    // canonical path, but `process.argv[1]` can be a symlinked path
+    // (e.g. `/tmp` vs `/private/tmp` on macOS). Both paths may not exist
+    // on disk (unit tests), so swallow ENOENT.
+    let entrypointReal;
+    try {
+        entrypointReal = realpathSync(entrypointArg);
+    }
+    catch {
+        entrypointReal = entrypointArg;
+    }
+    if (metaPath === entrypointArg || metaPath === entrypointReal) {
+        // Re-throw from a timer so errors escape any surrounding promise chain
+        // and trigger Node's uncaughtException handler → non-zero exit code.
+        void (async () => {
+            try {
+                await fn();
+            }
+            catch (err) {
+                setImmediate(() => { throw err; });
+            }
+        })();
+    }
+}
+//# sourceMappingURL=define-main.js.map

package/dist/cli/define-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-main.js","sourceRoot":"","sources":["../../src/cli/define-main.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAkC,EAClC,EAA8B;IAE9B,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,aAAa;QAAE,OAAO;IAE3B,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,mEAAmE;IACnE,gEAAgE;IAChE,qEAAqE;IACrE,2CAA2C;IAC3C,IAAI,cAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,cAAc,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,cAAc,GAAG,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ,KAAK,aAAa,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QAC9D,uEAAuE;QACvE,qEAAqE;QACrE,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,EAAE,EAAE,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,YAAY,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;AACH,CAAC"}

package/dist/cli/define-project.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Project configuration for the `just` CLI.
+ *
+ * Declares one app entry (optionally split by env.type), build settings,
+ * and environment configuration. Used in `justscale.config.ts`.
+ *
+ * @example Shorthand — one composition for every env
+ * ```typescript
+ * export default defineProject({
+ *   app: () => import('./src/app.js'),
+ * })
+ * ```
+ *
+ * @example Split by env.type — dev.ts adds pglite + dev CLIs
+ * ```typescript
+ * export default defineProject({
+ *   app: {
+ *     default:     () => import('./src/app.js'),
+ *     development: () => import('./src/dev.js'),
+ *     test:        () => import('./src/dev.js'),
+ *   },
+ * })
+ * ```
+ */
+import type { EnvironmentType } from '../features/environment/types.js';
+export interface EnvironmentConfig {
+    url: string;
+    ssh?: string;
+}
+export interface BuildConfig {
+    outDir?: string;
+    target?: string;
+    /**
+     * Files or globs to copy into the output directory alongside the bundled
+     * entry when running `just build --env <name>`. Useful for artifacts the
+     * deployed process needs at runtime but that don't live in the bundle
+     * (SQL migration files, OpenAPI specs, etc.). Paths are resolved relative
+     * to the directory containing `justscale.config.ts`.
+     */
+    include?: string[];
+    /**
+     * Package specifiers to keep external (not bundled). Node builtins
+     * (`node:*`) are handled automatically. Use this for native modules
+     * with `.node` binaries (better-sqlite3, bcrypt, sharp, canvas) or
+     * any package that doesn't survive bundling. Anything not in this
+     * list is inlined into the output — that's what gives the deploy
+     * artifact real tree-shaking benefit.
+     */
+    external?: string[];
+}
+/** Lazy import factory returning the user's app module. */
+export type AppLoader = () => Promise<unknown>;
+/**
+ * User-configurable app entry. Either a single loader (same composition
+ * for every env), or an object with a required `default` fallback and
+ * optional per-env overrides keyed by `env.type`.
+ */
+export type AppEntry = AppLoader | ({
+    default: AppLoader;
+} & Partial<Record<EnvironmentType, AppLoader>>);
+export interface ProjectConfig {
+    app: AppEntry;
+    build?: BuildConfig;
+    environments?: Record<string, EnvironmentConfig>;
+}
+/**
+ * Resolve the loader for a given env.type. Function-shorthand entries
+ * are returned as-is; object-form entries prefer the type-specific
+ * override and fall through to `default`.
+ */
+export declare function pickAppLoader(app: AppEntry, envType: EnvironmentType): AppLoader;
+export declare function defineProject(config: ProjectConfig): ProjectConfig;
+export declare function isProjectConfig(value: unknown): value is ProjectConfig;
+/**
+ * Extract the file path argument from a lazy import loader like
+ * `() => import('./src/dev.js')`. Returns null if the loader uses a shape
+ * we can't introspect (computed specifiers, re-exports, dynamic paths).
+ * Shared by `just dev` and `just build` so both resolve the app entry the
+ * same way.
+ */
+export declare function extractLoaderPath(loader: AppLoader): string | null;
+/**
+ * `config.app` uses `.js` suffixes even when the source is `.ts` (NodeNext
+ * resolution convention). Resolve to the actual source file that exists on
+ * disk, preferring the `.ts` variant when it's alongside the `.js` path.
+ */
+export declare function resolveSourcePath(baseDir: string, loaderPath: string): string | null;
+/**
+ * Resolve the app entry source file for a given env.type. Returns null if
+ * the config doesn't point at a file the filesystem can produce.
+ */
+export declare function resolveAppEntry(configFileUrl: string, app: AppEntry, envType: EnvironmentType): string | null;
+//# sourceMappingURL=define-project.d.ts.map

package/dist/cli/define-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-project.d.ts","sourceRoot":"","sources":["../../src/cli/define-project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,2DAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,CAAC;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,CAAA;IACb,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CACjD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,eAAe,GACvB,SAAS,CAGX;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAElE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAIlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQpF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAMf"}

package/dist/cli/define-project.js

@@ -0,0 +1,85 @@
+/**
+ * Project configuration for the `just` CLI.
+ *
+ * Declares one app entry (optionally split by env.type), build settings,
+ * and environment configuration. Used in `justscale.config.ts`.
+ *
+ * @example Shorthand — one composition for every env
+ * ```typescript
+ * export default defineProject({
+ *   app: () => import('./src/app.js'),
+ * })
+ * ```
+ *
+ * @example Split by env.type — dev.ts adds pglite + dev CLIs
+ * ```typescript
+ * export default defineProject({
+ *   app: {
+ *     default:     () => import('./src/app.js'),
+ *     development: () => import('./src/dev.js'),
+ *     test:        () => import('./src/dev.js'),
+ *   },
+ * })
+ * ```
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the loader for a given env.type. Function-shorthand entries
+ * are returned as-is; object-form entries prefer the type-specific
+ * override and fall through to `default`.
+ */
+export function pickAppLoader(app, envType) {
+    if (typeof app === 'function')
+        return app;
+    return app[envType] ?? app.default;
+}
+const PROJECT_CONFIG_SYMBOL = Symbol('justscale.project-config');
+export function defineProject(config) {
+    return Object.assign(config, { [PROJECT_CONFIG_SYMBOL]: true });
+}
+export function isProjectConfig(value) {
+    return typeof value === 'object' && value !== null && PROJECT_CONFIG_SYMBOL in value;
+}
+/**
+ * Extract the file path argument from a lazy import loader like
+ * `() => import('./src/dev.js')`. Returns null if the loader uses a shape
+ * we can't introspect (computed specifiers, re-exports, dynamic paths).
+ * Shared by `just dev` and `just build` so both resolve the app entry the
+ * same way.
+ */
+export function extractLoaderPath(loader) {
+    const src = loader.toString();
+    const match = src.match(/import\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+    return match?.[1] ?? null;
+}
+/**
+ * `config.app` uses `.js` suffixes even when the source is `.ts` (NodeNext
+ * resolution convention). Resolve to the actual source file that exists on
+ * disk, preferring the `.ts` variant when it's alongside the `.js` path.
+ */
+export function resolveSourcePath(baseDir, loaderPath) {
+    const absolute = resolve(baseDir, loaderPath);
+    if (existsSync(absolute))
+        return absolute;
+    if (absolute.endsWith('.js')) {
+        const tsVariant = absolute.slice(0, -3) + '.ts';
+        if (existsSync(tsVariant))
+            return tsVariant;
+    }
+    return null;
+}
+/**
+ * Resolve the app entry source file for a given env.type. Returns null if
+ * the config doesn't point at a file the filesystem can produce.
+ */
+export function resolveAppEntry(configFileUrl, app, envType) {
+    const loader = pickAppLoader(app, envType);
+    const loaderPath = extractLoaderPath(loader);
+    if (!loaderPath)
+        return null;
+    const configDir = dirname(fileURLToPath(configFileUrl));
+    return resolveSourcePath(configDir, loaderPath);
+}
+//# sourceMappingURL=define-project.js.map

package/dist/cli/define-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-project.js","sourceRoot":"","sources":["../../src/cli/define-project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAgDzC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAa,EACb,OAAwB;IAExB,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,OAAO,GAAG,CAAC;IAC1C,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC;AACrC,CAAC;AAED,MAAM,qBAAqB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAEjE,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,qBAAqB,IAAI,KAAK,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAClE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,UAAkB;IACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC9C,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QAChD,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,aAAqB,EACrB,GAAa,EACb,OAAwB;IAExB,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,OAAO,iBAAiB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAClD,CAAC"}

package/dist/cli/dev-server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dev server — runs the user's app entry with file watching and auto
+ * restart. Skips an explicit build step: tsx transforms TS on the fly,
+ * and `tsx watch` handles restart-on-change natively. In production
+ * users ship compiled JS via `just build` and run `node dist/app.js`.
+ *
+ * Entry selection mirrors `assembleCliApp`: load `justscale.config.ts`,
+ * resolve the active env, look up `config.app[env.type]` (falling back
+ * to `config.app.default`), and extract the file path from the loader.
+ * This way `just dev` in a `type: 'development'` env picks up `dev.ts`
+ * instead of `app.ts`, so pglite / in-memory channel overrides are
+ * hot-reloaded alongside the user's composition.
+ */
+interface DevServerOptions {
+    root: string;
+    log: (msg: string) => void;
+}
+export declare function startDevServer(options: DevServerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=dev-server.d.ts.map

package/dist/cli/dev-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/cli/dev-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsBH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3B;AA+CD,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE7E"}

package/dist/cli/dev-server.js

@@ -0,0 +1,131 @@
+/**
+ * Dev server — runs the user's app entry with file watching and auto
+ * restart. Skips an explicit build step: tsx transforms TS on the fly,
+ * and `tsx watch` handles restart-on-change natively. In production
+ * users ship compiled JS via `just build` and run `node dist/app.js`.
+ *
+ * Entry selection mirrors `assembleCliApp`: load `justscale.config.ts`,
+ * resolve the active env, look up `config.app[env.type]` (falling back
+ * to `config.app.default`), and extract the file path from the loader.
+ * This way `just dev` in a `type: 'development'` env picks up `dev.ts`
+ * instead of `app.ts`, so pglite / in-memory channel overrides are
+ * hot-reloaded alongside the user's composition.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { loadEnvironment } from '../features/environment/load.js';
+import { discover } from './discovery.js';
+import { extractLoaderPath, pickAppLoader, resolveAppEntry } from './define-project.js';
+function findBinDirs(start) {
+    const dirs = [];
+    let current = start;
+    while (true) {
+        const candidate = join(current, 'node_modules', '.bin');
+        if (existsSync(candidate))
+            dirs.push(candidate);
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Legacy fallback: locate the app entry via conventional filenames.
+ * Used only when `justscale.config.ts` is absent or the loader path
+ * couldn't be extracted.
+ */
+function findServeEntry(root) {
+    const candidates = ['src/app.ts', 'src/main.ts', 'src/server.ts', 'src/serve.ts'];
+    for (const candidate of candidates) {
+        const fullPath = join(root, candidate);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+async function pickEntry(root, log) {
+    const result = await discover();
+    if (!result || !result.config.app) {
+        log('[dev] No justscale.config.ts or config.app; falling back to filename search.');
+        return findServeEntry(root);
+    }
+    const env = await loadEnvironment({ from: { url: result.configFileUrl } });
+    const loader = pickAppLoader(result.config.app, env.type);
+    const loaderPath = extractLoaderPath(loader);
+    if (!loaderPath) {
+        log(`[dev] Could not extract an import path from config.app for env.type='${env.type}'. ` +
+            'Loader is not a simple `() => import(\'./src/xyz.js\')`. ' +
+            'Falling back to filename search.');
+        return findServeEntry(root);
+    }
+    const resolved = resolveAppEntry(result.configFileUrl, result.config.app, env.type);
+    if (!resolved) {
+        log(`[dev] config.app[${env.type}] points at '${loaderPath}', but neither that file nor its .ts variant exists.`);
+        return findServeEntry(root);
+    }
+    log(`[dev] env.type='${env.type}' → ${resolved}`);
+    return resolved;
+}
+export async function startDevServer(options) {
+    const { root, log } = options;
+    const entry = await pickEntry(root, log);
+    if (!entry) {
+        log('[dev] No app entry found. Expected a justscale.config.ts with an `app` entry, ' +
+            'or one of src/app.ts, src/main.ts, src/server.ts, src/serve.ts.');
+        process.exit(1);
+    }
+    log(`[dev] Starting ${entry}`);
+    // No `tsx watch` — the kernel starts an in-process HMR file watcher
+    // when NODE_ENV=development, which re-imports changed modules and
+    // calls `container.hotReload()` without restarting the process.
+    // That keeps pglite state, the HTTP listen socket, and lifecycle
+    // instances alive across edits.
+    //
+    // Loader chain: `@justscale/typescript/register` handles process +
+    // proto compilation; `tsx` handles the rest of the TS -> JS transform.
+    //
+    // PATH prepending is required so `tsx` resolves — Node's `spawn` uses
+    // the child's PATH (not the interactive shell's), so the project's
+    // node_modules/.bin must be made visible explicitly.
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const pathPrefix = findBinDirs(root).join(sep);
+    const env = {
+        ...process.env,
+        NODE_ENV: 'development',
+        PATH: pathPrefix
+            ? `${pathPrefix}${sep}${process.env.PATH ?? ''}`
+            : (process.env.PATH ?? ''),
+    };
+    // The `@justscale/hmr/register` observer loader records every file
+    // URL the process loads. The in-process HMR watcher (started by the
+    // kernel when NODE_ENV=development) reads that set to decide which
+    // directories to watch and which service tokens to swap on change.
+    const proc = spawn('node', [
+        '--import',
+        '@justscale/typescript/register',
+        '--import',
+        '@justscale/hmr/register',
+        '--import',
+        'tsx',
+        entry,
+    ], {
+        cwd: root,
+        stdio: 'inherit',
+        env,
+    });
+    const cleanup = () => {
+        if (!proc.killed)
+            proc.kill('SIGTERM');
+    };
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    await new Promise((resolve) => {
+        proc.on('exit', (code) => {
+            process.exitCode = code ?? 0;
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=dev-server.js.map

package/dist/cli/dev-server.js.map

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

package/dist/cli/discovery.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Discovery module — finds project config and package-contributed CLI controllers.
+ *
+ * Used by:
+ * - main.ts (CLI entry point)
+ * - mcp serve command
+ * - any future consumer that needs to discover the project structure
+ */
+import { type ProjectConfig } from './define-project.js';
+export interface ProjectDiscoveryResult {
+    type: 'project';
+    config: ProjectConfig;
+    /** file:// URL of the loaded justscale.config.{ts,js} — used as the
+     * anchor for `loadEnvironment({ from })` so env resolution starts
+     * from the project root, not the (possibly workspace-level) cwd. */
+    configFileUrl: string;
+}
+export type DiscoveryResult = ProjectDiscoveryResult | null;
+/**
+ * Discover a `justscale.config.ts` (defineProject result) in the current
+ * directory. Returns `null` if no config is present — callers fall back to
+ * built-in-only behaviour in that case.
+ */
+export declare function discover(): Promise<DiscoveryResult>;
+/**
+ * Discover CLI controllers from dependencies that have a "justscale" field.
+ */
+export declare function discoverPackageCommands(): Promise<any[]>;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/cli/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAM1E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,aAAa,CAAA;IACrB;;wEAEoE;IACpE,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,IAAI,CAAC;AAW5D;;;;GAIG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAmBzD;AAMD;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CA8C9D"}