@miruzero/zgpt 0.1.5 → 0.1.6

package/README.md

@@ -50,7 +50,9 @@ const chatgpt = require('@miruzero/zgpt');
 
 The npm package name and the CLI binary name are independent; installing **only** `@miruzero/zgpt` does not create a local `node_modules/zgpt` alias.
 
-The package exposes the `zgpt` executable through npm's `bin` field. A local `npm install` does not add `node_modules/.bin` to the parent shell's PATH, so use `npx zgpt` for local installs or install globally for the bare `zgpt` command.
+The package exposes the `zgpt` executable through npm's `bin` field. Running **`zgpt` with no arguments displays root Help** (as do `zgpt help` and `zgpt --help`) without making an HTTP request. A local `npm install` does not add `node_modules/.bin` to the parent shell's PATH, so use `npx zgpt` for local installs or install globally for the bare `zgpt` command.
+
+**Windows troubleshooting (HTTP 401 while `auth-status` is valid):** `zgpt auth-status` reads local token metadata and does **not** probe the upstream server. Versions before `0.1.6` can report a stale token as valid when stored session expiry exceeds its JWT `exp`. Check `Get-Command zgpt` and `node -p "require('@miruzero/zgpt/package.json').version"` in the consuming project to identify the exact installation. Each npm installation maintains independent state unless `ZERO_CHATGPT_STATE_DIR` points to the same persistent writable directory. For example, set `$env:ZERO_CHATGPT_STATE_DIR = "$HOME\\.zgpt\\state"` in PowerShell before running the CLI and run `zgpt login` to acquire authentication for that directory. Do not copy or display access tokens or cookies when troubleshooting. `zgpt get --help` displays local usage without requesting the Backend in `0.1.6`.
 
 ### Hierarchical SDK → CLI automatic command discovery
 
@@ -150,7 +152,7 @@ zgpt api apps getAppsDirectoryBrowse --query category=productivity
 zgpt api composer getComposerItems --query 'entrypoint=chat&limit=10'
 ```
 
-The `--query` flag accepts shell-friendly `name=value` or `name=value&name2=value2`, as well as a JSON object. For GET routes requiring query parameters, see `zgpt api show "GET /backend-api/..."` and `src/api/contracts.json`. The auditor and capture scanners are developer scripts in this source checkout and are not bundled in the npm package. Version `0.1.5` includes the release-ready SDK/CLI changes described above once published.
+The `--query` flag accepts shell-friendly `name=value` or `name=value&name2=value2`, as well as a JSON object. For GET routes requiring query parameters, see `zgpt api show "GET /backend-api/..."` and `src/api/contracts.json`. The auditor and capture scanners are developer scripts in this source checkout and are not bundled in the npm package. Version `0.1.5` was published; changes to JWT-expiry validation and `get --help` are prepared in local source `0.1.6` and require a new npm publish before external installations receive them.
 
 ### Custom MCP server CRUD and action refresh
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miruzero/zgpt",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "commonjs",
   "main": "src/index.js",
   "bin": {
@@ -19,7 +19,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "classic-level": "^3.0.0"
+    "classic-level": "^3.0.0",
+    "zgpt": "npm:@miruzero/zgpt@^0.1.5"
   },
   "allowScripts": {
     "classic-level@3.0.0": true

package/src/auth/index.js

@@ -12,6 +12,13 @@ const tokenExpiry = (token) => {
     return Number.isFinite(payload.exp) ? new Date(payload.exp * 1000).toISOString() : null;
   } catch { return null; }
 };
+// Cached session expiry can exceed the actual JWT expiry. Never mark a JWT as
+// usable past its own exp claim merely because persisted metadata says so.
+const earliestExpiry = (token, reported) => {
+  const claim = tokenExpiry(token);
+  const parsed = [claim, reported].map(value => Date.parse(value || '')).filter(Number.isFinite);
+  return parsed.length ? new Date(Math.min(...parsed)).toISOString() : (reported || claim || null);
+};
 const isExpired = (expires) => { const at = Date.parse(expires || ''); return Number.isFinite(at) && at <= Date.now(); };
 const rawFromEnv = (env) => {
   const token = typeof env.ZERO_CHATGPT_ACCESS_TOKEN === 'string' ? env.ZERO_CHATGPT_ACCESS_TOKEN.trim() : '';
@@ -24,7 +31,7 @@ const rawFromFile = (env) => {
   const file = paths.authFile(env);
   const data = readJson(file);
   if (!data || typeof data.accessToken !== 'string' || !data.accessToken) return null;
-  return { tokenName: data.tokenName || 'ACCESS', accessToken: data.accessToken, expires: data.expires || tokenExpiry(data.accessToken), updatedAt: data.updatedAt || null, source: 'file', file };
+  return { tokenName: data.tokenName || 'ACCESS', accessToken: data.accessToken, expires: earliestExpiry(data.accessToken, data.expires), updatedAt: data.updatedAt || null, source: 'file', file };
 };
 
 exports.status = ({ env = process.env } = {}) => {
@@ -39,7 +46,7 @@ exports.importSession = ({ body, env = process.env, source = 'session' } = {}) =
   if (!accessToken || typeof accessToken !== 'string') {
     throw Object.assign(new Error('ChatGPT session did not provide an access token'), { code: 'AUTH_REQUIRED' });
   }
-  const expires = body?.expires || body?.expires_at || tokenExpiry(accessToken);
+  const expires = earliestExpiry(accessToken, body?.expires || body?.expires_at);
   const value = {
     tokenName: 'ACCESS',
     accessToken,
@@ -69,7 +76,7 @@ exports.refresh = async ({ env = process.env, acquireSession, fresh = false } =
   const value = {
     tokenName: 'ACCESS',
     accessToken,
-    expires: body?.expires || body?.expires_at || tokenExpiry(accessToken),
+    expires: earliestExpiry(accessToken, body?.expires || body?.expires_at),
     updatedAt: new Date().toISOString()
   };
   writeJson(paths.authFile(env), value);

package/src/cli/sdk-dispatch.js

@@ -306,7 +306,8 @@ exports.run = async (argv, options = {}) => {
   const stdout = options.stdout || console.log;
   const stderr = options.stderr || console.error;
   try {
-    if (argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
+    // A bare `zgpt` is a help request, not an unknown SDK namespace.
+    if (!argv.length || argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
       const name = argv[1];
       if (argv.length > 3 || argv.length === 3 && name !== 'api') throw error('Usage: zgpt help [namespace]');
       if (!name) stdout(exports.help(runtime));

package/src/cli.js

@@ -39,6 +39,13 @@ exports.run = async (argv = [], options = {}) => {
   if (command === 'help' || command === '--help' || command === '-h') {
     return require('./cli/sdk-dispatch').run(argv, { ...options, stdout, stderr });
   }
+  // A help flag directly after a legacy command must never become a room ID.
+  if (['get', 'export'].includes(command) && ['--help', '-h', 'help'].includes(argv[1])) {
+    stdout(command === 'get'
+      ? 'Usage: zgpt get <conversation-id> [--json | --debug | --limit N]'
+      : 'Usage: zgpt export <conversation-id> [--json | --debug | --limit N] [--out PATH]');
+    return 0;
+  }
   // SDK namespaces are routed dynamically; legacy aliases below remain compatible.
   const runtime = options.runtime || require('./index');
   if (command === 'functions' || command === 'call' || command === 'api' ||