clawkit-cli-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+//#region src/errors.d.ts
+declare const CLI_ERROR_CODES: readonly ["E_ARG_INVALID", "E_ARG_MISSING", "E_ARG_CONFLICT", "E_ARG_UNSUPPORTED", "E_AUTH_REQUIRED", "E_AUTH_INVALID", "E_NOT_FOUND_RESOURCE", "E_UPSTREAM_NETWORK", "E_UPSTREAM_TIMEOUT", "E_UPSTREAM_BAD_RESPONSE", "E_UNKNOWN"];
+type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
+interface CliAppErrorOptions {
+  code: CliErrorCode;
+  message: string;
+  details?: unknown;
+  cause?: unknown;
+}
+declare class CliAppError extends Error {
+  readonly code: CliErrorCode;
+  readonly details?: unknown;
+  constructor(options: CliAppErrorOptions);
+}
+declare function isCliAppError(value: unknown): value is CliAppError;
+declare function toCliAppError(value: unknown): CliAppError;
+//#endregion
+//#region src/envelope.d.ts
+interface Meta {
+  requestId: string;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  verbose: boolean;
+}
+interface CliSuccess<T> {
+  ok: true;
+  data: T;
+  meta: Meta;
+}
+interface CliError {
+  ok: false;
+  error: {
+    code: CliErrorCode;
+    message: string;
+    details?: unknown;
+  };
+}
+type CliEnvelope<T> = CliSuccess<T> | CliError;
+declare function createSuccessEnvelope<T>(data: T, meta: Meta): CliSuccess<T>;
+declare function createErrorEnvelope(code: CliErrorCode, message: string, details?: unknown): CliError;
+//#endregion
+//#region src/command-context.d.ts
+interface CreateCommandContextOptions {
+  clock?: () => number;
+  now?: () => Date;
+  requestIdFactory?: () => string;
+  verbose?: boolean;
+}
+interface CommandContext {
+  requestId: string;
+  startedAt: string;
+  verbose: boolean;
+  toMeta: () => Meta;
+}
+declare function createCommandContext(options?: CreateCommandContextOptions): CommandContext;
+//#endregion
+//#region src/exit-codes.d.ts
+type CliExitCode = 0 | 2 | 3 | 4 | 5 | 10;
+declare const EXIT_CODES: {
+  readonly SUCCESS: 0;
+  readonly ARGUMENT_ERROR: 2;
+  readonly AUTH_OR_CONFIG_ERROR: 3;
+  readonly NOT_FOUND: 4;
+  readonly UPSTREAM_ERROR: 5;
+  readonly UNKNOWN_ERROR: 10;
+};
+declare function mapErrorCodeToExitCode(code: CliErrorCode): CliExitCode;
+//#endregion
+export { CLI_ERROR_CODES, CliAppError, CliAppErrorOptions, CliEnvelope, CliError, CliErrorCode, CliExitCode, CliSuccess, CommandContext, CreateCommandContextOptions, EXIT_CODES, Meta, createCommandContext, createErrorEnvelope, createSuccessEnvelope, isCliAppError, mapErrorCodeToExitCode, toCliAppError };

package/dist/index.mjs

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+
+//#region src/command-context.ts
+function createCommandContext(options = {}) {
+	const clock = options.clock ?? Date.now;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const requestIdFactory = options.requestIdFactory ?? randomUUID;
+	const verbose = options.verbose ?? false;
+	const startTimeMs = clock();
+	const startedAt = now().toISOString();
+	const requestId = requestIdFactory();
+	return {
+		requestId,
+		startedAt,
+		verbose,
+		toMeta: () => {
+			const endTimeMs = clock();
+			const durationMs = Math.max(0, endTimeMs - startTimeMs);
+			return {
+				requestId,
+				startedAt,
+				finishedAt: now().toISOString(),
+				durationMs,
+				verbose
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/envelope.ts
+function createSuccessEnvelope(data, meta) {
+	return {
+		ok: true,
+		data,
+		meta
+	};
+}
+function createErrorEnvelope(code, message, details) {
+	if (details === void 0) return {
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	};
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			details
+		}
+	};
+}
+
+//#endregion
+//#region src/errors.ts
+const CLI_ERROR_CODES = [
+	"E_ARG_INVALID",
+	"E_ARG_MISSING",
+	"E_ARG_CONFLICT",
+	"E_ARG_UNSUPPORTED",
+	"E_AUTH_REQUIRED",
+	"E_AUTH_INVALID",
+	"E_NOT_FOUND_RESOURCE",
+	"E_UPSTREAM_NETWORK",
+	"E_UPSTREAM_TIMEOUT",
+	"E_UPSTREAM_BAD_RESPONSE",
+	"E_UNKNOWN"
+];
+var CliAppError = class extends Error {
+	code;
+	details;
+	constructor(options) {
+		super(options.message, { cause: options.cause });
+		this.name = "CliAppError";
+		this.code = options.code;
+		this.details = options.details;
+	}
+};
+function isCliAppError(value) {
+	return value instanceof CliAppError;
+}
+function toCliAppError(value) {
+	if (isCliAppError(value)) return value;
+	if (value instanceof Error) return new CliAppError({
+		code: "E_UNKNOWN",
+		message: value.message,
+		details: { name: value.name },
+		cause: value
+	});
+	return new CliAppError({
+		code: "E_UNKNOWN",
+		message: "Unknown error",
+		details: value
+	});
+}
+
+//#endregion
+//#region src/exit-codes.ts
+const EXIT_CODES = {
+	SUCCESS: 0,
+	ARGUMENT_ERROR: 2,
+	AUTH_OR_CONFIG_ERROR: 3,
+	NOT_FOUND: 4,
+	UPSTREAM_ERROR: 5,
+	UNKNOWN_ERROR: 10
+};
+function mapErrorCodeToExitCode(code) {
+	if (code.startsWith("E_ARG_")) return EXIT_CODES.ARGUMENT_ERROR;
+	if (code.startsWith("E_AUTH_")) return EXIT_CODES.AUTH_OR_CONFIG_ERROR;
+	if (code.startsWith("E_NOT_FOUND_")) return EXIT_CODES.NOT_FOUND;
+	if (code.startsWith("E_UPSTREAM_")) return EXIT_CODES.UPSTREAM_ERROR;
+	return EXIT_CODES.UNKNOWN_ERROR;
+}
+
+//#endregion
+export { CLI_ERROR_CODES, CliAppError, EXIT_CODES, createCommandContext, createErrorEnvelope, createSuccessEnvelope, isCliAppError, mapErrorCodeToExitCode, toCliAppError };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "clawkit-cli-core",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Shared CLI contracts and helpers for clawkit packages",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "check": "pnpm typecheck && pnpm test"
+  }
+}