clispark 1.3.0 → 1.4.0

package/README.md

@@ -29,7 +29,7 @@ Every generated project includes:
 - **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
+- **Example commands** — a minimal `hello` starting point plus a `task`/`task complete`/`task list` reference covering required args, optional args, enum-constrained args, integer and boolean args, and subcommands
 - **A clean build pipeline** (`tsup`) producing a directly runnable binary
 
 ## Usage

package/package.json

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

package/templates/base/ARCHITECTURE.md

@@ -23,6 +23,50 @@ export default class MyCommand extends BaseCommand {
 
 `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()`.
 
+## Argument Types
+
+Every entry in a command's `static args` is built from `@oclif/core`'s `Args` helpers. `task.ts` / `task/complete.ts` / `task/list.ts` use a few of these; the full set `@oclif/core` ships:
+
+- **`Args.string()`** — plain text, no parsing/validation. The default choice.
+  ```ts
+  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' })
+  // `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' })
+  // `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' })
+  // 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' })
+  ```
+- **`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}`);
+      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'] })
+  // `task <title> urgent` → "Expected urgent to be one of: low, medium, high"
+  ```
+
+See `task.ts` (string + enum-constrained string), `task/complete.ts` (integer), and `task/list.ts` (string + boolean) for these in a real, runnable command.
+
 ## 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.

package/templates/base/README.md

@@ -5,3 +5,19 @@ Generated with [clispark](https://github.com/martinwichner/clispark).
 ## Requirements
 
 Node.js **>=24** — this project's entry point (`bin/run.ts`) runs directly via Node's native TypeScript execution, with no build step. On an older Node version it fails with an `ERR_UNKNOWN_FILE_EXTENSION` error rather than a clear version message, so if you hit that, check `node --version` first.
+
+## Example commands
+
+Two example commands ship in `src/commands/` as copy-paste starting points:
+
+- **`hello`** (`src/commands/hello.ts`) — the minimal case: no args, no subcommands.
+  ```bash
+  node bin/run.ts hello
+  ```
+- **`task`** / **`task complete`** / **`task list`** (`src/commands/task.ts`, `src/commands/task/`) — a reference for oclif's argument and subcommand patterns: required args, optional args, an enum-constrained arg, an integer arg, a boolean arg, and how a folder under `src/commands/` becomes a subcommand.
+  ```bash
+  node bin/run.ts task "Buy milk" high
+  node bin/run.ts task complete 1
+  node bin/run.ts task list groceries
+  ```
+  See `ARCHITECTURE.md`'s "Argument Types" section for the full set of argument types oclif supports, including a couple this example doesn't use.

package/templates/base/src/commands/task/complete.test.ts

@@ -0,0 +1,20 @@
+// templates/base/src/commands/task/complete.test.ts
+import { describe, it, expect } from 'vitest';
+import { runCommand } from '@oclif/test';
+
+describe('task complete', () => {
+  it('completes a task by numeric id', async () => {
+    const { stdout } = await runCommand('task complete 42');
+    expect(stdout).toContain('Completed task 42');
+  });
+
+  it('rejects a non-numeric id', async () => {
+    const { error } = await runCommand('task complete abc');
+    expect(error?.message).toContain('Expected an integer but received: abc');
+  });
+
+  it('requires an id', async () => {
+    const { error } = await runCommand('task complete');
+    expect(error?.message).toContain('Missing 1 required arg');
+  });
+});

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

@@ -0,0 +1,16 @@
+// templates/base/src/commands/task/complete.ts
+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 args = {
+    id: Args.integer({ required: true, description: 'Task ID to complete' }),
+  };
+  static flags = {};
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(TaskComplete);
+    this.log(`Completed task ${args.id}`);
+  }
+}

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

@@ -0,0 +1,25 @@
+// templates/base/src/commands/task/list.test.ts
+import { describe, it, expect } from 'vitest';
+import { runCommand } from '@oclif/test';
+
+describe('task list', () => {
+  it('lists all tasks with no args', async () => {
+    const { stdout } = await runCommand('task list');
+    expect(stdout).toContain('Listing all tasks');
+  });
+
+  it('lists tasks matching a filter', async () => {
+    const { stdout } = await runCommand('task list groceries');
+    expect(stdout).toContain('Listing tasks matching "groceries"');
+  });
+
+  it('combines a filter with the done flag', async () => {
+    const { stdout } = await runCommand('task list groceries true');
+    expect(stdout).toContain('Listing tasks matching "groceries" (completed only: true)');
+  });
+
+  it('parses "no" as false for the done arg', async () => {
+    const { stdout } = await runCommand('task list groceries no');
+    expect(stdout).toContain('(completed only: false)');
+  });
+});

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

@@ -0,0 +1,18 @@
+// templates/base/src/commands/task/list.ts
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base-command';
+
+export default class TaskList extends BaseCommand {
+  static description = 'List tasks (demonstrates a subcommand with two optional arguments of different types)';
+  static args = {
+    filter: Args.string({ required: false, description: 'Optional filter term' }),
+    done: Args.boolean({ required: false, description: 'Only show completed tasks (true/false)' }),
+  };
+  static flags = {};
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(TaskList);
+    const base = args.filter ? `Listing tasks matching "${args.filter}"` : 'Listing all tasks';
+    this.log(args.done !== undefined ? `${base} (completed only: ${args.done})` : base);
+  }
+}

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

@@ -0,0 +1,26 @@
+// templates/base/src/commands/task.test.ts
+import { describe, it, expect } from 'vitest';
+import { runCommand } from '@oclif/test';
+
+describe('task', () => {
+  it('creates a task with just a title', async () => {
+    const { stdout } = await runCommand('task "Buy milk"');
+    expect(stdout).toContain('Created task: "Buy milk"');
+    expect(stdout).not.toContain('priority');
+  });
+
+  it('creates a task with a priority', async () => {
+    const { stdout } = await runCommand('task "Buy milk" high');
+    expect(stdout).toContain('Created task: "Buy milk" (priority: high)');
+  });
+
+  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');
+  });
+
+  it('requires a title', async () => {
+    const { error } = await runCommand('task');
+    expect(error?.message).toContain('Missing 1 required arg');
+  });
+});

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

@@ -0,0 +1,21 @@
+// templates/base/src/commands/task.ts
+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 args = {
+    title: Args.string({ required: true, description: 'Task title' }),
+    priority: Args.string({
+      required: false,
+      options: ['low', 'medium', 'high'],
+      description: 'Optional priority',
+    }),
+  };
+  static flags = {};
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(Task);
+    this.log(`Created task: "${args.title}"${args.priority ? ` (priority: ${args.priority})` : ''}`);
+  }
+}