@gajae-code/utils 0.12.21 → 0.13.0

package/dist/types/cli.d.ts

@@ -6,6 +6,8 @@ export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "st
     multiple?: boolean;
     options?: readonly string[];
     required?: boolean;
+    /** The string value may be omitted; parsers decide whether to consume it. */
+    optionalValue?: boolean;
 }
 export interface ArgDescriptor {
     kind: "string";
@@ -21,6 +23,8 @@ interface FlagInput {
     multiple?: boolean;
     options?: readonly string[];
     required?: boolean;
+    /** The string value may be omitted; parsers decide whether to consume it. */
+    optionalValue?: boolean;
 }
 interface ArgInput {
     description?: string;

package/dist/types/dirs.d.ts

@@ -137,6 +137,8 @@ export declare function getSessionsDir(agentDir?: string): string;
 export declare function getBlobsDir(agentDir?: string): string;
 /** Get the resident-text cache root for a profile agent directory. */
 export declare function getResidentCacheRootDir(profileAgentDir: string): string;
+/** Get the managed cold-history sidecar cache root for a profile agent directory. */
+export declare function getSidecarCacheRootDir(profileAgentDir: string): string;
 /** Get the custom themes directory (~/.gjc/agent/themes). */
 export declare function getCustomThemesDir(agentDir?: string): string;
 /** Get the tools directory (~/.gjc/agent/tools). */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.12.21",
+	"version": "0.13.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.12.21",
+		"@gajae-code/natives": "0.13.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/cli.ts

@@ -23,6 +23,8 @@ export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "st
 	multiple?: boolean;
 	options?: readonly string[];
 	required?: boolean;
+	/** The string value may be omitted; parsers decide whether to consume it. */
+	optionalValue?: boolean;
 }
 
 export interface ArgDescriptor {
@@ -40,6 +42,8 @@ interface FlagInput {
 	multiple?: boolean;
 	options?: readonly string[];
 	required?: boolean;
+	/** The string value may be omitted; parsers decide whether to consume it. */
+	optionalValue?: boolean;
 }
 
 interface ArgInput {
@@ -352,7 +356,14 @@ function renderCommandBody(lines: string[], Cmd: CommandCtor): void {
 		for (const [name, desc] of flagEntries) {
 			const charPart = desc.char ? `-${desc.char}, ` : "    ";
 			const namePart = `--${name}`;
-			const typePart = desc.kind === "boolean" ? "" : desc.kind === "integer" ? "=<int>" : "=<value>";
+			const typePart =
+				desc.kind === "boolean"
+					? ""
+					: desc.kind === "integer"
+						? "=<int>"
+						: desc.optionalValue
+							? "[=<value>]"
+							: "=<value>";
 			formatted.push([`  ${charPart}${namePart}${typePart}`, desc.description ?? ""]);
 		}
 		const maxLeft = Math.max(...formatted.map(([l]) => l.length));
@@ -430,7 +441,9 @@ export async function run(opts: RunOptions): Promise<void> {
 
 	// Per-command help. Commands with nested subcommands can opt into receiving
 	// help flags themselves so `cmd subcommand --help` can render subcommand help.
-	if (commandArgv.includes("--help") || commandArgv.includes("-h")) {
+	const delimiterIndex = commandArgv.indexOf("--");
+	const helpArgs = delimiterIndex === -1 ? commandArgv : commandArgv.slice(0, delimiterIndex);
+	if (helpArgs.includes("--help") || helpArgs.includes("-h")) {
 		const entry = findEntry(opts.commands, commandId);
 		if (!entry) {
 			process.stderr.write(`Unknown command: ${commandId}\n`);

package/src/dirs.ts

@@ -551,6 +551,11 @@ export function getResidentCacheRootDir(profileAgentDir: string): string {
 	return dirs.agentSubdir(profileAgentDir, "resident-cache", "cache");
 }
 
+/** Get the managed cold-history sidecar cache root for a profile agent directory. */
+export function getSidecarCacheRootDir(profileAgentDir: string): string {
+	return dirs.agentSubdir(profileAgentDir, "sidecar-cache", "cache");
+}
+
 /** Get the custom themes directory (~/.gjc/agent/themes). */
 export function getCustomThemesDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "themes");