clispark 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Mohn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# clispark
+
+Interactive scaffolding tool for new CLI projects. Run `npx clispark` to generate a new, ready-to-run TypeScript CLI project with consistent logging, error handling, and command structure — no manual setup required.
+
+## Status
+
+🚧 **Work in progress — not yet published to npm.**
+
+| Milestone | Description | Status |
+| --- | --- | --- |
+| M1 | Generator scaffold (wizard, package-name availability check) | ✅ Done |
+| M2 | Project-scaffold engine (file generation, git init, install & build) | ✅ Done |
+| M2.5 | Generator's own logging & error handling (dogfooding) | ✅ Done |
+| M3 | Core runtime features in generated boilerplate (auto command registration, logging, error handling, testing, example command) | ✅ Done |
+| M4 | Private registry support (`.npmrc` generation, wired into scaffold's own `npm install`) | ✅ Done |
+| M5 | Documentation (`ARCHITECTURE.md`) & release automation (CI, Conventional-Commits versioning, npm publish pipeline) | ✅ Done — first real release pending |
+| M6 | Update mechanism for already-generated projects | 🔜 Next |
+
+## Usage
+
+Once published, running the generator will look like this:
+
+```bash
+npx clispark
+```
+
+The wizard asks a few questions (project name, work/private profile, registry URL if applicable), checks the chosen package name's availability, then scaffolds a new directory with a ready-to-run project — `git init`, `npm install`, and `npm run build` all happen automatically. If a custom registry URL was given, an `.npmrc` pointing at it is generated too, so the install (and every future one) uses it automatically.
+
+## What you get
+
+Every generated project includes:
+
+- **oclif-based CLI structure** with convention-based command discovery — drop a file in `src/commands/`, no manual registration needed
+- **Structured logging** (`pino`, one log file per invocation in an OS-appropriate log directory) that automatically covers every command
+- **Consistent error handling** with no opt-out — clean `Error: <message>` output on failure, full stack trace captured in the log file
+- **A working test setup** (`vitest` + `@oclif/test`) with an example test to copy from
+- **A first example command** (`hello`) as a starting point for your own commands
+- **A clean build pipeline** (`tsup`) producing a directly runnable binary
+
+## Tech stack
+
+**Generator itself (`clispark`):** TypeScript, [commander](https://github.com/tj/commander.js) (CLI structure), [@clack/prompts](https://github.com/bombshell-dev/clack) (interactive wizard), `cross-spawn` (cross-platform shelling out to git/npm), `pino` + `env-paths` (own logging), `tsup` + `vitest`.
+
+**Generated boilerplate:** TypeScript, [oclif](https://oclif.io/) (command framework), `pino` + `env-paths` (logging), `tsup` (build), `vitest` + `@oclif/test` (testing).
+
+## Releases
+
+Releases are automated via [release-please](https://github.com/googleapis/release-please): every commit to `master` follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` → minor, `fix:` → patch, `BREAKING CHANGE` → major), and release-please maintains a running "Release PR" with the version bump and changelog. Merging that PR creates a GitHub Release, which triggers the `publish.yml` workflow: it re-runs the full CI suite (tests, typecheck, build, security audit, a scaffold smoke test) against the release commit, then publishes to npm.
+
+CI (`ci.yml`) runs on every push/PR: unit tests, typecheck, build, `npm audit --audit-level=high` (blocking on high/critical findings, which are also tracked as GitHub issues), and an end-to-end scaffold smoke test that generates a real project and runs its own test suite — the same kind of check previously done manually for each milestone.
+
+## Development notes
+
+This project is being built with the help of [Claude](https://claude.com/claude-code). Implementation plans are written before coding starts and committed alongside the code under [`docs/superpowers/plans/`](docs/superpowers/plans/), so the reasoning and step-by-step approach behind each milestone stays visible in version control.
+
+Planning and execution follow the [Superpowers](https://github.com/obra/superpowers) skill set for Claude Code (brainstorming → writing-plans → subagent-driven-development) — credit to [obra](https://github.com/obra) for that workflow.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { createRequire } from "module";
+import path3 from "path";
+import { Command } from "commander";
+
+// src/wizard.ts
+import { intro, outro, text, select, log, isCancel, cancel } from "@clack/prompts";
+
+// src/registry.ts
+var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+async function checkPackageNameAvailability(name, registryUrl = DEFAULT_REGISTRY_URL) {
+  const url = `${registryUrl.replace(/\/$/, "")}/${encodeURIComponent(name)}`;
+  try {
+    const response = await fetch(url);
+    if (response.status === 404) return "available";
+    if (response.status === 200) return "taken";
+    return "unverified";
+  } catch {
+    return "unverified";
+  }
+}
+
+// src/wizard.ts
+var defaultDeps = {
+  checkAvailability: checkPackageNameAvailability
+};
+function exitIfCancelled(value) {
+  if (isCancel(value)) {
+    cancel("Operation cancelled.");
+    process.exit(1);
+  }
+}
+function validateProjectName(value) {
+  if (!value || value.trim().length === 0) return "Project name is required.";
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(value)) {
+    return "Use lowercase letters and numbers, with single hyphens between words (no leading, trailing, or repeated hyphens).";
+  }
+  return void 0;
+}
+async function runWizard(deps = defaultDeps) {
+  intro("clispark \u2014 scaffold a new CLI project");
+  const nameValue = await text({
+    message: "Project name",
+    validate: validateProjectName
+  });
+  exitIfCancelled(nameValue);
+  let projectName = nameValue;
+  const profileValue = await select({
+    message: "Is this a work or private project?",
+    options: [
+      { value: "private", label: "Private" },
+      { value: "work", label: "Work" }
+    ]
+  });
+  exitIfCancelled(profileValue);
+  const profile = profileValue;
+  let registryUrl = DEFAULT_REGISTRY_URL;
+  if (profile === "work") {
+    const registryValue = await text({
+      message: "Custom npm registry URL (leave empty for npmjs.org)",
+      placeholder: DEFAULT_REGISTRY_URL,
+      defaultValue: DEFAULT_REGISTRY_URL
+    });
+    exitIfCancelled(registryValue);
+    registryUrl = registryValue || DEFAULT_REGISTRY_URL;
+  }
+  let nameAvailability = await deps.checkAvailability(projectName, registryUrl);
+  while (nameAvailability === "taken") {
+    log.warn(`"${projectName}" is already taken on ${registryUrl}. Please choose a different name.`);
+    const retryValue = await text({
+      message: "Project name",
+      validate: validateProjectName
+    });
+    exitIfCancelled(retryValue);
+    projectName = retryValue;
+    nameAvailability = await deps.checkAvailability(projectName, registryUrl);
+  }
+  if (nameAvailability === "unverified") {
+    log.warn(`Could not verify availability of "${projectName}" on ${registryUrl}. Continuing anyway.`);
+  }
+  outro(`Ready to scaffold "${projectName}".`);
+  return { projectName, profile, registryUrl, nameAvailability };
+}
+
+// src/scaffold.ts
+import spawn from "cross-spawn";
+import { fileURLToPath } from "url";
+import path from "path";
+import { cp, readdir, readFile, rename, writeFile } from "fs/promises";
+var TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates", "base");
+async function assertTargetDirIsUsable(targetDir) {
+  let entries;
+  try {
+    entries = await readdir(targetDir);
+  } catch {
+    return;
+  }
+  if (entries.length > 0) {
+    throw new Error(`Directory "${targetDir}" already exists and is not empty.`);
+  }
+}
+async function replacePlaceholder(filePath, projectName) {
+  const content = (await readFile(filePath, "utf8")).replaceAll("{{projectName}}", projectName);
+  await writeFile(filePath, content);
+}
+async function copyTemplate(options) {
+  const { projectName, targetDir, registryUrl } = options;
+  await assertTargetDirIsUsable(targetDir);
+  await cp(TEMPLATE_DIR, targetDir, { recursive: true });
+  await rename(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
+  await replacePlaceholder(path.join(targetDir, "package.json"), projectName);
+  await replacePlaceholder(path.join(targetDir, "README.md"), projectName);
+  await replacePlaceholder(path.join(targetDir, "src", "logger.ts"), projectName);
+  await replacePlaceholder(path.join(targetDir, "ARCHITECTURE.md"), projectName);
+  if (registryUrl && registryUrl !== DEFAULT_REGISTRY_URL) {
+    await writeFile(path.join(targetDir, ".npmrc"), `registry=${registryUrl}
+`);
+  }
+}
+async function defaultRunCommand(command, args, cwd) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Command "${command} ${args.join(" ")}" exited with code ${code}`));
+      }
+    });
+  });
+}
+var defaultScaffoldDeps = { runCommand: defaultRunCommand };
+async function scaffoldProject(options, deps = defaultScaffoldDeps) {
+  await copyTemplate(options);
+  const { targetDir } = options;
+  await deps.runCommand("git", ["init"], targetDir);
+  await deps.runCommand("git", ["add", "-A"], targetDir);
+  await deps.runCommand("git", ["commit", "-m", "chore: initial scaffold from clispark"], targetDir);
+  await deps.runCommand("npm", ["install"], targetDir);
+  await deps.runCommand("npm", ["run", "build"], targetDir);
+}
+
+// src/logger.ts
+import { randomBytes } from "crypto";
+import { mkdirSync } from "fs";
+import path2 from "path";
+import envPaths from "env-paths";
+import pino from "pino";
+var paths = envPaths("clispark", { suffix: "" });
+function buildLogFileName(commandName) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "-");
+  const suffix = randomBytes(3).toString("hex");
+  return `${commandName}-${timestamp}-${suffix}.log`;
+}
+function createLogger(commandName, logDir = paths.log) {
+  mkdirSync(logDir, { recursive: true });
+  const logFilePath = path2.join(logDir, buildLogFileName(commandName));
+  const logger = pino(pino.destination({ dest: logFilePath, sync: true }));
+  return { logger, logFilePath };
+}
+function withLogging(commandName, action, logDir = paths.log) {
+  return async () => {
+    let handle;
+    try {
+      handle = createLogger(commandName, logDir);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`
+\u2716 ${message}`);
+      process.exit(1);
+      return;
+    }
+    const { logger, logFilePath } = handle;
+    logger.info({ command: commandName }, "started");
+    try {
+      await action(logger);
+      logger.info({ command: commandName }, "completed");
+    } catch (error) {
+      logger.error({ command: commandName, err: error }, "failed");
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`
+\u2716 ${message}`);
+      console.error(`Details: ${logFilePath}`);
+      process.exit(1);
+    }
+  };
+}
+
+// src/cli.ts
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var program = new Command();
+program.name("clispark").description("Interactive scaffolding tool for new CLI projects").version(pkg.version);
+program.action(
+  withLogging("scaffold", async (logger) => {
+    const answers = await runWizard();
+    const targetDir = path3.join(process.cwd(), answers.projectName);
+    logger.info({ projectName: answers.projectName, targetDir }, "scaffold started");
+    await scaffoldProject({ projectName: answers.projectName, targetDir, registryUrl: answers.registryUrl });
+    logger.info({ projectName: answers.projectName }, "scaffold completed");
+    console.log(`
+Done! Your new CLI project is ready at ${targetDir}`);
+  })
+);
+program.parseAsync(process.argv).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/wizard.ts","../src/registry.ts","../src/scaffold.ts","../src/logger.ts"],"sourcesContent":["// src/cli.ts\r\nimport { createRequire } from 'node:module';\r\nimport path from 'node:path';\r\nimport { Command } from 'commander';\r\nimport { runWizard } from './wizard.js';\r\nimport { scaffoldProject } from './scaffold.js';\r\nimport { withLogging } from './logger.js';\r\n\r\nconst require = createRequire(import.meta.url);\r\nconst pkg = require('../package.json') as { version: string };\r\n\r\nconst program = new Command();\r\n\r\nprogram\r\n  .name('clispark')\r\n  .description('Interactive scaffolding tool for new CLI projects')\r\n  .version(pkg.version);\r\n\r\nprogram.action(\r\n  withLogging('scaffold', async (logger) => {\r\n    const answers = await runWizard();\r\n    const targetDir = path.join(process.cwd(), answers.projectName);\r\n\r\n    logger.info({ projectName: answers.projectName, targetDir }, 'scaffold started');\r\n    await scaffoldProject({ projectName: answers.projectName, targetDir, registryUrl: answers.registryUrl });\r\n    logger.info({ projectName: answers.projectName }, 'scaffold completed');\r\n\r\n    console.log(`\\nDone! Your new CLI project is ready at ${targetDir}`);\r\n  }),\r\n);\r\n\r\nprogram.parseAsync(process.argv).catch((error: unknown) => {\r\n  console.error(error);\r\n  process.exit(1);\r\n});\r\n","// src/wizard.ts\r\nimport { intro, outro, text, select, log, isCancel, cancel } from '@clack/prompts';\r\nimport { checkPackageNameAvailability, DEFAULT_REGISTRY_URL } from './registry.js';\r\nimport type { Profile, WizardAnswers } from './types.js';\r\n\r\nexport interface WizardDeps {\r\n  checkAvailability: typeof checkPackageNameAvailability;\r\n}\r\n\r\nconst defaultDeps: WizardDeps = {\r\n  checkAvailability: checkPackageNameAvailability,\r\n};\r\n\r\nfunction exitIfCancelled(value: unknown): void {\r\n  if (isCancel(value)) {\r\n    cancel('Operation cancelled.');\r\n    process.exit(1);\r\n  }\r\n}\r\n\r\nfunction validateProjectName(value: string): string | undefined {\r\n  if (!value || value.trim().length === 0) return 'Project name is required.';\r\n  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(value)) {\r\n    return 'Use lowercase letters and numbers, with single hyphens between words (no leading, trailing, or repeated hyphens).';\r\n  }\r\n  return undefined;\r\n}\r\n\r\nexport async function runWizard(deps: WizardDeps = defaultDeps): Promise<WizardAnswers> {\r\n  intro('clispark — scaffold a new CLI project');\r\n\r\n  const nameValue = await text({\r\n    message: 'Project name',\r\n    validate: validateProjectName,\r\n  });\r\n  exitIfCancelled(nameValue);\r\n  let projectName = nameValue as string;\r\n\r\n  const profileValue = await select({\r\n    message: 'Is this a work or private project?',\r\n    options: [\r\n      { value: 'private', label: 'Private' },\r\n      { value: 'work', label: 'Work' },\r\n    ],\r\n  });\r\n  exitIfCancelled(profileValue);\r\n  const profile = profileValue as Profile;\r\n\r\n  let registryUrl = DEFAULT_REGISTRY_URL;\r\n  if (profile === 'work') {\r\n    const registryValue = await text({\r\n      message: 'Custom npm registry URL (leave empty for npmjs.org)',\r\n      placeholder: DEFAULT_REGISTRY_URL,\r\n      defaultValue: DEFAULT_REGISTRY_URL,\r\n    });\r\n    exitIfCancelled(registryValue);\r\n    registryUrl = (registryValue as string) || DEFAULT_REGISTRY_URL;\r\n  }\r\n\r\n  let nameAvailability = await deps.checkAvailability(projectName, registryUrl);\r\n\r\n  while (nameAvailability === 'taken') {\r\n    log.warn(`\"${projectName}\" is already taken on ${registryUrl}. Please choose a different name.`);\r\n\r\n    const retryValue = await text({\r\n      message: 'Project name',\r\n      validate: validateProjectName,\r\n    });\r\n    exitIfCancelled(retryValue);\r\n    projectName = retryValue as string;\r\n\r\n    nameAvailability = await deps.checkAvailability(projectName, registryUrl);\r\n  }\r\n\r\n  if (nameAvailability === 'unverified') {\r\n    log.warn(`Could not verify availability of \"${projectName}\" on ${registryUrl}. Continuing anyway.`);\r\n  }\r\n\r\n  outro(`Ready to scaffold \"${projectName}\".`);\r\n\r\n  return { projectName, profile, registryUrl, nameAvailability };\r\n}\r\n","export const DEFAULT_REGISTRY_URL = 'https://registry.npmjs.org';\r\n\r\nexport type NameCheckResult = 'available' | 'taken' | 'unverified';\r\n\r\nexport async function checkPackageNameAvailability(\r\n  name: string,\r\n  registryUrl: string = DEFAULT_REGISTRY_URL,\r\n): Promise<NameCheckResult> {\r\n  const url = `${registryUrl.replace(/\\/$/, '')}/${encodeURIComponent(name)}`;\r\n\r\n  try {\r\n    const response = await fetch(url);\r\n    if (response.status === 404) return 'available';\r\n    if (response.status === 200) return 'taken';\r\n    return 'unverified';\r\n  } catch {\r\n    return 'unverified';\r\n  }\r\n}\r\n","import spawn from 'cross-spawn';\r\nimport { fileURLToPath } from 'node:url';\r\nimport path from 'node:path';\r\nimport { cp, readdir, readFile, rename, writeFile } from 'node:fs/promises';\r\nimport { DEFAULT_REGISTRY_URL } from './registry.js';\r\n\r\nexport interface ScaffoldOptions {\r\n  projectName: string;\r\n  targetDir: string;\r\n  registryUrl?: string;\r\n}\r\n\r\nconst TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'base');\r\n\r\nasync function assertTargetDirIsUsable(targetDir: string): Promise<void> {\r\n  let entries: string[];\r\n  try {\r\n    entries = await readdir(targetDir);\r\n  } catch {\r\n    return;\r\n  }\r\n  if (entries.length > 0) {\r\n    throw new Error(`Directory \"${targetDir}\" already exists and is not empty.`);\r\n  }\r\n}\r\n\r\nasync function replacePlaceholder(filePath: string, projectName: string): Promise<void> {\r\n  const content = (await readFile(filePath, 'utf8')).replaceAll('{{projectName}}', projectName);\r\n  await writeFile(filePath, content);\r\n}\r\n\r\nexport async function copyTemplate(options: ScaffoldOptions): Promise<void> {\r\n  const { projectName, targetDir, registryUrl } = options;\r\n\r\n  await assertTargetDirIsUsable(targetDir);\r\n  await cp(TEMPLATE_DIR, targetDir, { recursive: true });\r\n\r\n  await rename(path.join(targetDir, 'gitignore'), path.join(targetDir, '.gitignore'));\r\n\r\n  await replacePlaceholder(path.join(targetDir, 'package.json'), projectName);\r\n  await replacePlaceholder(path.join(targetDir, 'README.md'), projectName);\r\n  await replacePlaceholder(path.join(targetDir, 'src', 'logger.ts'), projectName);\r\n  await replacePlaceholder(path.join(targetDir, 'ARCHITECTURE.md'), projectName);\r\n\r\n  if (registryUrl && registryUrl !== DEFAULT_REGISTRY_URL) {\r\n    await writeFile(path.join(targetDir, '.npmrc'), `registry=${registryUrl}\\n`);\r\n  }\r\n}\r\n\r\nexport interface ScaffoldDeps {\r\n  runCommand: (command: string, args: string[], cwd: string) => Promise<void>;\r\n}\r\n\r\nasync function defaultRunCommand(command: string, args: string[], cwd: string): Promise<void> {\r\n  await new Promise<void>((resolve, reject) => {\r\n    const child = spawn(command, args, { cwd, stdio: 'inherit' });\r\n    child.on('error', reject);\r\n    child.on('close', (code) => {\r\n      if (code === 0) {\r\n        resolve();\r\n      } else {\r\n        reject(new Error(`Command \"${command} ${args.join(' ')}\" exited with code ${code}`));\r\n      }\r\n    });\r\n  });\r\n}\r\n\r\nconst defaultScaffoldDeps: ScaffoldDeps = { runCommand: defaultRunCommand };\r\n\r\nexport async function scaffoldProject(\r\n  options: ScaffoldOptions,\r\n  deps: ScaffoldDeps = defaultScaffoldDeps,\r\n): Promise<void> {\r\n  await copyTemplate(options);\r\n\r\n  const { targetDir } = options;\r\n  await deps.runCommand('git', ['init'], targetDir);\r\n  await deps.runCommand('git', ['add', '-A'], targetDir);\r\n  await deps.runCommand('git', ['commit', '-m', 'chore: initial scaffold from clispark'], targetDir);\r\n  await deps.runCommand('npm', ['install'], targetDir);\r\n  await deps.runCommand('npm', ['run', 'build'], targetDir);\r\n}\r\n","import { randomBytes } from 'node:crypto';\r\nimport { mkdirSync } from 'node:fs';\r\nimport path from 'node:path';\r\nimport envPaths from 'env-paths';\r\nimport pino, { type Logger } from 'pino';\r\n\r\nconst paths = envPaths('clispark', { suffix: '' });\r\n\r\nexport interface LoggerHandle {\r\n  logger: Logger;\r\n  logFilePath: string;\r\n}\r\n\r\nfunction buildLogFileName(commandName: string): string {\r\n  const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');\r\n  const suffix = randomBytes(3).toString('hex');\r\n  return `${commandName}-${timestamp}-${suffix}.log`;\r\n}\r\n\r\nexport function createLogger(commandName: string, logDir: string = paths.log): LoggerHandle {\r\n  mkdirSync(logDir, { recursive: true });\r\n\r\n  const logFilePath = path.join(logDir, buildLogFileName(commandName));\r\n  const logger = pino(pino.destination({ dest: logFilePath, sync: true }));\r\n\r\n  return { logger, logFilePath };\r\n}\r\n\r\nexport function withLogging(\r\n  commandName: string,\r\n  action: (logger: Logger) => Promise<void>,\r\n  logDir: string = paths.log,\r\n): () => Promise<void> {\r\n  return async () => {\r\n    let handle: LoggerHandle;\r\n    try {\r\n      handle = createLogger(commandName, logDir);\r\n    } catch (error) {\r\n      const message = error instanceof Error ? error.message : String(error);\r\n      console.error(`\\n✖ ${message}`);\r\n      process.exit(1);\r\n      return;\r\n    }\r\n\r\n    const { logger, logFilePath } = handle;\r\n    logger.info({ command: commandName }, 'started');\r\n\r\n    try {\r\n      await action(logger);\r\n      logger.info({ command: commandName }, 'completed');\r\n    } catch (error) {\r\n      logger.error({ command: commandName, err: error }, 'failed');\r\n      const message = error instanceof Error ? error.message : String(error);\r\n      console.error(`\\n✖ ${message}`);\r\n      console.error(`Details: ${logFilePath}`);\r\n      process.exit(1);\r\n    }\r\n  };\r\n}\r\n"],"mappings":"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","names":["path","path","require","path"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "clispark",
+  "version": "1.0.0",
+  "description": "Interactive scaffolding tool for new CLI projects",
+  "keywords": [
+    "cli",
+    "scaffolding",
+    "generator",
+    "boilerplate",
+    "starter",
+    "oclif",
+    "typescript"
+  ],
+  "homepage": "https://github.com/martinwichner/clispark#readme",
+  "bugs": {
+    "url": "https://github.com/martinwichner/clispark/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/martinwichner/clispark.git"
+  },
+  "license": "MIT",
+  "author": "Martin Mohn <martin.wichner@googlemail.com>",
+  "type": "module",
+  "bin": {
+    "clispark": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "shx chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "commander": "^13.1.0",
+    "cross-spawn": "^7.0.3",
+    "env-paths": "^3.0.0",
+    "pino": "^9.6.0"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.10.5",
+    "shx": "^0.3.4",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/base/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# {{projectName}} Architecture
+
+This document explains the conventions this project was generated with, so the automatic behavior (command discovery, logging, error handling) doesn't feel like unexplained magic.
+
+## Commands
+
+Every command lives in `src/commands/` and extends `BaseCommand` (`src/base-command.ts`) instead of oclif's own `Command` class directly:
+
+```ts
+import { BaseCommand } from '../base-command.js';
+
+export default class MyCommand extends BaseCommand {
+  static description = 'What this command does';
+  static args = {};
+  static flags = {};
+
+  async run(): Promise<void> {
+    await this.parse(MyCommand);
+    // ...
+  }
+}
+```
+
+`BaseCommand` overrides oclif's `init()`/`catch()`/`finally()` lifecycle methods to log every command's start, failure, and completion automatically — no manual logging calls needed inside `run()`.
+
+## Command Discovery
+
+oclif discovers commands at runtime from the `oclif.commands` path in `package.json` (`./dist/commands`) — there is no custom filesystem-scanning code. Dropping a new file in `src/commands/` and building the project is enough for oclif to pick it up; nothing needs to be manually registered.
+
+## Logging
+
+`src/logger.ts` writes structured JSON logs via `pino`, one file per command invocation, to an OS-appropriate log directory (via `env-paths`) — never to the project's own working directory. Every log line includes the command name. On failure, the full error (including stack trace) is logged, while the terminal only ever shows a clean `Error: <message>` — never a raw stack trace.
+
+## Testing
+
+Tests use `@oclif/test`'s `runCommand()` helper and live next to the command they test (e.g. `src/commands/hello.test.ts`). Running `npm test` first runs a build (via the `pretest` script) — `runCommand()` reads compiled output from `dist/commands`, so a stale or missing build produces empty, unhelpful output instead of a clear error. Every command's `run()` must call `await this.parse(<CommandClass>)`, even with no flags/args, to avoid an oclif `UnparsedCommand` warning.

package/templates/base/README.md

@@ -0,0 +1,3 @@
+# {{projectName}}
+
+Generated with [clispark](https://github.com/martinwichner/clispark).

package/templates/base/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from '@oclif/core';
+
+await execute({ dir: import.meta.url });

package/templates/base/gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log

package/templates/base/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "description": "",
+  "type": "module",
+  "bin": {
+    "{{projectName}}": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "oclif": {
+    "bin": "{{projectName}}",
+    "dirname": "{{projectName}}",
+    "commands": "./dist/commands",
+    "topicSeparator": " ",
+    "plugins": [
+      "@oclif/plugin-help"
+    ]
+  },
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "shx chmod +x bin/run.js",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.0.0",
+    "@oclif/plugin-help": "^6.0.0",
+    "env-paths": "^3.0.0",
+    "pino": "^9.6.0"
+  },
+  "devDependencies": {
+    "@oclif/test": "^4.0.0",
+    "@types/node": "^22.10.5",
+    "shx": "^0.3.4",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/templates/base/src/base-command.ts

@@ -0,0 +1,28 @@
+// templates/base/src/base-command.ts
+import { Command, type Interfaces } from '@oclif/core';
+import type { Logger } from 'pino';
+import { createLogger } from './logger.js';
+
+export abstract class BaseCommand extends Command {
+  protected logger?: Logger;
+
+  async init(): Promise<void> {
+    await super.init();
+
+    const { logger } = createLogger(this.id ?? 'unknown');
+    this.logger = logger;
+    this.logger.info({ command: this.id }, 'started');
+  }
+
+  protected async catch(err: Interfaces.CommandError): Promise<unknown> {
+    this.logger?.error({ command: this.id, err }, 'failed');
+    return super.catch(err);
+  }
+
+  protected async finally(err: Error | undefined): Promise<unknown> {
+    if (!err) {
+      this.logger?.info({ command: this.id }, 'completed');
+    }
+    return super.finally(err);
+  }
+}

package/templates/base/src/commands/hello.test.ts

@@ -0,0 +1,10 @@
+// templates/base/src/commands/hello.test.ts
+import { describe, it, expect } from 'vitest';
+import { runCommand } from '@oclif/test';
+
+describe('hello', () => {
+  it('prints a greeting', async () => {
+    const { stdout } = await runCommand('hello');
+    expect(stdout).toContain('Hello from your new CLI!');
+  });
+});

package/templates/base/src/commands/hello.ts

@@ -0,0 +1,13 @@
+// templates/base/src/commands/hello.ts
+import { BaseCommand } from '../base-command.js';
+
+export default class Hello extends BaseCommand {
+  static description = 'Say hello';
+  static args = {};
+  static flags = {};
+
+  async run(): Promise<void> {
+    await this.parse(Hello);
+    this.log('Hello from your new CLI!');
+  }
+}

package/templates/base/src/index.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/templates/base/src/logger.ts

@@ -0,0 +1,28 @@
+// templates/base/src/logger.ts
+import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import envPaths from 'env-paths';
+import pino, { type Logger } from 'pino';
+
+const paths = envPaths('{{projectName}}', { suffix: '' });
+
+export interface LoggerHandle {
+  logger: Logger;
+  logFilePath: string;
+}
+
+function buildLogFileName(commandName: string): string {
+  const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');
+  const suffix = randomBytes(3).toString('hex');
+  return `${commandName}-${timestamp}-${suffix}.log`;
+}
+
+export function createLogger(commandName: string, logDir: string = paths.log): LoggerHandle {
+  mkdirSync(logDir, { recursive: true });
+
+  const logFilePath = path.join(logDir, buildLogFileName(commandName));
+  const logger = pino(pino.destination({ dest: logFilePath, sync: true }));
+
+  return { logger, logFilePath };
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/templates/base/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/commands/**/*.ts', '!src/commands/**/*.test.ts'],
+  format: ['esm'],
+  target: 'node18',
+  outDir: 'dist',
+  clean: true,
+  sourcemap: true,
+});

package/templates/base/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    disableConsoleIntercept: true,
+  },
+});