@karmaniverous/smoz 0.2.0 → 0.2.1

package/README.md

@@ -18,17 +18,41 @@ SMOZ is a small, pragmatic toolkit for authoring AWS Lambda handlers with [Middy
 - HTTP middleware with validation, shaping, errors, CORS, negotiation, and HEAD
 - Non‑HTTP flows stay lean (no middleware overhead)
 
-## Quick links
+## Quick start (from zero)
+
+From an empty directory:
+
+```bash
+npx @karmaniverous/smoz init -i
+npx smoz dev -p 3000
+```
+
+- The first command scaffolds a new app and installs dependencies (including a local `smoz` bin).
+- The second command starts the inline local backend and keeps registers + OpenAPI fresh.
+- Open http://localhost:3000/openapi in your browser.
 
+Prefer `serverless‑offline`?
+
+```bash
+npx smoz dev -l offline -p 3000
+```
+
+Add your first endpoint (avoid clashing with the template’s hello):
+
+```bash
+npx smoz add rest/foo/get
+```
+
+## Quick links
+ 
 - [Overview](https://docs.karmanivero.us/smoz/documents/Overview.html)
 - [Why smoz?](https://docs.karmanivero.us/smoz/documents/Why_smoz_.html)
 - [Getting started](https://docs.karmanivero.us/smoz/documents/Getting_started.html)
 - [10-minute tour](https://docs.karmanivero.us/smoz/documents/10%E2%80%91minute_tour.html)
-- [HTTP MIddleware](https://docs.karmanivero.us/smoz/documents/HTTP_middleware.html)
+- [HTTP Middleware](https://docs.karmanivero.us/smoz/documents/HTTP_middleware.html)
 - [Recipes](https://docs.karmanivero.us/smoz/documents/Recipes.html)
   - [SQS function](https://docs.karmanivero.us/smoz/documents/Recipes.SQS_function.html)
-  - [Contexts + Cognito authorizer](https://docs.karmanivero.us/smoz/documents/Recipes.Contexts_+_Cognito_authorizer.html)
-  - [Custom middleware insertion](https://docs.karmanivero.us/smoz/documents/Recipes.Custom_middleware_insertion.html)
+  - [Contexts + Cognito authorizer](https://docs.karmanivero.us/smoz/documents/Recipes.Contexts_+_Cognito_authorizer.html)  - [Custom middleware insertion](https://docs.karmanivero.us/smoz/documents/Recipes.Custom_middleware_insertion.html)
   - [Per‑function env](<https://docs.karmanivero.us/smoz/documents/Recipes.Per%E2%80%91function_env_(fnEnvKeys).html>)
   - [Observability](<https://docs.karmanivero.us/smoz/documents/Recipes.Observability_(requestId_header).html>)
   - [Troubleshooting](https://docs.karmanivero.us/smoz/documents/Recipes.Troubleshooting.html)

package/dist/cli/index.cjs

@@ -792,16 +792,6 @@ const launchInline = async (root, opts) => {
     return { close, restart };
 };
 
-/**
- * smoz init
- *
- * Scaffolds a new project from packaged templates.
- * - Copies ./templates/<template>/ into the target root (default: default)
- * - 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 };
@@ -809,25 +799,6 @@ const writeIfAbsent = async (outFile, content) => {
     await fs.promises.writeFile(outFile, content, 'utf8');
     return { created: true };
 };
-const askConflict = async (rl, filePath) => {
-    const q = `File exists: ${toPosix(filePath)}\n` +
-        `Choose: [o]verwrite, [e]xample, [s]kip, [O]verwrite all, [E]xample all, [S]kip all: `;
-    // Single key selection for simplicity
-    const ans = (await rl.question(q)).trim();
-    if (/^o$/.test(ans))
-        return 'overwrite';
-    if (/^e$/.test(ans))
-        return 'example';
-    if (/^s$/.test(ans))
-        return 'skip';
-    if (/^O$/.test(ans))
-        return 'all-overwrite';
-    if (/^E$/.test(ans))
-        return 'all-example';
-    if (/^S$/.test(ans))
-        return 'all-skip';
-    return 'example';
-};
 const walk = async (dir, out = []) => {
     const entries = await fs.promises.readdir(dir, { withFileTypes: true });
     for (const ent of entries) {
@@ -841,15 +812,6 @@ const walk = async (dir, out = []) => {
     }
     return out;
 };
-const resolveTemplatesBase = () => {
-    // Resolve the templates folder from the CLI package install root,
-    // not the caller’s project root. This makes --template <name> work
-    // consistently whether smoz is run from a consuming app or this repo.
-    // Anchor discovery to this module’s directory.
-    const here = path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
-    const pkgRoot = packageDirectory.packageDirectorySync({ cwd: here }) ?? process.cwd(); // conservative fallback
-    return path.resolve(pkgRoot, 'templates');
-};
 const readJson = async (file) => {
     try {
         const data = await fs.promises.readFile(file, 'utf8');
@@ -863,6 +825,79 @@ 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 askConflict = async (rl, filePath) => {
+    const q = `File exists: ${filePath}\n` +
+        `Choose: [o]verwrite, [e]xample, [s]kip, ` +
+        `[O]verwrite all, [E]xample all, [S]kip all: `;
+    const ans = (await rl.question(q)).trim();
+    if (/^o$/.test(ans))
+        return 'overwrite';
+    if (/^e$/.test(ans))
+        return 'example';
+    if (/^s$/.test(ans))
+        return 'skip';
+    if (/^O$/.test(ans))
+        return 'all-overwrite';
+    if (/^E$/.test(ans))
+        return 'all-example';
+    if (/^S$/.test(ans))
+        return 'all-skip';
+    return 'example';
+};
+const copyDirWithConflicts = async (srcDir, dstRoot, created, skipped, examples, opts) => {
+    const files = await walk(srcDir);
+    let sticky;
+    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 { created: c } = await writeIfAbsent(dest, data);
+            if (c)
+                created.push(path.posix.normalize(dest));
+            else
+                skipped.push(path.posix.normalize(dest));
+            continue;
+        }
+        // Conflict flow
+        let decision = opts.conflict === 'ask' ? 'example' : opts.conflict;
+        if (opts.conflict === 'ask' && opts.rl && !sticky) {
+            const ans = await askConflict(opts.rl, path.posix.normalize(dest));
+            if (ans === 'all-overwrite') {
+                sticky = 'overwrite';
+            }
+            else if (ans === 'all-example') {
+                sticky = 'example';
+            }
+            else if (ans === 'all-skip') {
+                sticky = 'skip';
+            }
+            else {
+                decision = ans;
+            }
+        }
+        if (sticky)
+            decision = sticky;
+        if (decision === 'overwrite') {
+            await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+            await fs.promises.writeFile(dest, data, 'utf8');
+            created.push(path.posix.normalize(dest));
+        }
+        else if (decision === 'example') {
+            const ex = `${dest}.example`;
+            const { created: c } = await writeIfAbsent(ex, data);
+            if (c)
+                examples.push(path.posix.normalize(ex));
+            else
+                skipped.push(path.posix.normalize(ex));
+        }
+        else {
+            skipped.push(path.posix.normalize(dest));
+        }
+    }
+};
+
 const detectPm = (root) => {
     if (fs.existsSync(path.join(root, 'pnpm-lock.yaml')))
         return 'pnpm';
@@ -889,7 +924,6 @@ const runInstall = (root, pm) => {
     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,
@@ -907,10 +941,10 @@ const runInstall = (root, pm) => {
     }
     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 };
@@ -948,54 +982,71 @@ const mergeAdditive = (target, source) => {
     target.scripts = scriptsOut;
     return merged;
 };
-const copyDirWithConflicts = async (srcDir, dstRoot, created, skipped, examples, opts) => {
-    const files = await walk(srcDir);
-    let sticky;
-    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 { created: c } = await writeIfAbsent(dest, data);
-            if (c)
-                created.push(path.posix.normalize(dest));
-            else
-                skipped.push(path.posix.normalize(dest));
-            continue;
-        }
-        // Conflict
-        let decision = opts.conflict === 'ask' ? 'example' : opts.conflict;
-        if (opts.conflict === 'ask' && opts.rl && !sticky) {
-            const ans = await askConflict(opts.rl, dest);
-            if (ans === 'all-overwrite') {
-                sticky = 'overwrite';
-            }
-            else if (ans === 'all-example') {
-                sticky = 'example';
-            }
-            else if (ans === 'all-skip') {
-                sticky = 'skip';
-            }
-            else {
-                decision = ans;
-            }
-        }
-        if (sticky)
-            decision = sticky;
-        if (decision === 'overwrite') {
-            await fs.promises.writeFile(dest, data, 'utf8');
-            created.push(path.posix.normalize(dest));
-        }
-        else if (decision === 'example') {
-            const ex = `${dest}.example`;
-            await writeIfAbsent(ex, data);
-            examples.push(path.posix.normalize(ex));
-        }
-        else {
-            skipped.push(path.posix.normalize(dest));
+/**
+ * Ensure a runtime dependency on @karmaniverous/smoz is present in the
+ * target manifest, using a caret version derived from the toolkit package.
+ * Returns the merge descriptor string when added, else undefined.
+ */
+const ensureToolkitDependency = async (targetPkg, templatesBase) => {
+    try {
+        const toolkitRoot = path.dirname(templatesBase);
+        const toolkitPkg = await readJson(path.join(toolkitRoot, 'package.json'));
+        const verRaw = toolkitPkg?.version?.trim();
+        const depVersion = verRaw ? `^${verRaw}` : '^0.0.0';
+        const deps = targetPkg.dependencies ?? {};
+        if (!deps['@karmaniverous/smoz']) {
+            targetPkg.dependencies ??=
+                {};
+            targetPkg.dependencies['@karmaniverous/smoz'] = depVersion;
+            return `dependencies:@karmaniverous/smoz@${depVersion}`;
         }
     }
+    catch {
+        // best-effort; ignore
+    }
+    return undefined;
 };
+
+/**
++ * Resolve the packaged templates root from the CLI install location,
+ * not the caller's project root. This makes -t <name> work both from
+ * a consuming app and from this repository.
++ */
+const resolveTemplatesBase = () => {
+    const here = path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
+    const pkgRoot = packageDirectory.packageDirectorySync({ cwd: here }) ?? process.cwd();
+    return path.resolve(pkgRoot, 'templates');
+};
+const toPosix = (p) => 
+// local helper for path presentation (not used for FS operations)
+p.replace(/\\/g, '/');
+
+const seedRegisterPlaceholders = async (root) => {
+    const genDir = path.join(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',
+        },
+    ];
+    const created = [];
+    const skipped = [];
+    for (const s of seeds) {
+        const { created: c } = await writeIfAbsent(s.path, s.content);
+        (c ? created : skipped).push(path.posix.normalize(s.path));
+    }
+    return { created, skipped };
+};
+
+const toPosixSep = (p) => p.split(path.sep).join('/');
 const runInit = async (root, template = 'default', opts) => {
     const created = [];
     const skipped = [];
@@ -1003,7 +1054,7 @@ const runInit = async (root, template = 'default', opts) => {
     const merged = [];
     const optAll = opts ?? {};
     const templatesBase = resolveTemplatesBase();
-    // Resolve template source: named template (default/minimal/full) or filesystem path
+    // Resolve template source: named template or filesystem path
     const templateIsPath = fs.existsSync(template) && (await fs.promises.stat(template)).isDirectory();
     const srcBase = templateIsPath
         ? path.resolve(template)
@@ -1012,9 +1063,9 @@ const runInit = async (root, template = 'default', opts) => {
     if (!fs.existsSync(srcBase)) {
         throw new Error(`Template "${template}" not found (path or name). Tried: ${toPosix(srcBase)}.`);
     }
-    // 1) Copy shared boilerplate (project) first (idempotent)
+    // 1) Copy shared project boilerplate
     if (fs.existsSync(projectBase)) {
-        const rl = optAll.yes
+        const rl = optAll.yes === true
             ? undefined
             : promises.createInterface({ input: node_process.stdin, output: node_process.stdout, terminal: true });
         let policy;
@@ -1027,12 +1078,11 @@ const runInit = async (root, template = 'default', opts) => {
             ? { conflict: policy, rl }
             : { conflict: policy };
         await copyDirWithConflicts(projectBase, root, created, skipped, examples, copyOpts);
-        if (rl)
-            rl.close();
+        rl?.close();
     }
     // 2) Copy selected template
     {
-        const rl = optAll.yes
+        const rl = optAll.yes === true
             ? undefined
             : promises.createInterface({ input: node_process.stdin, output: node_process.stdout, terminal: true });
         let policy;
@@ -1045,12 +1095,9 @@ const runInit = async (root, template = 'default', opts) => {
             ? { conflict: policy, rl }
             : { conflict: policy };
         await copyDirWithConflicts(srcBase, root, created, skipped, examples, copyOpts);
-        if (rl)
-            rl.close();
+        rl?.close();
     }
-    // 2.5) Convert template 'gitignore' into real '.gitignore'
-    // NPM often excludes '.gitignore' from published packages; shipping 'gitignore'
-    // and converting here ensures downstream projects get a proper .gitignore.
+    // 2.5) Convert template 'gitignore' into a real '.gitignore'
     try {
         const giSrc = path.join(root, 'gitignore');
         const giDot = path.join(root, '.gitignore');
@@ -1060,8 +1107,6 @@ const runInit = async (root, template = 'default', opts) => {
                 created.push(path.posix.normalize(giDot));
             }
             else {
-                // Both exist: preserve the template as an example (if not already present),
-                // then remove the extra 'gitignore' to avoid clutter.
                 const example = path.join(root, 'gitignore.example');
                 if (!fs.existsSync(example)) {
                     const data = await fs.promises.readFile(giSrc, 'utf8');
@@ -1073,36 +1118,19 @@ const runInit = async (root, template = 'default', opts) => {
         }
     }
     catch {
-        // best-effort; ignore conversion errors
+        // best-effort
     }
-    // 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));
+    // Seed app/generated/register.* placeholders
+    {
+        const res = await seedRegisterPlaceholders(root);
+        created.push(...res.created);
+        skipped.push(...res.skipped);
     }
     // 3) package.json presence (create when missing)
     const pkgPath = path.join(root, 'package.json');
     let pkg = await readJson(pkgPath);
     if (!pkg) {
-        const name = toPosix(root).split('/').pop() ?? 'smoz-app';
+        const name = toPosixSep(root).split('/').pop() ?? 'smoz-app';
         pkg = {
             name,
             private: true,
@@ -1110,33 +1138,39 @@ const runInit = async (root, template = 'default', opts) => {
             version: '0.0.0',
             scripts: {},
         };
-        const dryRunCreate = Boolean(optAll.dryRun);
-        if (!dryRunCreate)
+        if (!optAll.dryRun)
             await writeJson(pkgPath, pkg);
         created.push(path.posix.normalize(pkgPath));
-    } // 4) Merge manifest (deps/devDeps/scripts) additively
-    // Prefer a real package.json in the template; fallback to legacy manifests if absent.
+    }
+    // 4) Merge manifest additively (prefer template's embedded package.json)
     const templatePkgPath = path.resolve(srcBase, 'package.json');
     const manifest = fs.existsSync(templatePkgPath)
         ? await readJson(templatePkgPath)
         : await readJson(path.resolve(templatesBase, '.manifests', `package.${template}.json`));
+    let pkgChanged = false;
     if (manifest) {
-        const before = JSON.stringify(pkg);
         const added = mergeAdditive(pkg, manifest);
-        merged.push(...added);
-        const dryRun = Boolean(optAll.dryRun);
-        if (!dryRun && before !== JSON.stringify(pkg)) {
-            await writeJson(pkgPath, pkg);
+        if (added.length > 0) {
+            pkgChanged = true;
+            merged.push(...added);
         }
     }
+    // 4.5) Ensure runtime dependency on @karmaniverous/smoz is present
+    {
+        const injected = await ensureToolkitDependency(pkg, templatesBase);
+        if (injected) {
+            merged.push(injected);
+            pkgChanged = true;
+        }
+    }
+    if (!optAll.dryRun && pkgChanged)
+        await writeJson(pkgPath, pkg);
     // 5) Optional install
     let installed = 'skipped';
-    // Install policy:
+    // Policy:
     // -y implies auto install unless --no-install
     const installOpt = optAll.install ?? false;
     const impliedAuto = optAll.yes === true && optAll.noInstall !== true && installOpt !== 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
@@ -1144,13 +1178,7 @@ const runInit = async (root, template = 'default', opts) => {
             ? detectPm(root)
             : undefined;
     installed = pm ? runInstall(root, pm) : installed;
-    return {
-        created,
-        skipped,
-        examples,
-        merged,
-        installed,
-    };
+    return { created, skipped, examples, merged, installed };
 };
 
 /**

package/package.json

@@ -13,7 +13,6 @@
     "url": "https://github.com/karmaniverous/smoz/issues"
   },
   "dependencies": {
-    "@karmaniverous/cached-axios": "^0.2.0",
     "@middy/core": "^6.4.5",
     "@middy/http-content-negotiation": "^6.4.5",
     "@middy/http-cors": "^6.4.5",
@@ -24,11 +23,11 @@
     "@middy/http-response-serializer": "^6.4.5",
     "aws-lambda": "^1.0.7",
     "chokidar": "^4.0.3",
-    "commander": "^14.0.0",
+    "commander": "^14.0.1",
     "http-errors": "^2.0.0",
     "package-directory": "^8.1.0",
     "radash": "^12.1.1",
-    "zod": "^4.1.6"
+    "zod": "^4.1.8"
   },
   "description": "John Galt Services back end.",
   "devDependencies": {
@@ -48,8 +47,7 @@
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "fs-extra": "^11.3.1",
     "knip": "^5.63.1",
-    "lefthook": "^1.12.4",
-    "orval": "^7.11.2",
+    "lefthook": "^1.13.0",
     "pkg-dir": "^9.0.0",
     "prettier": "^3.6.2",
     "release-it": "^19.0.4",
@@ -167,7 +165,6 @@
     "docs": "typedoc",
     "domain:create": "serverless create_domain",
     "domain:delete": "serverless delete_domain",
-    "generate": "cd services/activecampaign && orval",
     "knip": "knip",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
@@ -185,5 +182,5 @@
     "templates:lint": "eslint --fix -c templates/default/eslint.config.ts \"templates/default/**/*.{ts,tsx,js,jsx}\" && eslint --fix templates/default/eslint.config.ts"
   },
   "type": "module",
-  "version": "0.2.0"
+  "version": "0.2.1"
 }