@taskset/cli 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @taskset/cli
+
+## 0.1.2
+
+### Patch Changes
+
+- Publish the Taskset CLI and its runtime package chain under the `@taskset`
+  scope with public npm access and intentional package contents.
+- Updated dependencies
+  - @taskset/contracts@0.1.2
+  - @taskset/core@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Changeset initiated
+- Updated dependencies
+  - @taskset/contracts@0.1.1
+  - @taskset/core@0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taskset contributors
+
+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,20 @@
+# @taskset/cli
+
+The public, scriptable command-line interface for Taskset. Install it with:
+
+```bash
+pnpm add --save-dev @taskset/cli
+```
+
+It contains argument parsing, stdout and stderr rendering, exit-code mapping,
+the `taskset` executable, and the `defineConfig` helper used by
+`taskset.config.ts`. Repository discovery, validation, storage, and task
+behavior are delegated to `@taskset/core`.
+
+Current commands:
+
+- `taskset init`
+- `taskset config`
+- `taskset task create`
+- `taskset task list`
+- `taskset task show`

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+export interface CliContext {
+    readonly cwd?: string;
+    readonly stderr?: (value: string) => void;
+    readonly stdout?: (value: string) => void;
+}
+export declare function runCli(args: readonly string[], context?: CliContext): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AA2ED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAyK/F"}

package/dist/cli.js

@@ -0,0 +1,203 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { TASK_PRIORITIES, TASK_STATUSES, } from '@taskset/contracts';
+import { createTask, discoverRepository, initializeRepository, listTasks, readTask, serializeTaskFile, } from '@taskset/core';
+const USAGE = `Usage:
+  taskset init [--cwd <path>]
+  taskset config [--json] [--cwd <path>]
+  taskset task create --title <title> [options]
+  taskset task list [--json] [--cwd <path>]
+  taskset task show <task-id> [--json] [--cwd <path>]
+
+Create options:
+  --status <status>
+  --priority <priority>
+  --label <label>           Repeatable
+  --depends-on <task-id>    Repeatable
+  --file <path>             Repeatable
+  --body <markdown>
+`;
+class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliUsageError';
+    }
+}
+function parseTaskStatus(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!TASK_STATUSES.includes(value)) {
+        throw new CliUsageError(`Invalid task status "${value}"`);
+    }
+    return value;
+}
+function parseTaskPriority(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!TASK_PRIORITIES.includes(value)) {
+        throw new CliUsageError(`Invalid task priority "${value}"`);
+    }
+    return value;
+}
+function resolveCommandCwd(baseDirectory, cwdOption) {
+    return cwdOption ? path.resolve(baseDirectory, cwdOption) : baseDirectory;
+}
+function parseCommonOptions(args) {
+    return parseArgs({
+        args,
+        allowPositionals: false,
+        options: {
+            cwd: { type: 'string' },
+            json: { type: 'boolean' },
+        },
+    });
+}
+function requireSinglePositional(positionals, name) {
+    if (positionals.length !== 1 || !positionals[0]) {
+        throw new CliUsageError(`Expected exactly one ${name}`);
+    }
+    return positionals[0];
+}
+function formatError(error) {
+    if (!(error instanceof Error)) {
+        return 'Unknown Taskset error';
+    }
+    const issues = 'issues' in error && Array.isArray(error.issues)
+        ? error.issues
+            .map((issue) => typeof issue === 'object' && issue !== null && 'field' in issue && 'message' in issue
+            ? `\n  ${String(issue.field)}: ${String(issue.message)}`
+            : '')
+            .join('')
+        : '';
+    return `${error.message}${issues}`;
+}
+export async function runCli(args, context = {}) {
+    const cwd = path.resolve(context.cwd ?? process.cwd());
+    const stdout = context.stdout ?? ((value) => process.stdout.write(value));
+    const stderr = context.stderr ?? ((value) => process.stderr.write(value));
+    try {
+        const [command, subcommand] = args;
+        const commandArgs = args.slice(1);
+        const taskArgs = args.slice(2);
+        if (!command || command === 'help' || command === '--help' || command === '-h') {
+            stdout(USAGE);
+            return 0;
+        }
+        if (command === 'init') {
+            const parsed = parseCommonOptions(commandArgs);
+            const repository = await initializeRepository(resolveCommandCwd(cwd, parsed.values.cwd));
+            stdout(`Initialized Taskset in ${repository.rootDirectory}\n`);
+            return 0;
+        }
+        if (command === 'config') {
+            const parsed = parseCommonOptions(commandArgs);
+            const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd));
+            if (parsed.values.json) {
+                stdout(`${JSON.stringify({
+                    rootDirectory: repository.rootDirectory,
+                    configPath: repository.configPath,
+                    dataDirectory: repository.dataDirectory,
+                    config: repository.config,
+                }, null, 2)}\n`);
+            }
+            else {
+                stdout(`${repository.configPath}\n`);
+            }
+            return 0;
+        }
+        if (command !== 'task') {
+            throw new CliUsageError(`Unknown command "${command}"`);
+        }
+        if (subcommand === 'create') {
+            const parsed = parseArgs({
+                args: taskArgs,
+                allowPositionals: false,
+                options: {
+                    body: { type: 'string' },
+                    cwd: { type: 'string' },
+                    'depends-on': { type: 'string', multiple: true },
+                    file: { type: 'string', multiple: true },
+                    json: { type: 'boolean' },
+                    label: { type: 'string', multiple: true },
+                    priority: { type: 'string' },
+                    status: { type: 'string' },
+                    title: { type: 'string' },
+                },
+            });
+            if (!parsed.values.title) {
+                throw new CliUsageError('The --title option is required');
+            }
+            const status = parseTaskStatus(parsed.values.status);
+            const priority = parseTaskPriority(parsed.values.priority);
+            const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd));
+            const record = await createTask(repository, {
+                title: parsed.values.title,
+                ...(status ? { status } : {}),
+                ...(priority ? { priority } : {}),
+                ...(parsed.values.label ? { labels: parsed.values.label } : {}),
+                ...(parsed.values['depends-on'] ? { dependsOn: parsed.values['depends-on'] } : {}),
+                ...(parsed.values.file ? { files: parsed.values.file } : {}),
+                ...(parsed.values.body !== undefined ? { body: parsed.values.body } : {}),
+            });
+            if (parsed.values.json) {
+                stdout(`${JSON.stringify({ relativePath: record.relativePath, ...record.task.metadata }, null, 2)}\n`);
+            }
+            else {
+                stdout(`${record.task.metadata.id}\n`);
+            }
+            return 0;
+        }
+        if (subcommand === 'list') {
+            const parsed = parseCommonOptions(taskArgs);
+            const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd));
+            const records = await listTasks(repository);
+            if (parsed.values.json) {
+                stdout(`${JSON.stringify(records.map((record) => ({
+                    relativePath: record.relativePath,
+                    ...record.task.metadata,
+                })), null, 2)}\n`);
+            }
+            else {
+                for (const record of records) {
+                    stdout(`${record.task.metadata.id}\t${record.task.metadata.status}\t${record.task.metadata.title}\n`);
+                }
+            }
+            return 0;
+        }
+        if (subcommand === 'show') {
+            const parsed = parseArgs({
+                args: taskArgs,
+                allowPositionals: true,
+                options: {
+                    cwd: { type: 'string' },
+                    json: { type: 'boolean' },
+                },
+            });
+            const taskId = requireSinglePositional(parsed.positionals, 'task ID');
+            const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd));
+            const record = await readTask(repository, taskId);
+            if (parsed.values.json) {
+                stdout(`${JSON.stringify({
+                    relativePath: record.relativePath,
+                    metadata: record.task.metadata,
+                    body: record.task.body,
+                }, null, 2)}\n`);
+            }
+            else {
+                stdout(serializeTaskFile(record.task, { filePath: record.relativePath }));
+            }
+            return 0;
+        }
+        throw new CliUsageError(`Unknown task command "${subcommand ?? ''}"`);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError || error instanceof TypeError) {
+            stderr(`${formatError(error)}\n\n${USAGE}`);
+            return 2;
+        }
+        stderr(`${formatError(error)}\n`);
+        return 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { defineConfig } from '@taskset/core';
+export { type CliContext, runCli } from './cli.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineConfig } from '@taskset/core';
+export { runCli } from "./cli.js";

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@taskset/cli",
+  "type": "module",
+  "private": false,
+  "version": "0.1.2",
+  "description": "The scriptable command-line interface for Taskset.",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "taskset": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "dependencies": {
+    "@taskset/contracts": "0.1.2",
+    "@taskset/core": "0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8",
+    "@taskset/configs": "0.1.1"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc",
+    "clean": "node --eval \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\"",
+    "test": "vitest run --root ../.. packages/cli/src",
+    "test:watch": "vitest --root ../.. packages/cli/src"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from './cli.ts'
+
+process.exitCode = await runCli(process.argv.slice(2))

package/src/cli.ts

@@ -0,0 +1,282 @@
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import {
+	TASK_PRIORITIES,
+	TASK_STATUSES,
+	type TaskPriority,
+	type TaskStatus,
+} from '@taskset/contracts'
+import {
+	createTask,
+	discoverRepository,
+	initializeRepository,
+	listTasks,
+	readTask,
+	serializeTaskFile,
+} from '@taskset/core'
+
+const USAGE = `Usage:
+  taskset init [--cwd <path>]
+  taskset config [--json] [--cwd <path>]
+  taskset task create --title <title> [options]
+  taskset task list [--json] [--cwd <path>]
+  taskset task show <task-id> [--json] [--cwd <path>]
+
+Create options:
+  --status <status>
+  --priority <priority>
+  --label <label>           Repeatable
+  --depends-on <task-id>    Repeatable
+  --file <path>             Repeatable
+  --body <markdown>
+`
+
+export interface CliContext {
+	readonly cwd?: string
+	readonly stderr?: (value: string) => void
+	readonly stdout?: (value: string) => void
+}
+
+class CliUsageError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'CliUsageError'
+	}
+}
+
+function parseTaskStatus(value: string | undefined): TaskStatus | undefined {
+	if (value === undefined) {
+		return undefined
+	}
+
+	if (!TASK_STATUSES.includes(value as TaskStatus)) {
+		throw new CliUsageError(`Invalid task status "${value}"`)
+	}
+
+	return value as TaskStatus
+}
+
+function parseTaskPriority(value: string | undefined): TaskPriority | undefined {
+	if (value === undefined) {
+		return undefined
+	}
+
+	if (!TASK_PRIORITIES.includes(value as TaskPriority)) {
+		throw new CliUsageError(`Invalid task priority "${value}"`)
+	}
+
+	return value as TaskPriority
+}
+
+function resolveCommandCwd(baseDirectory: string, cwdOption: string | undefined): string {
+	return cwdOption ? path.resolve(baseDirectory, cwdOption) : baseDirectory
+}
+
+function parseCommonOptions(args: readonly string[]) {
+	return parseArgs({
+		args,
+		allowPositionals: false,
+		options: {
+			cwd: { type: 'string' },
+			json: { type: 'boolean' },
+		},
+	})
+}
+
+function requireSinglePositional(positionals: readonly string[], name: string): string {
+	if (positionals.length !== 1 || !positionals[0]) {
+		throw new CliUsageError(`Expected exactly one ${name}`)
+	}
+
+	return positionals[0]
+}
+
+function formatError(error: unknown): string {
+	if (!(error instanceof Error)) {
+		return 'Unknown Taskset error'
+	}
+
+	const issues =
+		'issues' in error && Array.isArray(error.issues)
+			? error.issues
+					.map((issue) =>
+						typeof issue === 'object' && issue !== null && 'field' in issue && 'message' in issue
+							? `\n  ${String(issue.field)}: ${String(issue.message)}`
+							: '',
+					)
+					.join('')
+			: ''
+
+	return `${error.message}${issues}`
+}
+
+export async function runCli(args: readonly string[], context: CliContext = {}): Promise<number> {
+	const cwd = path.resolve(context.cwd ?? process.cwd())
+	const stdout = context.stdout ?? ((value: string) => process.stdout.write(value))
+	const stderr = context.stderr ?? ((value: string) => process.stderr.write(value))
+
+	try {
+		const [command, subcommand] = args
+		const commandArgs = args.slice(1)
+		const taskArgs = args.slice(2)
+
+		if (!command || command === 'help' || command === '--help' || command === '-h') {
+			stdout(USAGE)
+			return 0
+		}
+
+		if (command === 'init') {
+			const parsed = parseCommonOptions(commandArgs)
+			const repository = await initializeRepository(resolveCommandCwd(cwd, parsed.values.cwd))
+			stdout(`Initialized Taskset in ${repository.rootDirectory}\n`)
+			return 0
+		}
+
+		if (command === 'config') {
+			const parsed = parseCommonOptions(commandArgs)
+			const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd))
+
+			if (parsed.values.json) {
+				stdout(
+					`${JSON.stringify(
+						{
+							rootDirectory: repository.rootDirectory,
+							configPath: repository.configPath,
+							dataDirectory: repository.dataDirectory,
+							config: repository.config,
+						},
+						null,
+						2,
+					)}\n`,
+				)
+			} else {
+				stdout(`${repository.configPath}\n`)
+			}
+
+			return 0
+		}
+
+		if (command !== 'task') {
+			throw new CliUsageError(`Unknown command "${command}"`)
+		}
+
+		if (subcommand === 'create') {
+			const parsed = parseArgs({
+				args: taskArgs,
+				allowPositionals: false,
+				options: {
+					body: { type: 'string' },
+					cwd: { type: 'string' },
+					'depends-on': { type: 'string', multiple: true },
+					file: { type: 'string', multiple: true },
+					json: { type: 'boolean' },
+					label: { type: 'string', multiple: true },
+					priority: { type: 'string' },
+					status: { type: 'string' },
+					title: { type: 'string' },
+				},
+			})
+
+			if (!parsed.values.title) {
+				throw new CliUsageError('The --title option is required')
+			}
+
+			const status = parseTaskStatus(parsed.values.status)
+			const priority = parseTaskPriority(parsed.values.priority)
+
+			const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd))
+			const record = await createTask(repository, {
+				title: parsed.values.title,
+				...(status ? { status } : {}),
+				...(priority ? { priority } : {}),
+				...(parsed.values.label ? { labels: parsed.values.label } : {}),
+				...(parsed.values['depends-on'] ? { dependsOn: parsed.values['depends-on'] } : {}),
+				...(parsed.values.file ? { files: parsed.values.file } : {}),
+				...(parsed.values.body !== undefined ? { body: parsed.values.body } : {}),
+			})
+
+			if (parsed.values.json) {
+				stdout(
+					`${JSON.stringify(
+						{ relativePath: record.relativePath, ...record.task.metadata },
+						null,
+						2,
+					)}\n`,
+				)
+			} else {
+				stdout(`${record.task.metadata.id}\n`)
+			}
+
+			return 0
+		}
+
+		if (subcommand === 'list') {
+			const parsed = parseCommonOptions(taskArgs)
+			const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd))
+			const records = await listTasks(repository)
+
+			if (parsed.values.json) {
+				stdout(
+					`${JSON.stringify(
+						records.map((record) => ({
+							relativePath: record.relativePath,
+							...record.task.metadata,
+						})),
+						null,
+						2,
+					)}\n`,
+				)
+			} else {
+				for (const record of records) {
+					stdout(
+						`${record.task.metadata.id}\t${record.task.metadata.status}\t${record.task.metadata.title}\n`,
+					)
+				}
+			}
+
+			return 0
+		}
+
+		if (subcommand === 'show') {
+			const parsed = parseArgs({
+				args: taskArgs,
+				allowPositionals: true,
+				options: {
+					cwd: { type: 'string' },
+					json: { type: 'boolean' },
+				},
+			})
+			const taskId = requireSinglePositional(parsed.positionals, 'task ID')
+			const repository = await discoverRepository(resolveCommandCwd(cwd, parsed.values.cwd))
+			const record = await readTask(repository, taskId)
+
+			if (parsed.values.json) {
+				stdout(
+					`${JSON.stringify(
+						{
+							relativePath: record.relativePath,
+							metadata: record.task.metadata,
+							body: record.task.body,
+						},
+						null,
+						2,
+					)}\n`,
+				)
+			} else {
+				stdout(serializeTaskFile(record.task, { filePath: record.relativePath }))
+			}
+
+			return 0
+		}
+
+		throw new CliUsageError(`Unknown task command "${subcommand ?? ''}"`)
+	} catch (error) {
+		if (error instanceof CliUsageError || error instanceof TypeError) {
+			stderr(`${formatError(error)}\n\n${USAGE}`)
+			return 2
+		}
+
+		stderr(`${formatError(error)}\n`)
+		return 1
+	}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { defineConfig } from '@taskset/core'
+export { type CliContext, runCli } from './cli.ts'