@karmaniverous/smoz 0.1.2 → 0.1.3

package/dist/cli/index.cjs

@@ -0,0 +1,1218 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+'use strict';
+
+var fs = require('node:fs');
+var path = require('node:path');
+var commander = require('commander');
+var packageDirectory = require('package-directory');
+var node_url = require('node:url');
+var chokidar = require('chokidar');
+var node_child_process = require('node:child_process');
+var os = require('node:os');
+
+/**
+ * SMOZ CLI: add
+ *
+ * Scaffold a function under app/functions.
+ * Usage spec:
+ * - HTTP:    <eventType>/<segments...>/<method>
+ * - non-HTTP:<eventType>/<segments...>
+ *
+ * Creates:
+ * - HTTP: lambda.ts, handler.ts, openapi.ts
+ * - non-HTTP: lambda.ts, handler.ts
+ *
+ * Idempotent and formatted (uses Prettier if available).
+ */
+const HTTP_METHODS = new Set([
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+    'head',
+    'options',
+    'trace',
+]);
+const toPosix$2 = (p) => p.split(path.sep).join('/');
+const formatMaybe$1 = async (root, filePath, source) => {
+    try {
+        const prettier = (await import('prettier'));
+        const cfg = (await prettier.resolveConfig(root)) ?? {};
+        return prettier.format(source, { ...cfg, filepath: filePath });
+    }
+    catch {
+        return source;
+    }
+};
+const writeIfAbsent$1 = async (outFile, content) => {
+    if (fs.existsSync(outFile))
+        return { created: false };
+    await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+    await fs.promises.writeFile(outFile, content, 'utf8');
+    return { created: true };
+};
+/** True if a segment encodes a path param (:id | {id} | [id]). */
+const isParamSeg = (s) => s.startsWith(':') ||
+    (s.startsWith('{') && s.endsWith('}')) ||
+    (s.startsWith('[') && s.endsWith(']'));
+/** Extract the bare param name from a param segment. */
+const getParamName = (s) => {
+    if (s.startsWith(':'))
+        return s.slice(1);
+    if (s.startsWith('{') && s.endsWith('}'))
+        return s.slice(1, -1);
+    if (s.startsWith('[') && s.endsWith(']'))
+        return s.slice(1, -1);
+    return s;
+};
+/** Normalize a segment for the filesystem (Windows‑safe). */
+const toDirSeg = (s) => isParamSeg(s) ? `[${getParamName(s)}]` : s;
+/** Normalize a segment for API paths (Serverless/OpenAPI‑native). */
+const toPathSeg = (s) => isParamSeg(s) ? `{${getParamName(s)}}` : s;
+const lambdaHttpTemplate = ({ token, basePath, method, }) => `/**
+ * Registration: ${method.toUpperCase()} /${basePath} (public)
+ */
+import { join } from 'node:path';
+
+import { z } from 'zod';
+
+import { app, APP_ROOT_ABS } from '@/app/config/app.config';
+
+export const eventSchema = z.any();
+export const responseSchema = z.any();
+
+export const fn = app.defineFunction({
+  eventType: '${token}',
+  httpContexts: ['public'],
+  method: '${method}',
+  basePath: '${basePath}',
+  contentType: 'application/json',
+  eventSchema,
+  responseSchema,
+  callerModuleUrl: import.meta.url,
+  endpointsRootAbs: join(APP_ROOT_ABS, 'functions', '${token}').replace(/\\\\\\\\/g, '/'),
+});
+`;
+const handlerHttpTemplate = () => `/**
+ * Handler: replace with your business logic.
+ */
+import { z } from 'zod';
+
+import type { responseSchema } from './lambda';
+import { fn } from './lambda';
+
+type Response = z.infer<typeof responseSchema>;
+
+export const handler = fn.handler(async (): Promise<Response> => {
+  return {} as Response;
+});
+`;
+const openapiTemplate = ({ params, pathTemplate, }) => {
+    const paramsBlock = params.length > 0
+        ? `  parameters: [
+${params
+            .map((p) => `    { name: '${p}', in: 'path', required: true, schema: { type: 'string' }, description: 'Path parameter: ${p}' },`)
+            .join('\n')}
+  ],
+`
+        : '';
+    return `/* REQUIREMENTS
+- Define OpenAPI Path Item for the new endpoint.
+*/
+import { eventSchema, fn, responseSchema } from './lambda';
+
+fn.openapi({
+  summary: 'Describe your endpoint',
+  description: 'Describe your endpoint. Path template: ${pathTemplate}.',
+${paramsBlock}  requestBody: {
+    description: 'Request payload.',
+    content: { 'application/json': { schema: eventSchema } },
+  },
+  responses: {
+    200: {
+      description: 'Ok',
+      content: { 'application/json': { schema: responseSchema } },
+    },
+  },
+  tags: [],
+});
+
+export {};
+`;
+};
+const lambdaInternalTemplate = (token) => `/**
+ * Registration: internal ${token} function.
+ */
+import { join } from 'node:path';
+
+import { z } from 'zod';
+
+import { app, APP_ROOT_ABS } from '@/app/config/app.config';
+
+export const eventSchema = z.any();
+export const responseSchema = z.any();
+
+export const fn = app.defineFunction({
+  eventType: '${token}',
+  eventSchema,
+  responseSchema,
+  callerModuleUrl: import.meta.url,
+  endpointsRootAbs: join(APP_ROOT_ABS, 'functions', '${token}').replace(/\\\\\\\\/g, '/'),
+});
+`;
+const handlerInternalTemplate = () => `/**
+ * Handler: replace with your business logic.
+ */
+import { z } from 'zod';
+
+import type { responseSchema } from './lambda';
+import { fn } from './lambda';
+
+type Response = z.infer<typeof responseSchema>;
+
+export const handler = fn.handler(async (_event): Promise<Response> => {
+  void _event;
+  return {} as Response;
+});
+`;
+const runAdd = async (root, spec) => {
+    const parts = spec.split('/').filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error('Invalid spec. Use <eventType>/<segments...>/<method> (HTTP) or <eventType>/<segments...> (non-HTTP).');
+    }
+    const token = parts[0].toLowerCase();
+    const tail = parts[parts.length - 1].toLowerCase();
+    const isHttp = HTTP_METHODS.has(tail);
+    const baseParts = isHttp ? parts.slice(1, -1) : parts.slice(1);
+    if (baseParts.length === 0) {
+        throw new Error('Provide at least one path segment after the eventType.');
+    }
+    const method = isHttp ? tail : undefined;
+    // Normalize param segments for path and filesystem
+    const dirSegs = baseParts.map(toDirSeg);
+    const pathSegs = baseParts.map(toPathSeg);
+    // Base path (Serverless/OpenAPI native, uses {param})
+    const basePathPosix = toPosix$2(pathSegs.join('/'));
+    // Derive path template and param names for OpenAPI hints
+    const paramNames = baseParts.filter(isParamSeg).map(getParamName);
+    const pathTemplate = '/' + pathSegs.join('/');
+    const dir = path.join(root, 'app', 'functions', token, ...dirSegs, ...(method ? [method] : []));
+    const lambdaPath = path.join(dir, 'lambda.ts');
+    const handlerPath = path.join(dir, 'handler.ts');
+    const openapiPath = path.join(dir, 'openapi.ts');
+    // Compute contents
+    const files = [];
+    if (isHttp) {
+        files.push({
+            path: lambdaPath,
+            content: lambdaHttpTemplate({
+                token,
+                basePath: basePathPosix,
+                method: method,
+            }),
+            enabled: true,
+        });
+        files.push({
+            path: handlerPath,
+            content: handlerHttpTemplate(),
+            enabled: true,
+        });
+        files.push({
+            path: openapiPath,
+            content: openapiTemplate({ params: paramNames, pathTemplate }),
+            enabled: true,
+        });
+    }
+    else {
+        files.push({
+            path: lambdaPath,
+            content: lambdaInternalTemplate(token),
+            enabled: true,
+        });
+        files.push({
+            path: handlerPath,
+            content: handlerInternalTemplate(),
+            enabled: true,
+        });
+        files.push({ path: openapiPath, content: '', enabled: false });
+    }
+    const created = [];
+    const skipped = [];
+    for (const f of files) {
+        if (!f.enabled)
+            continue;
+        const formatted = await formatMaybe$1(root, f.path, f.content);
+        const { created: c } = await writeIfAbsent$1(f.path, formatted);
+        if (c)
+            created.push(path.posix.normalize(f.path));
+        else
+            skipped.push(path.posix.normalize(f.path));
+    }
+    return { created, skipped };
+};
+
+/**
+ * serverless-offline runner (dev-only).
+ *
+ * - Provides sane TMP/TEMP/TMPDIR fallbacks to avoid "undefined\\temp\\..." paths.
+ * - Spawns the local Serverless CLI to run "offline start".
+ * - Provides restart/close helpers for the dev orchestrator.
+ * - Avoids unnecessary nullish-coalescing so ESLint doesn't flag conditions.
+ */
+const launchOffline = async (root, opts) => {
+    const slsJs = path.resolve(root, 'node_modules', 'serverless', 'bin', 'serverless.js');
+    const makeCmd = () => {
+        const args = [];
+        let cmd;
+        let shell = false;
+        if (fs.existsSync(slsJs)) {
+            cmd = process.execPath;
+            args.push(slsJs, 'offline', 'start', '--stage', opts.stage, '--httpPort', String(typeof opts.port === 'number' ? opts.port : 0));
+        }
+        else {
+            // Fallback to PATH
+            cmd = process.platform === 'win32' ? 'serverless.cmd' : 'serverless';
+            args.push('offline', 'start', '--stage', opts.stage, '--httpPort', String(typeof opts.port === 'number' ? opts.port : 0));
+            shell = true;
+        }
+        return { cmd, args, shell };
+    };
+    let child = spawnOffline(root, makeCmd(), opts.verbose);
+    const close = async () => new Promise((resolve) => {
+        if (child.killed) {
+            resolve();
+            return;
+        }
+        child.once('exit', () => {
+            resolve();
+        });
+        child.kill('SIGTERM');
+        // Safety timeout
+        setTimeout(() => {
+            resolve();
+        }, 1500);
+    });
+    const restart = async () => {
+        await close();
+        child = spawnOffline(root, makeCmd(), opts.verbose);
+    };
+    return { restart, close };
+};
+const spawnOffline = (root, cmd, verbose) => {
+    // Inherit the parent env, but ensure temp variables are present.
+    // Some toolchains (e.g., tsx/esbuild invoked under offline) interpolate TEMP/TMP,
+    // and if they are undefined, they may create literal "undefined\\temp\\..." paths
+    // relative to CWD. Use os.tmpdir() as a safe fallback.
+    const baseEnv = { ...process.env };
+    const tmp = os.tmpdir();
+    // Cross-platform default
+    if (!baseEnv.TMPDIR)
+        baseEnv.TMPDIR = tmp;
+    // Windows defaults
+    if (process.platform === 'win32') {
+        if (!baseEnv.TEMP)
+            baseEnv.TEMP = tmp;
+        if (!baseEnv.TMP)
+            baseEnv.TMP = tmp;
+        // Some nested toolchains derive cache roots from these when TMP/TEMP are absent
+        if (!baseEnv.LOCALAPPDATA)
+            baseEnv.LOCALAPPDATA = tmp;
+        if (!baseEnv.USERPROFILE)
+            baseEnv.USERPROFILE = tmp;
+    }
+    else {
+        // POSIX: some tools fall back to HOME for caches when TMPDIR isn't used
+        if (!baseEnv.HOME)
+            baseEnv.HOME = tmp;
+    }
+    // Optional diagnostics to verify the child sees sane temp-related envs
+    if (verbose) {
+        const snap = {
+            TMPDIR: baseEnv.TMPDIR,
+            TEMP: baseEnv.TEMP,
+            TMP: baseEnv.TMP,
+            HOME: baseEnv.HOME,
+            USERPROFILE: baseEnv.USERPROFILE,
+            LOCALAPPDATA: baseEnv.LOCALAPPDATA,
+        };
+        process.stdout.write(`[offline] env snapshot: ${JSON.stringify(snap)}\n`);
+    }
+    const child = node_child_process.spawn(cmd.cmd, cmd.args, {
+        cwd: root,
+        shell: cmd.shell,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: baseEnv,
+    });
+    const prefix = '[offline] ';
+    const emit = (buf) => {
+        const text = buf.toString('utf8');
+        if (verbose)
+            process.stdout.write(prefix + text);
+    };
+    const emitErr = (buf) => {
+        const text = buf.toString('utf8');
+        process.stderr.write(prefix + text);
+    };
+    // With stdio: 'pipe', these streams are present
+    child.stdout.on('data', emit);
+    child.stderr.on('data', emitErr);
+    child.on('error', (err) => {
+        process.stderr.write(`${prefix}${err.message}\n`);
+    });
+    return child;
+};
+
+/* OpenAPI one-shot runner: spawn the project-local OpenAPI script via tsx.
+ * - Mirrors the npm script: tsx app/config/openapi && prettier (project-local script already formats).
+ * - Keeps CLI responsibilities minimal; errors bubble via non-zero exit.
+ */
+const findTsxCli = (root) => {
+    // Prefer invoking the JS entry to avoid shell .cmd quirks on Windows.
+    const js = path.resolve(root, 'node_modules', 'tsx', 'dist', 'cli.js');
+    if (fs.existsSync(js)) {
+        return {
+            cmd: process.execPath,
+            args: [js, 'app/config/openapi.ts'],
+            shell: false,
+        };
+    }
+    // Fallback to "tsx" on PATH (may rely on shell resolution).
+    const cmd = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+    return { cmd, args: ['app/config/openapi.ts'], shell: true };
+};
+const runOpenapi = async (root, opts) => {
+    // Detect changes by comparing the pre/post content of app/generated/openapi.json.
+    const outFile = path.resolve(root, 'app', 'generated', 'openapi.json');
+    let before;
+    try {
+        if (fs.existsSync(outFile))
+            before = fs.readFileSync(outFile, 'utf8');
+    }
+    catch {
+        // ignore read errors; treat as absent
+        before = undefined;
+    }
+    const { cmd, args, shell } = findTsxCli(root);
+    if (opts?.verbose) {
+        console.log(`[openapi] ${[cmd, ...args].join(' ')}`);
+    }
+    const res = node_child_process.spawnSync(cmd, args, {
+        cwd: root,
+        stdio: 'inherit',
+        shell,
+    });
+    if (typeof res.status !== 'number' || res.status !== 0) {
+        const code = typeof res.status === 'number' ? String(res.status) : 'unknown';
+        throw new Error(`openapi failed (exit ${code})`);
+    }
+    // Determine whether the file content changed
+    try {
+        if (!fs.existsSync(outFile))
+            return before !== undefined; // deleted vs existed
+        const after = fs.readFileSync(outFile, 'utf8');
+        return before === undefined ? true : after !== before;
+    }
+    catch {
+        // If we cannot read, conservatively report "changed" so callers can refresh.
+        return true;
+    }
+};
+
+/**
+ * SMOZ CLI: register
+ *
+ * Scan app/functions/** for {lambda,openapi,serverless}.ts and generate
+ * side-effect import modules under app/generated/:
+ *  - register.functions.ts
+ *  - register.openapi.ts
+ *  - register.serverless.ts
+ *
+ * Idempotent and formatted (uses Prettier if available).
+ */
+const toPosix$1 = (p) => p.split(path.sep).join('/');
+const withoutTsExt = (p) => p.endsWith('.ts') ? p.slice(0, -3) : p;
+const HEADER = `/* AUTO-GENERATED by smoz register — DO NOT EDIT */
+`;
+const formatMaybe = async (root, filePath, source) => {
+    try {
+        // Resolve Prettier if available in the project
+        const prettier = (await import('prettier'));
+        const cfg = (await prettier.resolveConfig(root)) ?? {};
+        return prettier.format(source, { ...cfg, filepath: filePath });
+    }
+    catch {
+        return source;
+    }
+};
+const writeIfChanged = async (outFile, content) => {
+    try {
+        const prev = await fs.promises.readFile(outFile, 'utf8');
+        if (prev === content)
+            return false;
+    }
+    catch {
+        // file missing — proceed
+    }
+    await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+    await fs.promises.writeFile(outFile, content, 'utf8');
+    return true;
+};
+const walk$1 = async (dir, out = []) => {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+        const p = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await walk$1(p, out);
+        }
+        else if (ent.isFile()) {
+            out.push(p);
+        }
+    }
+    return out;
+};
+const collect = async (root) => {
+    const base = path.join(root, 'app', 'functions');
+    const buckets = { lambda: [], openapi: [], serverless: [] };
+    if (!fs.existsSync(base))
+        return buckets;
+    const files = await walk$1(base);
+    for (const abs of files) {
+        const name = abs.split(path.sep).pop() ?? '';
+        if (name === 'lambda.ts')
+            buckets.lambda.push(abs);
+        if (name === 'openapi.ts')
+            buckets.openapi.push(abs);
+        if (name === 'serverless.ts')
+            buckets.serverless.push(abs);
+    }
+    // stable order
+    buckets.lambda.sort();
+    buckets.openapi.sort();
+    buckets.serverless.sort();
+    return buckets;
+};
+const makeImports = (root, files) => {
+    return files.map((abs) => {
+        const rel = toPosix$1(path.relative(root, abs));
+        const noExt = withoutTsExt(rel);
+        return `import '@/${noExt}';`;
+    });
+};
+const buildFile = (imports) => {
+    if (imports.length === 0)
+        return `${HEADER}\n`;
+    return `${HEADER}\n${imports.join('\n')}\n`;
+};
+const runRegister = async (root) => {
+    const buckets = await collect(root);
+    const lambdaImports = makeImports(root, buckets.lambda);
+    const openapiImports = makeImports(root, buckets.openapi);
+    const serverlessImports = makeImports(root, buckets.serverless);
+    const outDir = path.join(root, 'app', 'generated');
+    const fnsPath = path.join(outDir, 'register.functions.ts');
+    const oaiPath = path.join(outDir, 'register.openapi.ts');
+    const srvPath = path.join(outDir, 'register.serverless.ts');
+    const fns = await formatMaybe(root, fnsPath, buildFile(lambdaImports));
+    const oai = await formatMaybe(root, oaiPath, buildFile(openapiImports));
+    const srv = await formatMaybe(root, srvPath, buildFile(serverlessImports));
+    const wrote = [];
+    if (await writeIfChanged(fnsPath, fns))
+        wrote.push(path.posix.normalize(fnsPath));
+    if (await writeIfChanged(oaiPath, oai))
+        wrote.push(path.posix.normalize(oaiPath));
+    if (await writeIfChanged(srvPath, srv))
+        wrote.push(path.posix.normalize(srvPath));
+    return { wrote };
+};
+
+/* Dev loop orchestrator
+ * - Watches author sources; debounces bursts; runs tasks in order: register → openapi.
+ * - Optional local serving (--local inline|offline).
+ * - Stage/env: seeds process.env with concrete values for the selected stage.
+ */
+const runDev = async (root, opts) => {
+    const verbose = !!opts.verbose;
+    const stage = typeof opts.stage === 'string'
+        ? opts.stage
+        : inferDefaultStage(root, verbose);
+    // Seed env with concrete values for the selected stage.
+    try {
+        await seedEnvForStage(root, stage, verbose);
+    }
+    catch (e) {
+        if (verbose)
+            console.warn('[dev] env seeding warning:', e.message);
+    }
+    const mode = opts.local;
+    const port = typeof opts.port === 'number' ? opts.port : 0;
+    if (verbose) {
+        console.log(`[dev] options: register=${String(opts.register)} ` +
+            `openapi=${String(opts.openapi)} ` +
+            `local=${String(mode)} ` +
+            `stage=${stage} ` +
+            `port=${String(port)}`);
+    }
+    // Single debounced queue
+    let timer;
+    let running = false;
+    let pending = false;
+    // Small executor we can use for both pre-flight and queued runs
+    const executeOnce = async () => {
+        if (running)
+            return { wrote: false, openapiChanged: false };
+        running = true;
+        pending = false;
+        try {
+            let wrote = false;
+            if (opts.register) {
+                const res = await runRegister(root);
+                wrote = res.wrote.length > 0;
+                console.log(res.wrote.length
+                    ? `Updated:\n - ${res.wrote.join('\n - ')}`
+                    : 'No changes.');
+            }
+            let openapiChanged = false;
+            if (opts.openapi) {
+                openapiChanged = await runOpenapi(root, { verbose });
+            }
+            return { wrote, openapiChanged };
+        }
+        catch (e) {
+            console.error('[dev] task error:', e.message);
+            return { wrote: false, openapiChanged: false };
+        }
+        finally {
+            running = false;
+            // If a burst arrived while we were running, schedule again
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (pending)
+                schedule();
+        }
+    };
+    // Local child (if any)
+    let offline;
+    let inlineChild;
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            void (async () => {
+                pending = false;
+                const { wrote, openapiChanged } = await executeOnce();
+                // Local backend refresh
+                if (mode === 'offline') {
+                    // Restart only when route-surface can change (register wrote)
+                    if (wrote && offline) {
+                        if (verbose)
+                            console.log('[dev] restarting serverless-offline (register changed)...');
+                        await offline.restart();
+                    }
+                }
+                else if (mode === 'inline') {
+                    // Restart inline only if something material changed
+                    if (wrote || openapiChanged) {
+                        if (verbose)
+                            console.log('[dev] restarting inline server...');
+                        // inlineChild is created when mode === 'inline'; guard for safety
+                        if (inlineChild) {
+                            await inlineChild.restart();
+                        }
+                    }
+                }
+            })();
+        }, 250);
+    };
+    // Pre-flight: run tasks before launching the local backend to avoid an immediate restart
+    await executeOnce();
+    // Local serving
+    if (mode === 'offline') {
+        offline = await launchOffline(root, { stage, port, verbose });
+    }
+    else if (mode === 'inline') {
+        inlineChild = await launchInline(root, { stage, port, verbose });
+    } // Watch sources
+    const globs = [
+        path.join(root, 'app', 'functions', '**', 'lambda.ts'),
+        path.join(root, 'app', 'functions', '**', 'openapi.ts'),
+        path.join(root, 'app', 'functions', '**', 'serverless.ts'),
+    ];
+    if (verbose)
+        console.log('[dev] watching:', globs.map((g) => path.posix.normalize(g)).join(', '));
+    const watcher = chokidar.watch(globs, {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+    });
+    watcher.on('add', schedule).on('change', schedule).on('unlink', schedule);
+    // Keep process alive until SIGINT
+    await new Promise((resolve) => {
+        const stop = async () => {
+            try {
+                await watcher.close();
+                await offline?.close();
+                await inlineChild?.close();
+            }
+            finally {
+                resolve();
+            }
+        };
+        process.on('SIGINT', () => {
+            void stop();
+        });
+        process.on('SIGTERM', () => {
+            void stop();
+        });
+    });
+};
+const inferDefaultStage = (root, verbose) => {
+    // Prefer “dev”; if app.config.ts is available and we can inspect it cheaply later, expand behavior.
+    // For now, return 'dev' (explicit selection via --stage remains available).
+    if (verbose)
+        console.log('[dev] inferring stage: dev (explicit --stage overrides)');
+    return 'dev';
+};
+const seedEnvForStage = async (root, stage, verbose) => {
+    // Best effort: import the app config to read declared env keys and concrete values.
+    // Preserve existing process.env values; only seed when unset.
+    try {
+        const appConfigUrl = node_url.pathToFileURL(path.resolve(root, 'app', 'config', 'app.config.ts')).href;
+        // Dynamically import the TS module under tsx
+        const mod = (await import(appConfigUrl));
+        const app = mod.app;
+        const stages = mod.stages;
+        const globalKeys = Array.isArray(app?.global?.envKeys)
+            ? app.global.envKeys
+            : [];
+        const stageKeys = Array.isArray(app?.stage?.envKeys)
+            ? app.stage.envKeys
+            : [];
+        const globalParams = (stages?.default).params ?? {};
+        const stageParams = (stages?.[stage]).params ?? {};
+        const seedPair = (key, from) => {
+            if (key in process.env)
+                return;
+            const val = from[key];
+            if (val === undefined)
+                return;
+            if (typeof val === 'string') {
+                process.env[key] = val;
+                if (verbose)
+                    console.log(`[dev] env: ${key}=${val}`);
+                return;
+            }
+            if (typeof val === 'number' || typeof val === 'boolean') {
+                const v = String(val);
+                process.env[key] = v;
+                if (verbose)
+                    console.log(`[dev] env: ${key}=${v}`);
+                return;
+            }
+            // Non-primitive; skip to avoid [object Object] surprise.
+            if (verbose)
+                console.log(`[dev] env: skip ${key} (non-primitive)`);
+        };
+        for (const k of globalKeys) {
+            if (typeof k === 'string') {
+                seedPair(k, globalParams);
+            }
+        }
+        for (const k of stageKeys) {
+            if (typeof k === 'string') {
+                seedPair(k, stageParams);
+            }
+        }
+        // Ensure STAGE itself is present as a last resort
+        if (!process.env.STAGE) {
+            process.env.STAGE = stage;
+            if (verbose)
+                console.log(`[dev] env: STAGE=${stage}`);
+        }
+    }
+    catch {
+        // Fallback: seed STAGE only
+        if (!process.env.STAGE) {
+            process.env.STAGE = stage;
+            if (verbose)
+                console.log(`[dev] env: STAGE=${stage}`);
+        }
+    }
+};
+// Inline local runner: spawn tsx to run a TS server script.
+const launchInline = async (root, opts) => {
+    const { spawn } = await import('node:child_process');
+    const path = await import('node:path');
+    const fs = await import('node:fs');
+    const tsxCli = path.resolve(root, 'node_modules', 'tsx', 'dist', 'cli.js');
+    const entry = path.resolve(root, 'src', 'cli', 'local', 'inline.server.ts');
+    if (!fs.existsSync(entry)) {
+        throw new Error('inline server entry missing: src/cli/local/inline.server.ts');
+    }
+    const args = [tsxCli, entry];
+    if (!fs.existsSync(tsxCli)) {
+        // Fallback to PATH resolution
+        args.shift();
+        args.unshift(process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
+    }
+    else {
+        args.unshift(process.execPath);
+    }
+    const spawnChild = () => spawn(args[0], args.slice(1), {
+        cwd: root,
+        stdio: 'inherit',
+        shell: !args[0].endsWith('.js'),
+        env: {
+            ...process.env,
+            SMOZ_STAGE: opts.stage,
+            SMOZ_PORT: String(opts.port),
+            SMOZ_VERBOSE: opts.verbose ? '1' : '',
+        },
+    });
+    let child = spawnChild();
+    const close = async () => new Promise((resolve) => {
+        // If the process has already exited (exitCode set), resolve immediately.
+        if (child.exitCode !== null) {
+            resolve();
+            return;
+        }
+        child.once('exit', () => {
+            resolve();
+        });
+        child.kill('SIGTERM');
+        setTimeout(() => {
+            resolve();
+        }, 1500);
+    });
+    const restart = async () => {
+        await close();
+        child = spawnChild();
+    };
+    return { close, restart };
+};
+
+/**
+ * smoz init
+ *
+ * Scaffolds a new project from packaged templates.
+ * - Copies ./templates/project/ into the target root (shared boilerplate)
+ * - Copies ./templates/<template>/ into the target root (default: minimal)
+ * - Seeds app/generated/register.*.ts (empty modules) if missing
+ * - Idempotent: copy-if-absent; if a file exists, writes <name>.example alongside
+ * - Additive merge of template manifest (deps/devDeps/scripts) into package.json
+ * - Optional dependency installation via --install[=<pm>]
+ */
+const toPosix = (p) => p.split(path.sep).join('/');
+const writeIfAbsent = async (outFile, content) => {
+    if (fs.existsSync(outFile))
+        return { created: false };
+    await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+    await fs.promises.writeFile(outFile, content, 'utf8');
+    return { created: true };
+};
+const walk = async (dir, out = []) => {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+        const p = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await walk(p, out);
+        }
+        else if (ent.isFile()) {
+            out.push(p);
+        }
+    }
+    return out;
+};
+const resolveTemplatesBase = () => {
+    // Resolve the package root (works both in dev and when installed)
+    const pkgRoot = packageDirectory.packageDirectorySync() ?? process.cwd();
+    return path.resolve(pkgRoot, 'templates');
+};
+const readJson = async (file) => {
+    try {
+        const data = await fs.promises.readFile(file, 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+};
+const writeJson = async (file, obj) => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, JSON.stringify(obj, null, 2), 'utf8');
+};
+const detectPm = (root) => {
+    if (fs.existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(root, 'yarn.lock')))
+        return 'yarn';
+    if (fs.existsSync(path.join(root, 'package-lock.json')))
+        return 'npm';
+    if (fs.existsSync(path.join(root, 'bun.lockb')))
+        return 'bun';
+    const ua = process.env.npm_config_user_agent ?? '';
+    if (ua.includes('pnpm'))
+        return 'pnpm';
+    if (ua.includes('yarn'))
+        return 'yarn';
+    if (ua.includes('bun'))
+        return 'bun';
+    if (ua.includes('npm'))
+        return 'npm';
+    return undefined;
+};
+const runInstall = (root, pm) => {
+    if (!pm)
+        return 'skipped';
+    const known = pm === 'pnpm' || pm === 'yarn' || pm === 'bun' || pm === 'npm';
+    if (!known)
+        return 'unknown-pm';
+    // Spawn with explicit args; avoid tuple inference that widens types.
+    const res = node_child_process.spawnSync(pm, ['install'], {
+        stdio: 'inherit',
+        cwd: root,
+        shell: true,
+    });
+    if (res.status === 0) {
+        const tag = pm === 'pnpm'
+            ? 'ran (pnpm)'
+            : pm === 'yarn'
+                ? 'ran (yarn)'
+                : pm === 'bun'
+                    ? 'ran (bun)'
+                    : 'ran (npm)';
+        return tag;
+    }
+    return 'failed';
+};
+const mergeAdditive = (target, source) => {
+    const merged = [];
+    const mergeKey = (key) => {
+        // Allow possibly-undefined shapes to satisfy lint (no-unnecessary-condition).
+        const src = source[key] ?? {};
+        const dst = target[key] ?? {};
+        const out = { ...dst };
+        let changed = false;
+        for (const [k, v] of Object.entries(src)) {
+            if (!(k in dst)) {
+                out[k] = v;
+                merged.push(`${key}:${k}@${v}`);
+                changed = true;
+            }
+        }
+        if (changed) {
+            target[key] = out;
+        }
+    };
+    mergeKey('dependencies');
+    mergeKey('devDependencies');
+    mergeKey('peerDependencies');
+    const srcScripts = source.scripts ?? {};
+    const dstScripts = target.scripts ?? {};
+    const scriptsOut = { ...dstScripts };
+    for (const [name, script] of Object.entries(srcScripts)) {
+        if (!(name in dstScripts)) {
+            scriptsOut[name] = script;
+            merged.push(`scripts:${name}`);
+        }
+        else if (dstScripts[name] !== script) {
+            const alias = `${name}:smoz`;
+            if (!(alias in dstScripts)) {
+                scriptsOut[alias] = script;
+                merged.push(`scripts:${alias}`);
+            }
+        }
+    }
+    target.scripts = scriptsOut;
+    return merged;
+};
+const copyDirIdempotent = async (srcDir, dstRoot, created, skipped, examples) => {
+    const files = await walk(srcDir);
+    for (const abs of files) {
+        const rel = path.relative(srcDir, abs);
+        const dest = path.resolve(dstRoot, rel);
+        const data = await fs.promises.readFile(abs, 'utf8');
+        if (fs.existsSync(dest)) {
+            const ex = `${dest}.example`;
+            if (!fs.existsSync(ex)) {
+                await writeIfAbsent(ex, data);
+                examples.push(path.posix.normalize(ex));
+            }
+            else {
+                skipped.push(path.posix.normalize(dest));
+            }
+        }
+        else {
+            const { created: c } = await writeIfAbsent(dest, data);
+            if (c)
+                created.push(path.posix.normalize(dest));
+            else
+                skipped.push(path.posix.normalize(dest));
+        }
+    }
+};
+const runInit = async (root, template = 'minimal', opts) => {
+    const created = [];
+    const skipped = [];
+    const examples = [];
+    const merged = [];
+    const templatesBase = resolveTemplatesBase();
+    const srcBase = path.resolve(templatesBase, template);
+    const projectBase = path.resolve(templatesBase, 'project');
+    if (!fs.existsSync(srcBase)) {
+        throw new Error(`Template "${template}" not found under ${toPosix(templatesBase)}.`);
+    }
+    // 1) Copy shared boilerplate (project) first (idempotent)
+    if (fs.existsSync(projectBase)) {
+        await copyDirIdempotent(projectBase, root, created, skipped, examples);
+    }
+    // 2) Copy selected template
+    await copyDirIdempotent(srcBase, root, created, skipped, examples);
+    // Seed app/generated/register.*.ts (empty modules) if missing
+    const genDir = path.resolve(root, 'app', 'generated');
+    const seeds = [
+        {
+            path: path.join(genDir, 'register.functions.ts'),
+            content: `/* AUTO-GENERATED placeholder; will be rewritten by \`smoz register\` */\nexport {};\n`,
+        },
+        {
+            path: path.join(genDir, 'register.openapi.ts'),
+            content: `/* AUTO-GENERATED placeholder; will be rewritten by \`smoz register\` */\nexport {};\n`,
+        },
+        {
+            path: path.join(genDir, 'register.serverless.ts'),
+            content: `/* AUTO-GENERATED placeholder; will be rewritten by \`smoz register\` */\nexport {};\n`,
+        },
+    ];
+    for (const s of seeds) {
+        const { created: c } = await writeIfAbsent(s.path, s.content);
+        if (c)
+            created.push(path.posix.normalize(s.path));
+        else
+            skipped.push(path.posix.normalize(s.path));
+    }
+    // 3) package.json presence (guard or create with --init)
+    const pkgPath = path.join(root, 'package.json');
+    let pkg = await readJson(pkgPath);
+    if (!pkg) {
+        const shouldInit = !!(opts && opts.init);
+        if (shouldInit) {
+            const name = toPosix(root).split('/').pop() ?? 'smoz-app';
+            pkg = {
+                name,
+                private: true,
+                type: 'module',
+                version: '0.0.0',
+                scripts: {},
+            };
+            // Avoid optional chain to satisfy no-unnecessary-condition; normalize to boolean.
+            const dryRunCreate = !!opts.dryRun;
+            if (!dryRunCreate)
+                await writeJson(pkgPath, pkg);
+            created.push(path.posix.normalize(pkgPath));
+        }
+        else {
+            throw new Error('No package.json found. Run "npm init -y" (or re-run with --init) and then "smoz init" again.');
+        }
+    }
+    // 4) Merge manifest (deps/devDeps/scripts) additively
+    const manifestPath = path.resolve(templatesBase, '.manifests', `package.${template}.json`);
+    const manifest = await readJson(manifestPath);
+    if (manifest) {
+        const before = JSON.stringify(pkg);
+        const added = mergeAdditive(pkg, manifest);
+        merged.push(...added);
+        const dryRun = !!(opts && opts.dryRun);
+        if (!dryRun && before !== JSON.stringify(pkg)) {
+            await writeJson(pkgPath, pkg);
+        }
+    }
+    // 5) Optional install
+    let installed = 'skipped';
+    const installOpt = opts ? opts.install : false;
+    // Derive package manager to use (explicit string or detected when true),
+    // then set installed based on presence of a PM.
+    const hasInstallString = typeof installOpt === 'string' && installOpt.trim() !== '';
+    const pm = hasInstallString
+        ? installOpt
+        : installOpt === true
+            ? detectPm(root)
+            : undefined;
+    installed = pm ? runInstall(root, pm) : installed;
+    return { created, skipped, examples, merged, installed };
+};
+
+/**
+ * SMOZ CLI — version/signature + register/add
+ *
+ * - Default: print project signature (version, Node, repo root, stanPath, config presence)
+ * - register: one-shot — generate app/generated/register.*.ts from app/functions/**
+ * - openapi: one-shot — run the project’s OpenAPI builder
+ * - dev: watch loop orchestrator for register/openapi and optional local serving
+ * - add: scaffold a new function skeleton under app/functions
+ */
+const getRepoRoot = () => packageDirectory.packageDirectorySync() ?? process.cwd();
+const readPkg = (root) => {
+    try {
+        const raw = fs.readFileSync(path.join(root, 'package.json'), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+const detectPackageManager = () => {
+    const ua = process.env.npm_config_user_agent ?? '';
+    if (ua.includes('pnpm'))
+        return 'pnpm';
+    if (ua.includes('yarn'))
+        return 'yarn';
+    if (ua.includes('npm'))
+        return 'npm';
+    return ua || undefined;
+};
+const detectStanPath = (root) => {
+    // Keep this conservative; future: read stan.config.* if introduced.
+    const candidate = '.stan';
+    if (fs.existsSync(path.join(root, candidate, 'system', 'stan.system.md'))) {
+        return candidate;
+    }
+    return candidate; // default
+};
+const printSignature = () => {
+    const root = getRepoRoot();
+    const pkg = readPkg(root);
+    const name = pkg.name ?? 'smoz';
+    const version = pkg.version ?? '0.0.0';
+    const pm = detectPackageManager();
+    const stanPath = detectStanPath(root);
+    const hasAppConfig = fs.existsSync(path.join(root, 'app', 'config', 'app.config.ts'));
+    const hasSmozJson = fs.existsSync(path.join(root, 'smoz.config.json'));
+    const hasSmozYaml = fs.existsSync(path.join(root, 'smoz.config.yml')) ||
+        fs.existsSync(path.join(root, 'smoz.config.yaml'));
+    console.log(`${name} v${version}`);
+    console.log(`Node ${process.version}`);
+    console.log(`Repo: ${root}`);
+    console.log(`stanPath: ${stanPath}`);
+    console.log(`app/config/app.config.ts: ${hasAppConfig ? 'found' : 'missing'}`);
+    console.log(`smoz.config.*: ${hasSmozJson || hasSmozYaml ? 'found' : 'absent'}`);
+    if (pm)
+        console.log(`PM: ${pm}`);
+};
+const main = () => {
+    const root = getRepoRoot();
+    const pkg = readPkg(root);
+    const program = new commander.Command();
+    program
+        .name('smoz')
+        .description('SMOZ CLI')
+        .version(pkg.version ?? '0.0.0');
+    program
+        .command('add')
+        .argument('<spec>', 'Add function: HTTP <eventType>/<segments...>/<method> or non-HTTP <eventType>/<segments...>')
+        .description('Scaffold a new function under app/functions')
+        .action(async (spec) => {
+        try {
+            const { created, skipped } = await runAdd(root, spec);
+            console.log(created.length
+                ? `Created:\n - ${created.join('\n - ')}${skipped.length
+                    ? `\nSkipped (exists):\n - ${skipped.join('\n - ')}`
+                    : ''}`
+                : 'Nothing created (files already exist).');
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('init')
+        .description('Scaffold a new SMOZ app from packaged templates (default: minimal)')
+        .option('--template <name>', 'Template name (minimal|full)', 'minimal')
+        .option('--init', 'Create a minimal package.json if missing')
+        .option('-i, --install [pm]', 'Install dependencies (optionally specify pm: npm|pnpm|yarn|bun)')
+        .option('--yes', 'Skip prompts (non-interactive)', false)
+        .option('--dry-run', 'Show planned actions without writing', false)
+        .action(async (opts) => {
+        try {
+            const tpl = typeof opts.template === 'string' ? opts.template : 'minimal';
+            const { created, skipped, examples, merged, installed } = await runInit(root, tpl, opts);
+            console.log([
+                created.length
+                    ? `Created:\n - ${created.join('\n - ')}`
+                    : 'Created: (none)',
+                examples.length
+                    ? `Examples (existing preserved):\n - ${examples.join('\n - ')}`
+                    : undefined,
+                skipped.length
+                    ? `Skipped (exists):\n - ${skipped.join('\n - ')}`
+                    : undefined,
+                merged.length
+                    ? `package.json (additive):\n - ${merged.join('\n - ')}`
+                    : undefined,
+                `Install: ${installed}`,
+            ]
+                .filter(Boolean)
+                .join('\n'));
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('register')
+        .description('Scan app/functions/** and generate app/generated/register.*.ts (one-shot)')
+        .action(async () => {
+        const { wrote } = await runRegister(root);
+        console.log(wrote.length ? `Updated:\n - ${wrote.join('\n - ')}` : 'No changes.');
+    });
+    program
+        .command('openapi')
+        .description('Generate app/generated/openapi.json (one-shot)')
+        .action(async () => {
+        try {
+            await runOpenapi(root, { verbose: true });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('dev')
+        .description('Watch loop: keep registers/openapi fresh; optionally serve HTTP locally')
+        .option('-r, --register', 'Enable register step on change', true)
+        .option('-R, --no-register', 'Disable register step on change')
+        .option('-o, --openapi', 'Enable openapi step on change', true)
+        .option('-O, --no-openapi', 'Disable openapi step on change')
+        .option('-l, --local [mode]', 'Local server mode: inline|offline', 'inline')
+        .option('-s, --stage <name>', 'Stage name (default inferred)')
+        .option('-p, --port <n>', 'Port (0=random)', (v) => Number(v), 0)
+        .option('-v, --verbose', 'Verbose logging', false)
+        .action(async (opts) => {
+        try {
+            await runDev(root, {
+                register: opts.register !== false,
+                openapi: opts.openapi !== false,
+                local: typeof opts.local === 'string'
+                    ? opts.local
+                    : opts.local === false
+                        ? false
+                        : 'inline',
+                ...(typeof opts.stage === 'string' ? { stage: opts.stage } : {}),
+                port: opts.port ?? 0,
+                verbose: !!opts.verbose,
+            });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exitCode = 1;
+        }
+    });
+    // Default action (no subcommand): print version + signature block
+    program.action(() => {
+        printSignature();
+    });
+    program.parse(process.argv);
+};
+main();

package/package.json

@@ -161,7 +161,6 @@
   },
   "scripts": {
     "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
-    "build:cli": "rollup --config cli.rollup.config.ts --configPlugin @rollup/plugin-typescript",
     "changelog": "auto-changelog",
     "deploy": "tsx src/cli/index.ts register && serverless deploy",
     "diagrams": "cd diagrams/src && plantuml -tpng -o ../out -r .",
@@ -186,5 +185,5 @@
     "templates:lint": "eslint --fix -c templates/.check/eslint.templates.config.ts \"templates/**/*.{ts,tsx,js,jsx}\" && eslint --fix --no-ignore templates/.check/eslint.templates.config.ts"
   },
   "type": "module",
-  "version": "0.1.2"
+  "version": "0.1.3"
 }