hzl-cli 2.1.0 → 2.3.0

package/dist/config.test.js

@@ -1,14 +1,25 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { readConfig, resolveDbPaths } from './config.js';
+import { getConfigPath, isDevMode, readConfig, resolveDbPaths } from './config.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
 describe('nested db config', () => {
     const testDir = path.join(os.tmpdir(), `config-test-${Date.now()}`);
+    const xdgDataHome = process.platform === 'win32'
+        ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'))
+        : (process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'));
+    const xdgConfigHome = process.platform === 'win32'
+        ? (process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'))
+        : (process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'));
     beforeEach(() => {
         fs.mkdirSync(testDir, { recursive: true });
     });
     afterEach(() => {
+        delete process.env.HZL_DB;
+        delete process.env.HZL_ALLOW_PROD_DB;
+        delete process.env.HZL_CONFIG;
+        delete process.env.HZL_ALLOW_PROD_CONFIG;
+        delete process.env.HZL_DEV_MODE;
         fs.rmSync(testDir, { recursive: true, force: true });
     });
     it('reads nested events path', () => {
@@ -48,5 +59,36 @@ describe('nested db config', () => {
         const config = readConfig(configPath);
         expect(config.claimStaggerMs).toBe(750);
     });
+    it('blocks production XDG DB paths while in dev mode', () => {
+        const prodPath = path.join(xdgDataHome, 'hzl', 'events.db');
+        process.env.HZL_DB = prodPath;
+        if (!isDevMode()) {
+            expect(() => resolveDbPaths(undefined, path.join(testDir, 'config.json'))).not.toThrow();
+            return;
+        }
+        expect(() => resolveDbPaths(undefined, path.join(testDir, 'config.json'))).toThrow(/Refusing to use production DB path in dev mode/);
+    });
+    it('allows production XDG DB paths with explicit override', () => {
+        const prodPath = path.join(xdgDataHome, 'hzl', 'events.db');
+        process.env.HZL_DB = prodPath;
+        process.env.HZL_ALLOW_PROD_DB = '1';
+        const paths = resolveDbPaths(undefined, path.join(testDir, 'config.json'));
+        expect(paths.eventsDbPath).toBe(prodPath);
+    });
+    it('blocks production XDG config path while in dev mode', () => {
+        const prodConfigPath = path.join(xdgConfigHome, 'hzl', 'config.json');
+        process.env.HZL_CONFIG = prodConfigPath;
+        if (!isDevMode()) {
+            expect(getConfigPath()).toBe(prodConfigPath);
+            return;
+        }
+        expect(() => getConfigPath()).toThrow(/Refusing to use production config path in dev mode/);
+    });
+    it('allows production XDG config path with explicit override', () => {
+        const prodConfigPath = path.join(xdgConfigHome, 'hzl', 'config.json');
+        process.env.HZL_CONFIG = prodConfigPath;
+        process.env.HZL_ALLOW_PROD_CONFIG = '1';
+        expect(getConfigPath()).toBe(prodConfigPath);
+    });
 });
 //# sourceMappingURL=config.test.js.map

package/dist/config.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -11,7 +11,8 @@ export declare class CLIError extends Error {
     readonly exitCode: ExitCode;
     readonly code: string;
     readonly details?: unknown;
-    constructor(message: string, exitCode?: ExitCode, code?: string, details?: unknown);
+    readonly suggestions?: string[];
+    constructor(message: string, exitCode?: ExitCode, code?: string, details?: unknown, suggestions?: string[]);
 }
 export declare function handleError(error: unknown, json?: boolean): void;
 export declare function codeForExitCode(exitCode: ExitCode): string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,oBAAY,QAAQ;IAClB,OAAO,IAAI;IACX,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,QAAQ,IAAI;IACZ,aAAa,IAAI;IACjB,eAAe,IAAI;CACpB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAgC,EAC1C,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO;CAQpB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,OAAe,GAAG,IAAI,CAiBvE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAmB1D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,oBAAY,QAAQ;IAClB,OAAO,IAAI;IACX,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,QAAQ,IAAI;IACZ,aAAa,IAAI;IACjB,eAAe,IAAI;CACpB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;gBAGrC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAgC,EAC1C,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,EACjB,WAAW,CAAC,EAAE,MAAM,EAAE;CASzB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,OAAe,GAAG,IAAI,CAkCvE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAmB1D"}

package/dist/errors.js

@@ -14,24 +14,43 @@ export class CLIError extends Error {
     exitCode;
     code;
     details;
-    constructor(message, exitCode = ExitCode.GeneralError, code, details) {
+    suggestions;
+    constructor(message, exitCode = ExitCode.GeneralError, code, details, suggestions) {
         super(message);
         this.exitCode = exitCode;
         this.code = code ?? codeForExitCode(exitCode);
         this.details = details;
+        this.suggestions = suggestions;
         this.name = 'CLIError';
     }
 }
 export function handleError(error, json = false) {
     if (error instanceof CLIError) {
         if (json) {
-            console.log(JSON.stringify(createErrorEnvelope(error.code, error.message, error.details)));
+            console.log(JSON.stringify(createErrorEnvelope(error.code, error.message, error.details, error.suggestions)));
         }
         else {
             console.error(`Error: ${error.message}`);
+            if (error.suggestions && error.suggestions.length > 0) {
+                for (const suggestion of error.suggestions) {
+                    console.error(`Hint: ${suggestion}`);
+                }
+            }
         }
         process.exit(error.exitCode);
     }
+    if (error instanceof Error) {
+        const domainCode = error.code;
+        if (typeof domainCode === 'string' && domainCode.startsWith('task_invalid_')) {
+            if (json) {
+                console.log(JSON.stringify(createErrorEnvelope(domainCode, error.message)));
+            }
+            else {
+                console.error(`Error: ${error.message}`);
+            }
+            process.exit(ExitCode.InvalidInput);
+        }
+    }
     const message = error instanceof Error ? error.message : String(error);
     if (json) {
         console.log(JSON.stringify(createErrorEnvelope(codeForExitCode(ExitCode.GeneralError), message)));

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,CAAN,IAAY,QAQX;AARD,WAAY,QAAQ;IAClB,6CAAW,CAAA;IACX,uDAAgB,CAAA;IAChB,uDAAgB,CAAA;IAChB,uDAAgB,CAAA;IAChB,+CAAY,CAAA;IACZ,yDAAiB,CAAA;IACjB,6DAAmB,CAAA;AACrB,CAAC,EARW,QAAQ,KAAR,QAAQ,QAQnB;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjB,QAAQ,CAAW;IACnB,IAAI,CAAS;IACb,OAAO,CAAW;IAElC,YACE,OAAe,EACf,WAAqB,QAAQ,CAAC,YAAY,EAC1C,IAAa,EACb,OAAiB;QAEjB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,OAAgB,KAAK;IAC/D,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7F,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,eAAe,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpG,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAkB;IAChD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC,YAAY;YACxB,OAAO,eAAe,CAAC;QACzB,KAAK,QAAQ,CAAC,YAAY;YACxB,OAAO,eAAe,CAAC;QACzB,KAAK,QAAQ,CAAC,QAAQ;YACpB,OAAO,WAAW,CAAC;QACrB,KAAK,QAAQ,CAAC,aAAa;YACzB,OAAO,gBAAgB,CAAC;QAC1B,KAAK,QAAQ,CAAC,eAAe;YAC3B,OAAO,kBAAkB,CAAC;QAC5B,KAAK,QAAQ,CAAC,YAAY;YACxB,OAAO,eAAe,CAAC;QACzB,KAAK,QAAQ,CAAC,OAAO;YACnB,OAAO,SAAS,CAAC;QACnB;YACE,OAAO,eAAe,CAAC;IAC3B,CAAC;AACH,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.test.js

@@ -17,6 +17,12 @@ describe('CLIError', () => {
         expect(error.exitCode).toBe(ExitCode.NotFound);
         expect(error.code).toBe('not_found');
     });
+    it('creates error with suggestions', () => {
+        const error = new CLIError('Task not found: abc', ExitCode.NotFound, undefined, undefined, [
+            'hzl task list -P demo',
+        ]);
+        expect(error.suggestions).toEqual(['hzl task list -P demo']);
+    });
     it('maps exit codes to stable symbolic codes', () => {
         expect(codeForExitCode(ExitCode.InvalidUsage)).toBe('invalid_usage');
         expect(codeForExitCode(ExitCode.InvalidInput)).toBe('invalid_input');
@@ -39,5 +45,36 @@ describe('CLIError', () => {
             },
         });
     });
+    it('includes suggestions in error envelope JSON output', () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((code) => {
+            throw new Error(`exit:${code}`);
+        });
+        const error = new CLIError('Task not found: abc', ExitCode.NotFound, undefined, undefined, [
+            'hzl task list -P demo',
+        ]);
+        expect(() => handleError(error, true)).toThrow('exit:4');
+        const payload = JSON.parse(logSpy.mock.calls[0]?.[0]);
+        expect(payload.error.suggestions).toEqual(['hzl task list -P demo']);
+    });
+    it('maps typed task domain errors to invalid input exit code', () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((code) => {
+            throw new Error(`exit:${code}`);
+        });
+        const domainError = new Error('Progress must be an integer between 0 and 100');
+        domainError.code = 'task_invalid_progress';
+        expect(() => handleError(domainError, true)).toThrow('exit:3');
+        expect(exitSpy).toHaveBeenCalledWith(ExitCode.InvalidInput);
+        const payload = JSON.parse(logSpy.mock.calls[0]?.[0]);
+        expect(payload).toEqual({
+            schema_version: SCHEMA_VERSION,
+            ok: false,
+            error: {
+                code: 'task_invalid_progress',
+                message: 'Progress must be an integer between 0 and 100',
+            },
+        });
+    });
 });
 //# sourceMappingURL=errors.test.js.map

package/dist/errors.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../src/errors.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../src/errors.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,9 +2,15 @@ import { Command } from 'commander';
 import { CLIError, ExitCode } from './errors.js';
 import { resolveDbPaths, readConfig } from './config.js';
 import { formatOutput, printSuccess, printError, printTable } from './output.js';
+interface NormalizationResult {
+    args: string[];
+    notes: string[];
+}
 export declare function createProgram(): Command;
 export type LegacySurface = 'task_next' | 'json_flag' | 'assignee_flag';
 export declare function detectLegacySurface(args: string[]): LegacySurface | null;
+export declare function normalizeInvocationArgs(args: string[], program: Command): NormalizationResult;
+declare function buildUsageError(args: string[], program: Command, rawMessage: string): CLIError;
 export declare function run(argv?: string[]): Promise<void>;
-export { CLIError, ExitCode, resolveDbPaths, readConfig, formatOutput, printSuccess, printError, printTable, };
+export { CLIError, ExitCode, resolveDbPaths, readConfig, formatOutput, printSuccess, printError, printTable, buildUsageError, };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBpC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAuB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtG,wBAAgB,aAAa,IAAI,OAAO,CA+BvC;AAwCD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC;AAExE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,GAAG,IAAI,CAexE;AAiDD,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtE;AAED,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,GACX,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBpC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAuB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtG,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAyBD,wBAAgB,aAAa,IAAI,OAAO,CA4CvC;AAwCD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC;AAExE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,GAAG,IAAI,CAexE;AA2LD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAyE7F;AAkED,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,CA8FvF;AAgDD,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BtE;AAED,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,eAAe,GAChB,CAAC"}