clispark 1.19.1 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clispark",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "Interactive scaffolding tool for new CLI projects",
   "keywords": [
     "cli",

package/templates/dotnet/ARCHITECTURE.md

@@ -75,3 +75,22 @@ A few things run automatically around every log call:
 ## Testing
 
 Tests use `xunit` and live in `tests/Cli.Tests.csproj` (a separate project referencing `src/Cli.csproj`, not colocated with the commands they test — the conventional .NET layout, unlike vitest's colocated `*.test.ts` files). A test exercises a command directly via `new SomeCommand().Build()` then `.Parse(args).Invoke(...)` — no process spawning needed. Remember the `EnableDefaultExceptionHandler = false` detail from "Error Handling" above when asserting on thrown exceptions.
+
+## Lint Tooling
+
+If you answered "yes" to "Set up lint tooling?" during scaffolding, `src/Cli.csproj` includes a `<PropertyGroup>` enabling the .NET SDK's built-in Roslyn analyzers — no new NuGet dependency:
+
+```xml
+<PropertyGroup>
+  <EnableNETAnalyzers>true</EnableNETAnalyzers>
+  <AnalysisLevel>latest</AnalysisLevel>
+  <AnalysisMode>Recommended</AnalysisMode>
+  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+</PropertyGroup>
+```
+
+There's no separate lint command — analyzer warnings surface as part of a normal `dotnet build`. `AnalysisMode=Recommended` (over the SDK default `Default`) and `EnforceCodeStyleInBuild=true` (over the SDK default `false`, which otherwise confines code-style rules to the IDE) are what actually change build output; `EnableNETAnalyzers`/`AnalysisLevel` are already the `net10.0` SDK's own defaults and are listed here for explicitness.
+
+If you answered "no", this `<PropertyGroup>` isn't present, and `dotnet build` runs with only the SDK's own defaults.
+
+Either way, this choice is permanent and core-managed: `npx clispark update` keeps this block current for a project that opted in, and will never add it to a project that declined. There's no retroactive "turn lint tooling on later" command — rerun `clispark` in a new directory if you want it.

package/templates/dotnet/src/Cli.csproj

@@ -13,6 +13,13 @@
     <PackageId>{{projectName}}</PackageId>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+    <AnalysisLevel>latest</AnalysisLevel>
+    <AnalysisMode>Recommended</AnalysisMode>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="System.CommandLine" Version="2.0.10" />
     <PackageReference Include="Serilog" Version="4.4.0" />

package/templates/dotnet/src/Logging/CliLoggerFactory.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using Serilog;
 using Serilog.Core;
 using Xdg.Directories;
@@ -17,17 +18,17 @@ public static class CliLoggerFactory
         Directory.CreateDirectory(logDir);
         SweepOldLogs(logDir);
 
-        var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH-mm-ss-fffZ");
+        var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH-mm-ss-fffZ", CultureInfo.InvariantCulture);
         var suffix = Guid.NewGuid().ToString("N")[..6];
         var logFilePath = Path.Combine(logDir, $"{commandName}-{timestamp}-{suffix}.log");
 
         var config = new LoggerConfiguration()
             .Enrich.With(new SensitivePropertyEnricher(SensitiveKeys))
-            .WriteTo.File(logFilePath);
+            .WriteTo.File(logFilePath, formatProvider: CultureInfo.InvariantCulture);
 
         if (Environment.GetEnvironmentVariable("DEBUG") is not null)
         {
-            config = config.WriteTo.Console();
+            config = config.WriteTo.Console(formatProvider: CultureInfo.InvariantCulture);
         }
 
         var logger = config.CreateLogger();

package/templates/node/.prettierignore

@@ -0,0 +1 @@
+.clispark/

package/templates/node/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "endOfLine": "auto"
+}

package/templates/node/ARCHITECTURE.md

@@ -29,39 +29,40 @@ Every entry in a command's `static args` is built from `@oclif/core`'s `Args` he
 
 - **`Args.string()`** — plain text, no parsing/validation. The default choice.
   ```ts
-  title: Args.string({ description: 'Task title' })
+  title: Args.string({ description: 'Task title' });
   ```
 - **`Args.integer({ min?, max? })`** — parses digits into a real `number`, rejects non-numeric input, optional bounds.
   ```ts
-  id: Args.integer({ description: 'Task ID' })
+  id: Args.integer({ description: 'Task ID' });
   // `task complete abc` → "Expected an integer but received: abc"
   ```
 - **`Args.boolean()`** — parses into a real `boolean`. Any input is `true` except (case-insensitive) `0`, `false`, `n`, `no`, which parse to `false`.
   ```ts
-  done: Args.boolean({ description: 'Only completed tasks' })
+  done: Args.boolean({ description: 'Only completed tasks' });
   // `task list true` → done === true; `task list no` → done === false
   ```
 - **`Args.file({ exists? })`** / **`Args.directory({ exists? })`** — plain string path by default; with `exists: true`, verifies the path actually exists on disk (as a file/directory respectively) and throws otherwise.
   ```ts
-  config: Args.file({ exists: true, description: 'Path to a config file' })
+  config: Args.file({ exists: true, description: 'Path to a config file' });
   // missing file → "No file found at <path>"
   ```
 - **`Args.url()`** — parses into a real `URL` object, throws if the input isn't a valid URL.
   ```ts
-  endpoint: Args.url({ description: 'API endpoint' })
+  endpoint: Args.url({ description: 'API endpoint' });
   ```
 - **`Args.custom<T, Opts>({ parse })`** — build your own type when none of the above fit.
   ```ts
   const semver = Args.custom<string>({
     parse: async (input) => {
-      if (!/^\d+\.\d+\.\d+$/.test(input)) throw new Error(`Not a valid semver: ${input}`);
+      if (!/^\d+\.\d+\.\d+$/.test(input))
+        throw new Error(`Not a valid semver: ${input}`);
       return input;
     },
   });
   ```
 - **`options: [...]`** — a cross-cutting constraint any arg type can add (not a type itself): restricts input to a fixed list of values.
   ```ts
-  priority: Args.string({ options: ['low', 'medium', 'high'] })
+  priority: Args.string({ options: ['low', 'medium', 'high'] });
   // `task <title> urgent` → "Expected urgent to be one of: low, medium, high"
   ```
 
@@ -73,7 +74,7 @@ Flags (`--name`/`-n`) are `@oclif/core`'s other input mechanism, declared in `st
 
 - **`Flags.boolean()`** — presence-based: passing the flag sets it to `true`, omitting it leaves it `undefined`.
   ```ts
-  done: Flags.boolean({ description: 'Only show completed tasks' })
+  done: Flags.boolean({ description: 'Only show completed tasks' });
   // `task list --done` → done === true; omitted → done === undefined
   ```
 - Flags otherwise mirror the `Args` catalogue above (`Flags.string()`, `Flags.integer()`, `options: [...]`, etc.) — the choice between an arg and a flag is about calling convention (positional vs. named), not available types.
@@ -98,3 +99,16 @@ A few things run automatically around every log call:
 ## 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.
+
+## Lint Tooling
+
+If you answered "yes" to "Set up lint tooling?" during scaffolding, this project includes `eslint.config.js` (flat config, `@eslint/js` + `typescript-eslint` recommended rulesets), `.prettierrc`, and `.prettierignore` (excludes `.clispark/`, the tool's own generated manifest, from Prettier's formatting checks), plus `eslint-config-prettier` to keep ESLint out of Prettier's way on formatting-related rules. Run it with:
+
+```bash
+npm run lint    # eslint src bin
+npm run format  # prettier --write .
+```
+
+If you answered "no", none of this is present — no config files, no `lint`/`format` scripts, no eslint/prettier devDependencies.
+
+Either way, this choice is permanent and core-managed: `npx clispark update` keeps the lint config and its devDependency versions current for a project that opted in, and will never add any of it to a project that declined. There's no retroactive "turn lint tooling on later" command — rerun `clispark` in a new directory if you want it.

package/templates/node/eslint.config.js

@@ -0,0 +1,18 @@
+// eslint.config.js
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/**'],
+  },
+  {
+    files: ['src/**/*.ts', 'bin/**/*.ts'],
+    extends: [
+      eslint.configs.recommended,
+      ...tseslint.configs.recommended,
+      eslintConfigPrettier,
+    ],
+  },
+);

package/templates/node/package.json

@@ -25,6 +25,8 @@
   "scripts": {
     "build": "tsup",
     "postbuild": "shx chmod +x bin/run.ts",
+    "format": "prettier --write .",
+    "lint": "eslint src bin",
     "pretest": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
@@ -36,11 +38,16 @@
     "pino": "^9.6.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@oclif/test": "^4.0.0",
     "@types/node": "^24.0.0",
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.6",
     "shx": "^0.3.4",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
+    "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   }
 }

package/templates/node/src/commands/task/complete.ts

@@ -3,7 +3,8 @@ import { Args } from '@oclif/core';
 import { BaseCommand } from '../../base-command';
 
 export default class TaskComplete extends BaseCommand {
-  static description = 'Complete a task (demonstrates a subcommand with a required integer argument)';
+  static description =
+    'Complete a task (demonstrates a subcommand with a required integer argument)';
   static examples = [
     {
       command: '<%= config.bin %> task complete 1',

package/templates/node/src/commands/task/list.test.ts

@@ -15,7 +15,9 @@ describe('task list', () => {
 
   it('combines a filter with the --done flag', async () => {
     const { stdout } = await runCommand('task list groceries --done');
-    expect(stdout).toContain('Listing tasks matching "groceries" (completed only: true)');
+    expect(stdout).toContain(
+      'Listing tasks matching "groceries" (completed only: true)',
+    );
   });
 
   it('omits the completed-only note when --done is not passed', async () => {

package/templates/node/src/commands/task/list.ts

@@ -3,7 +3,8 @@ import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base-command';
 
 export default class TaskList extends BaseCommand {
-  static description = 'List tasks (demonstrates an optional argument combined with a boolean flag)';
+  static description =
+    'List tasks (demonstrates an optional argument combined with a boolean flag)';
   static examples = [
     {
       command: '<%= config.bin %> task list',
@@ -19,7 +20,10 @@ export default class TaskList extends BaseCommand {
     },
   ];
   static args = {
-    filter: Args.string({ required: false, description: 'Optional filter term' }),
+    filter: Args.string({
+      required: false,
+      description: 'Optional filter term',
+    }),
   };
   static flags = {
     done: Flags.boolean({ description: 'Only show completed tasks' }),
@@ -27,7 +31,9 @@ export default class TaskList extends BaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(TaskList);
-    const base = args.filter ? `Listing tasks matching "${args.filter}"` : 'Listing all tasks';
+    const base = args.filter
+      ? `Listing tasks matching "${args.filter}"`
+      : 'Listing all tasks';
     this.log(flags.done ? `${base} (completed only: true)` : base);
   }
 }

package/templates/node/src/commands/task.test.ts

@@ -16,7 +16,9 @@ describe('task', () => {
 
   it('rejects a priority outside the allowed values', async () => {
     const { error } = await runCommand('task "Buy milk" urgent');
-    expect(error?.message).toContain('Expected urgent to be one of: low, medium, high');
+    expect(error?.message).toContain(
+      'Expected urgent to be one of: low, medium, high',
+    );
   });
 
   it('requires a title', async () => {

package/templates/node/src/commands/task.ts

@@ -3,7 +3,8 @@ import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command';
 
 export default class Task extends BaseCommand {
-  static description = 'Create a task (demonstrates a required string arg and an optional enum-constrained arg)';
+  static description =
+    'Create a task (demonstrates a required string arg and an optional enum-constrained arg)';
   static examples = [
     {
       command: '<%= config.bin %> task "Buy milk"',
@@ -11,7 +12,8 @@ export default class Task extends BaseCommand {
     },
     {
       command: '<%= config.bin %> task "Buy milk" high',
-      description: 'Creates a task with an optional priority (low, medium, or high)',
+      description:
+        'Creates a task with an optional priority (low, medium, or high)',
     },
   ];
   static args = {
@@ -26,6 +28,8 @@ export default class Task extends BaseCommand {
 
   async run(): Promise<void> {
     const { args } = await this.parse(Task);
-    this.log(`Created task: "${args.title}"${args.priority ? ` (priority: ${args.priority})` : ''}`);
+    this.log(
+      `Created task: "${args.title}"${args.priority ? ` (priority: ${args.priority})` : ''}`,
+    );
   }
 }

package/templates/node/src/logger.test.ts

@@ -10,7 +10,9 @@ describe('createLogger', () => {
   let tmpRoot: string;
 
   beforeEach(async () => {
-    tmpRoot = await mkdtemp(path.join(tmpdir(), 'clispark-template-logger-test-'));
+    tmpRoot = await mkdtemp(
+      path.join(tmpdir(), 'clispark-template-logger-test-'),
+    );
   });
 
   afterEach(async () => {
@@ -151,7 +153,9 @@ describe('createLogger', () => {
   });
 
   it('streams log lines to stdout when DEBUG is set', async () => {
-    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const writeSpy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
     process.env.DEBUG = '1';
 
     try {
@@ -168,7 +172,9 @@ describe('createLogger', () => {
   });
 
   it('does not stream to stdout when DEBUG is unset', async () => {
-    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const writeSpy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
     delete process.env.DEBUG;
 
     const { logger } = createLogger('hello', tmpRoot);

package/templates/node/src/logger.ts

@@ -1,6 +1,12 @@
 // templates/base/src/logger.ts
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import {
+  mkdirSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import path from 'node:path';
 import envPaths from 'env-paths';
 import pino, { type Logger } from 'pino';
@@ -57,7 +63,8 @@ function sweepOldLogs(logDir: string): void {
     const markerPath = path.join(logDir, SWEEP_MARKER_FILE);
     let shouldSweep = true;
     try {
-      shouldSweep = Date.now() - statSync(markerPath).mtimeMs >= SWEEP_THROTTLE_MS;
+      shouldSweep =
+        Date.now() - statSync(markerPath).mtimeMs >= SWEEP_THROTTLE_MS;
     } catch {
       // no marker yet (first run in this directory) - sweep now
     }
@@ -75,16 +82,29 @@ function sweepOldLogs(logDir: string): void {
   });
 }
 
-export function createLogger(commandName: string, logDir: string = paths.log): LoggerHandle {
+export function createLogger(
+  commandName: string,
+  logDir: string = paths.log,
+): LoggerHandle {
   mkdirSync(logDir, { recursive: true });
   sweepOldLogs(logDir);
 
   const logFilePath = path.join(logDir, buildLogFileName(commandName));
-  const fileDestination = pino.destination({ dest: logFilePath, sync: true, mode: 0o600 });
+  const fileDestination = pino.destination({
+    dest: logFilePath,
+    sync: true,
+    mode: 0o600,
+  });
   const destination = process.env.DEBUG
-    ? pino.multistream([{ stream: fileDestination }, { stream: process.stdout }])
+    ? pino.multistream([
+        { stream: fileDestination },
+        { stream: process.stdout },
+      ])
     : fileDestination;
-  const logger = pino({ redact: buildRedactPaths(SENSITIVE_LOG_KEYS) }, destination);
+  const logger = pino(
+    { redact: buildRedactPaths(SENSITIVE_LOG_KEYS) },
+    destination,
+  );
 
   return { logger, logFilePath };
 }