@kidd-cli/core 0.1.0

package/dist/create-store-BQUX0tAn.js

@@ -0,0 +1,197 @@
+import { n as resolveLocalPath, t as resolveGlobalPath } from "./project-NPtYX2ZX.js";
+import { join } from "node:path";
+import { attempt, err, match, ok } from "@kidd-cli/utils/fp";
+import { jsonParse, jsonStringify } from "@kidd-cli/utils/json";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+//#region src/lib/store/create-store.ts
+/**
+* Create a file-backed {@link FileStore} that resolves JSON files from project-local
+* or global home directories.
+*
+* @param options - Store configuration.
+* @returns A FileStore instance.
+*/
+function createStore(options) {
+	const { dirName, defaults } = options;
+	/**
+	* Resolve the local project directory for the store.
+	*
+	* @private
+	* @param startDir - Optional directory to start searching from.
+	* @returns The local directory path, or null if no project root is found.
+	*/
+	function getLocalDir(startDir) {
+		return resolveLocalPath({
+			dirName,
+			startDir
+		});
+	}
+	/**
+	* Resolve the global home directory for the store.
+	*
+	* @private
+	* @returns The global directory path.
+	*/
+	function getGlobalDir() {
+		return resolveGlobalPath({ dirName });
+	}
+	/**
+	* Read the raw string content from a file path.
+	*
+	* @private
+	* @param filePath - The file path to read.
+	* @returns The file content, or null if the file does not exist or cannot be read.
+	*/
+	function loadFromPath(filePath) {
+		if (!existsSync(filePath)) return null;
+		const [error, content] = attempt(() => readFileSync(filePath, "utf8"));
+		if (error) return null;
+		return content;
+	}
+	/**
+	* Resolve a file from local or global directories based on the source strategy.
+	*
+	* @private
+	* @param resolveOptions - Resolution options.
+	* @returns The resolved result, or null if not found.
+	*/
+	function resolveFromSource(resolveOptions) {
+		return match(resolveOptions.source).with("local", () => {
+			if (!resolveOptions.localDir) return null;
+			return resolveOptions.handler(join(resolveOptions.localDir, resolveOptions.filename));
+		}).with("global", () => resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename))).with("resolve", () => {
+			if (resolveOptions.localDir) {
+				const localResult = resolveOptions.handler(join(resolveOptions.localDir, resolveOptions.filename));
+				if (localResult !== null) return localResult;
+			}
+			return resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename));
+		}).exhaustive();
+	}
+	/**
+	* Load the raw string content of a store file.
+	*
+	* @private
+	* @param filename - The filename to load.
+	* @param loadOptions - Options controlling source resolution.
+	* @returns The raw file content, or null if not found.
+	*/
+	function loadRaw(filename, loadOptions = {}) {
+		const { source: loadSource = "resolve", startDir } = loadOptions;
+		const localDir = getLocalDir(startDir);
+		return resolveFromSource({
+			filename,
+			globalDir: getGlobalDir(),
+			handler: loadFromPath,
+			localDir,
+			source: loadSource
+		});
+	}
+	/**
+	* Load and parse a store file as JSON, merging with defaults if available.
+	*
+	* @private
+	* @param filename - The filename to load.
+	* @param loadOptions - Options controlling source resolution.
+	* @returns The parsed data, defaults, or null.
+	*/
+	function load(filename, loadOptions = {}) {
+		const raw = loadRaw(filename, loadOptions);
+		if (raw === null) return defaults ?? null;
+		const [parseError, parsed] = jsonParse(raw);
+		if (parseError) return defaults ?? null;
+		if (defaults) return {
+			...defaults,
+			...parsed
+		};
+		return parsed;
+	}
+	/**
+	* Check if a file exists at the given path and return the path if so.
+	*
+	* @private
+	* @param filePath - The file path to check.
+	* @returns The file path if it exists, or null.
+	*/
+	function checkFileExists(filePath) {
+		if (existsSync(filePath)) return filePath;
+		return null;
+	}
+	/**
+	* Resolve the file path for a store file without reading its content.
+	*
+	* @private
+	* @param filename - The filename to resolve.
+	* @param loadOptions - Options controlling source resolution.
+	* @returns The resolved file path, or null if not found.
+	*/
+	function getFilePath(filename, loadOptions = {}) {
+		const { source: fileSource = "resolve", startDir } = loadOptions;
+		const localDir = getLocalDir(startDir);
+		return resolveFromSource({
+			filename,
+			globalDir: getGlobalDir(),
+			handler: checkFileExists,
+			localDir,
+			source: fileSource
+		});
+	}
+	/**
+	* Serialize data to JSON and write it to a store file.
+	*
+	* Creates the target directory if it does not exist. Defaults to
+	* the global home directory when no source is specified.
+	*
+	* @private
+	* @param filename - The filename to write.
+	* @param data - The data to serialize.
+	* @param saveOptions - Options controlling the write target.
+	* @returns A Result with the written file path on success.
+	*/
+	function save(filename, data, saveOptions = {}) {
+		const { source: saveSource = "global", startDir } = saveOptions;
+		const dir = resolveSaveDir({
+			globalDir: getGlobalDir(),
+			localDir: getLocalDir(startDir),
+			source: saveSource
+		});
+		if (dir === null) return err(/* @__PURE__ */ new Error(`Cannot save to "${saveSource}" — no local project directory found`));
+		const [stringifyError, json] = jsonStringify(data, { pretty: true });
+		if (stringifyError) return err(stringifyError);
+		const filePath = join(dir, filename);
+		const [writeError] = attempt(() => {
+			mkdirSync(dir, {
+				mode: 448,
+				recursive: true
+			});
+			writeFileSync(filePath, json, {
+				encoding: "utf8",
+				mode: 384
+			});
+		});
+		if (writeError) return err(writeError);
+		return ok(filePath);
+	}
+	return {
+		getFilePath,
+		getGlobalDir,
+		getLocalDir,
+		load,
+		loadRaw,
+		save
+	};
+}
+/**
+* Resolve the target directory for a save operation.
+*
+* @private
+* @param options - Resolution options.
+* @returns The directory path, or null when `local` is requested but unavailable.
+*/
+function resolveSaveDir(options) {
+	return match(options.source).with("local", () => options.localDir).with("global", () => options.globalDir).exhaustive();
+}
+
+//#endregion
+export { createStore as t };
+//# sourceMappingURL=create-store-BQUX0tAn.js.map

package/dist/create-store-BQUX0tAn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store-BQUX0tAn.js","names":[],"sources":["../src/lib/store/create-store.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nimport { attempt, err, match, ok } from '@kidd-cli/utils/fp'\nimport type { Result } from '@kidd-cli/utils/fp'\nimport { jsonParse, jsonStringify } from '@kidd-cli/utils/json'\n\nimport { resolveGlobalPath, resolveLocalPath } from '@/lib/project/index.js'\nimport type { PathSource } from '@/lib/project/types.js'\n\nimport type { FileStore, LoadOptions, SaveOptions, StoreOptions } from './types.js'\n\n/**\n * Create a file-backed {@link FileStore} that resolves JSON files from project-local\n * or global home directories.\n *\n * @param options - Store configuration.\n * @returns A FileStore instance.\n */\nexport function createStore<TData = unknown>(options: StoreOptions<TData>): FileStore<TData> {\n  const { dirName, defaults } = options\n\n  /**\n   * Resolve the local project directory for the store.\n   *\n   * @private\n   * @param startDir - Optional directory to start searching from.\n   * @returns The local directory path, or null if no project root is found.\n   */\n  function getLocalDir(startDir?: string): string | null {\n    return resolveLocalPath({ dirName, startDir })\n  }\n\n  /**\n   * Resolve the global home directory for the store.\n   *\n   * @private\n   * @returns The global directory path.\n   */\n  function getGlobalDir(): string {\n    return resolveGlobalPath({ dirName })\n  }\n\n  /**\n   * Read the raw string content from a file path.\n   *\n   * @private\n   * @param filePath - The file path to read.\n   * @returns The file content, or null if the file does not exist or cannot be read.\n   */\n  function loadFromPath(filePath: string): string | null {\n    if (!existsSync(filePath)) {\n      return null\n    }\n    const [error, content] = attempt(() => readFileSync(filePath, 'utf8'))\n    if (error) {\n      return null\n    }\n    return content\n  }\n\n  /**\n   * Resolve a file from local or global directories based on the source strategy.\n   *\n   * @private\n   * @param resolveOptions - Resolution options.\n   * @returns The resolved result, or null if not found.\n   */\n  function resolveFromSource<T>(resolveOptions: {\n    source: PathSource\n    localDir: string | null\n    globalDir: string\n    filename: string\n    handler: (filePath: string) => T | null\n  }): T | null {\n    return match(resolveOptions.source)\n      .with('local', (): T | null => {\n        if (!resolveOptions.localDir) {\n          return null\n        }\n        return resolveOptions.handler(join(resolveOptions.localDir, resolveOptions.filename))\n      })\n      .with('global', () =>\n        resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename))\n      )\n      .with('resolve', (): T | null => {\n        if (resolveOptions.localDir) {\n          const localResult = resolveOptions.handler(\n            join(resolveOptions.localDir, resolveOptions.filename)\n          )\n          if (localResult !== null) {\n            return localResult\n          }\n        }\n        return resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename))\n      })\n      .exhaustive()\n  }\n\n  /**\n   * Load the raw string content of a store file.\n   *\n   * @private\n   * @param filename - The filename to load.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The raw file content, or null if not found.\n   */\n  function loadRaw(filename: string, loadOptions: LoadOptions = {}): string | null {\n    const { source: loadSource = 'resolve', startDir } = loadOptions\n    const localDir = getLocalDir(startDir)\n    const globalDir = getGlobalDir()\n\n    return resolveFromSource<string>({\n      filename,\n      globalDir,\n      handler: loadFromPath,\n      localDir,\n      source: loadSource,\n    })\n  }\n\n  /**\n   * Load and parse a store file as JSON, merging with defaults if available.\n   *\n   * @private\n   * @param filename - The filename to load.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The parsed data, defaults, or null.\n   */\n  function load(filename: string, loadOptions: LoadOptions = {}): TData | null {\n    const raw = loadRaw(filename, loadOptions)\n\n    if (raw === null) {\n      return defaults ?? null\n    }\n\n    const [parseError, parsed] = jsonParse(raw)\n    if (parseError) {\n      return defaults ?? null\n    }\n\n    if (defaults) {\n      return { ...defaults, ...(parsed as Partial<TData>) }\n    }\n    return parsed as TData\n  }\n\n  /**\n   * Check if a file exists at the given path and return the path if so.\n   *\n   * @private\n   * @param filePath - The file path to check.\n   * @returns The file path if it exists, or null.\n   */\n  function checkFileExists(filePath: string): string | null {\n    if (existsSync(filePath)) {\n      return filePath\n    }\n    return null\n  }\n\n  /**\n   * Resolve the file path for a store file without reading its content.\n   *\n   * @private\n   * @param filename - The filename to resolve.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The resolved file path, or null if not found.\n   */\n  function getFilePath(filename: string, loadOptions: LoadOptions = {}): string | null {\n    const { source: fileSource = 'resolve', startDir } = loadOptions\n    const localDir = getLocalDir(startDir)\n    const globalDir = getGlobalDir()\n\n    return resolveFromSource<string>({\n      filename,\n      globalDir,\n      handler: checkFileExists,\n      localDir,\n      source: fileSource,\n    })\n  }\n\n  /**\n   * Serialize data to JSON and write it to a store file.\n   *\n   * Creates the target directory if it does not exist. Defaults to\n   * the global home directory when no source is specified.\n   *\n   * @private\n   * @param filename - The filename to write.\n   * @param data - The data to serialize.\n   * @param saveOptions - Options controlling the write target.\n   * @returns A Result with the written file path on success.\n   */\n  function save(filename: string, data: unknown, saveOptions: SaveOptions = {}): Result<string> {\n    const { source: saveSource = 'global', startDir } = saveOptions\n\n    const dir = resolveSaveDir({ globalDir: getGlobalDir(), localDir: getLocalDir(startDir), source: saveSource })\n\n    if (dir === null) {\n      return err(new Error(`Cannot save to \"${saveSource}\" — no local project directory found`))\n    }\n\n    const [stringifyError, json] = jsonStringify(data, { pretty: true })\n\n    if (stringifyError) {\n      return err(stringifyError)\n    }\n\n    const filePath = join(dir, filename)\n\n    const [writeError] = attempt(() => {\n      mkdirSync(dir, { mode: 0o700, recursive: true })\n      writeFileSync(filePath, json, { encoding: 'utf8', mode: 0o600 })\n    })\n\n    if (writeError) {\n      return err(writeError)\n    }\n\n    return ok(filePath)\n  }\n\n  return {\n    getFilePath,\n    getGlobalDir,\n    getLocalDir,\n    load,\n    loadRaw,\n    save,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve the target directory for a save operation.\n *\n * @private\n * @param options - Resolution options.\n * @returns The directory path, or null when `local` is requested but unavailable.\n */\nfunction resolveSaveDir(options: {\n  readonly localDir: string | null\n  readonly globalDir: string\n  readonly source: 'local' | 'global'\n}): string | null {\n  return match(options.source)\n    .with('local', (): string | null => options.localDir)\n    .with('global', () => options.globalDir)\n    .exhaustive()\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { a as CommandDef, c as MiddlewareFn, i as Command, l as Context, n as AutoloadOptions, o as CommandMap, r as CliOptions, s as Middleware, t as ArgsDef } from "./types-kjpRau0U.js";
+import { defineConfig } from "@kidd-cli/config";
+import { z } from "zod";
+
+//#region src/cli.d.ts
+/**
+* Bootstrap and run the CLI application.
+*
+* Parses argv, resolves the matched command, loads config, runs the
+* middleware chain, and invokes the command handler.
+*
+* @param options - CLI configuration including name, version, commands, and middleware.
+*/
+declare function cli<TSchema extends z.ZodType = z.ZodType>(options: CliOptions<TSchema>): Promise<void>;
+//#endregion
+//#region src/command.d.ts
+/**
+* Define a CLI command with typed args, config, and handler.
+*
+* @param def - Command definition including description, args schema, and handler.
+* @returns A resolved Command object for registration in the command map.
+*/
+declare function command<TArgsDef extends ArgsDef = ArgsDef, TConfig extends Record<string, unknown> = Record<string, unknown>>(def: CommandDef<TArgsDef, TConfig>): Command<TArgsDef, TConfig>;
+//#endregion
+//#region src/autoloader.d.ts
+/**
+* Scan a directory for command files and produce a CommandMap.
+*
+* @param options - Autoload configuration (directory override, etc.).
+* @returns A promise resolving to a CommandMap built from the directory tree.
+*/
+declare function autoload(options?: AutoloadOptions): Promise<CommandMap>;
+//#endregion
+//#region src/context/decorate.d.ts
+/**
+* Add a typed, immutable property to a context instance.
+*
+* Middleware authors use this to extend ctx with custom properties.
+* Pair with module augmentation on Context for type safety:
+*
+* ```ts
+* declare module '@kidd-cli/core' {
+*   interface Context {
+*     readonly github: HttpClient
+*   }
+* }
+* ```
+*
+* **Note:** This function mutates the context object via
+* `Object.defineProperty`. The added property is non-writable and
+* non-configurable, making it effectively frozen after assignment.
+* Mutation is intentional here — the context is assembled incrementally
+* across middleware, and copying the entire object on each decoration
+* would break the single-reference threading model used by the runner.
+*
+* @param ctx - The context instance to decorate (mutated in place).
+* @param key - The property name.
+* @param value - The property value (frozen after assignment).
+* @returns The same ctx reference, now carrying the new property.
+*/
+declare function decorateContext<TKey extends string, TValue>(ctx: Context, key: TKey, value: TValue): Context;
+//#endregion
+//#region src/middleware.d.ts
+/**
+* Create a typed middleware that runs before command handlers.
+*
+* @param handler - The middleware function receiving ctx and next.
+* @returns A Middleware object for use in the cli() middleware stack.
+*/
+declare function middleware<TConfig extends Record<string, unknown> = Record<string, unknown>>(handler: MiddlewareFn<TConfig>): Middleware<TConfig>;
+//#endregion
+export { type Command, type Context, autoload, cli, command, decorateContext, defineConfig, middleware };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli.ts","../src/command.ts","../src/autoloader.ts","../src/context/decorate.ts","../src/middleware.ts"],"mappings":";;;;;;;;;AAyBA;;;;iBAAsB,GAAA,iBAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,CAAA,CACtD,OAAA,EAAS,UAAA,CAAW,OAAA,IACnB,OAAA;;;;;;;;AAFH;iBCfgB,OAAA,kBACG,OAAA,GAAU,OAAA,kBACX,MAAA,oBAA0B,MAAA,kBAAA,CAC1C,GAAA,EAAK,UAAA,CAAW,QAAA,EAAU,OAAA,IAAW,OAAA,CAAY,QAAA,EAAU,OAAA;;;;;;;;ADY7D;iBEPsB,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;;AFOnE;;;;;;;;;;;;;;;;;;;;;iBGGgB,eAAA,6BAAA,CACd,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,IAAA,EACL,KAAA,EAAO,MAAA,GACN,OAAA;;;;;;;;AHPH;iBIfgB,UAAA,iBAA2B,MAAA,oBAA0B,MAAA,kBAAA,CACnE,OAAA,EAAS,YAAA,CAAa,OAAA,IACrB,UAAA,CAAW,OAAA"}