@totoday/quinn-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @totoday/quinn-cli
+
+## 0.1.2
+
+### Patch Changes
+
+- 629fba0: Unify organization query semantics around `organizations current`:
+  - remove `organizations details` command from CLI
+  - make `organizations current` return organization details with aggregate stats
+  - align SDK and skill documentation with the simplified flow
+  - @totoday/quinn-sdk@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- 2d4beb4: Improve `quinn login` password handling:
+  - default to interactive hidden password prompt
+  - add `--password-stdin` for script-friendly secure input
+  - deprecate plain-text `--password` with warning
+  - @totoday/quinn-sdk@0.1.1

package/README.md

@@ -0,0 +1,69 @@
+# @totoday/quinn-cli
+
+CLI for Quinn organization/member/role/competency queries.
+
+## Install
+
+```bash
+npm i -g @totoday/quinn-cli
+quinn --help
+```
+
+One-off without global install:
+
+```bash
+npx @totoday/quinn-cli --help
+```
+
+## Quick Start
+
+Login (recommended: hidden password prompt):
+
+```bash
+quinn login --email <email>
+```
+
+Login via stdin (scripts/password managers):
+
+```bash
+echo "<password>" | quinn login --email <email> --password-stdin
+```
+
+Check organization:
+
+```bash
+quinn organizations current
+```
+
+## Common Commands
+
+```bash
+# members
+quinn members find alice
+quinn members list --privilege owner,admin
+quinn members get <memberId1,memberId2,user@example.com>
+
+# roles / levels / competencies
+quinn roles list
+quinn levels list --role-id <roleId>
+quinn competencies list --role-id <roleId> --level-id <levelId>
+
+# endorsements
+quinn endorsements find --uid <uid> --competency-id <competencyId>
+quinn endorsements list --uids <u1,u2> --competency-ids <c1,c2>
+```
+
+## Config
+
+CLI reads config from:
+
+- `~/.config/quinn/config.json` (default)
+- `QUINN_CONFIG_PATH` (override)
+
+Runtime override order:
+
+1. command flags
+2. env vars (`QUINN_API_URL`, `QUINN_API_TOKEN`, `QUINN_ORG_ID`)
+3. config file
+
+If `apiUrl` is missing, default is `https://api.lunapark.com`.

package/dist/index.js

@@ -64,16 +64,13 @@ function writeConfig(configPath, config) {
 }
 function resolveRuntimeConfig(opts, fileConfig) {
     return {
-        apiUrl: opts.apiUrl || process.env.QUINN_API_URL || fileConfig.apiUrl,
+        apiUrl: opts.apiUrl || process.env.QUINN_API_URL || fileConfig.apiUrl || quinn_sdk_1.DEFAULT_QUINN_API_URL,
         token: opts.apiToken || opts.token || process.env.QUINN_API_TOKEN || fileConfig.token,
         orgId: opts.orgId || process.env.QUINN_ORG_ID || fileConfig.orgId,
     };
 }
 function createClient(config) {
     const { apiUrl, token, orgId } = config;
-    if (!apiUrl) {
-        throw new Error('missing apiUrl: set --api-url or QUINN_API_URL or config');
-    }
     if (!token) {
         throw new Error('missing token: set --api-token/--token or QUINN_API_TOKEN or config');
     }
@@ -82,6 +79,60 @@ function createClient(config) {
     }
     return new quinn_sdk_1.Quinn({ apiUrl, token, orgId });
 }
+function readPasswordFromStdin() {
+    const value = node_fs_1.default.readFileSync(0, 'utf8').trim();
+    if (!value) {
+        throw new Error('empty password from stdin');
+    }
+    return value;
+}
+async function promptPasswordHidden(prompt = 'Password: ') {
+    if (!process.stdin.isTTY) {
+        throw new Error('interactive password prompt requires TTY, use --password-stdin');
+    }
+    return await new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        let password = '';
+        const cleanup = () => {
+            stdin.off('data', onData);
+            if (stdin.isTTY) {
+                stdin.setRawMode(false);
+            }
+            stdin.pause();
+        };
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            if (text === '\u0003') {
+                cleanup();
+                reject(new Error('login cancelled'));
+                return;
+            }
+            if (text === '\r' || text === '\n') {
+                cleanup();
+                stdout.write('\n');
+                const value = password.trim();
+                if (!value) {
+                    reject(new Error('password is required'));
+                    return;
+                }
+                resolve(value);
+                return;
+            }
+            if (text === '\u007f' || text === '\b' || text === '\x08') {
+                if (password.length > 0) {
+                    password = password.slice(0, -1);
+                }
+                return;
+            }
+            password += text;
+        };
+        stdout.write(prompt);
+        stdin.resume();
+        stdin.setRawMode(true);
+        stdin.on('data', onData);
+    });
+}
 function getContext(command) {
     const global = command.optsWithGlobals();
     const configPath = getConfigPath(global);
@@ -132,8 +183,10 @@ program
     .addHelpText('after', [
     '',
     'Examples:',
+    '  quinn login --email <email>',
+    '  echo "<password>" | quinn login --email <email> --password-stdin',
     '  quinn config set --api-url http://localhost:8090 --api-token <token> --org-id <orgId>',
-    '  quinn organizations details',
+    '  quinn organizations current',
     '  quinn members find alice',
     '  quinn members get user-1,user-2,user@example.com',
 ].join('\n'))
@@ -202,34 +255,76 @@ configCmd.addHelpText('after', [
     '  quinn config get',
     '  quinn config set --api-url http://localhost:8090 --api-token <token> --org-id <orgId>',
 ].join('\n'));
+program
+    .command('login')
+    .description('login and save token (+orgId) into config (password input is hidden by default)')
+    .requiredOption('--email <email>')
+    .option('--password <password>', 'DEPRECATED: avoid plain-text password in command history/process list')
+    .option('--password-stdin', 'read password from stdin')
+    .option('--org-id <id>', 'override org id if login response does not include one')
+    .action(function (opts) {
+    return withHandler(async () => {
+        const { configPath, fileConfig, runtimeConfig } = getContext(this);
+        if (opts.password && opts.passwordStdin) {
+            throw new Error('cannot use --password and --password-stdin together');
+        }
+        let password = '';
+        if (opts.passwordStdin) {
+            password = readPasswordFromStdin();
+        }
+        else if (opts.password) {
+            process.stderr.write('Warning: --password is deprecated and insecure. Use interactive prompt or --password-stdin.\n');
+            password = opts.password;
+        }
+        else {
+            password = await promptPasswordHidden();
+        }
+        const auth = new quinn_sdk_1.QuinnAuth({
+            apiUrl: runtimeConfig.apiUrl,
+            configPath,
+        });
+        const login = await auth.login({
+            email: opts.email,
+            password,
+        });
+        const resolvedOrgId = opts.orgId || login.orgId || fileConfig.orgId;
+        if (!resolvedOrgId) {
+            throw new Error('orgId not found in login response, please pass --org-id');
+        }
+        const next = {
+            apiUrl: runtimeConfig.apiUrl || quinn_sdk_1.DEFAULT_QUINN_API_URL,
+            token: login.token,
+            orgId: resolvedOrgId,
+        };
+        writeConfig(configPath, next);
+        print({
+            ok: true,
+            configPath,
+            config: {
+                apiUrl: next.apiUrl,
+                token: maskToken(next.token),
+                orgId: next.orgId,
+            },
+        });
+    });
+});
 const orgCmd = program
     .command('organizations')
     .description('organization metadata and high-level stats');
 orgCmd
     .command('current')
-    .description('get current organization basic info (id, name)')
-    .action(function () {
-    return withHandler(async () => {
-        const { runtimeConfig } = getContext(this);
-        const quinn = createClient(runtimeConfig);
-        print(await quinn.organizations.get());
-    });
-});
-orgCmd
-    .command('details')
-    .description('get organization details with aggregate stats')
+    .description('get current organization details with aggregate stats')
     .action(function () {
     return withHandler(async () => {
         const { runtimeConfig } = getContext(this);
         const quinn = createClient(runtimeConfig);
-        print(await quinn.organizations.getDetails());
+        print(await quinn.organizations.current());
     });
 });
 orgCmd.addHelpText('after', [
     '',
     'Examples:',
     '  quinn organizations current',
-    '  quinn organizations details',
 ].join('\n'));
 const membersCmd = program.command('members').description('member operations');
 membersCmd

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@totoday/quinn-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "bin": {
     "quinn": "dist/index.js"
   },
   "dependencies": {
     "commander": "^13.1.0",
-    "@totoday/quinn-sdk": "0.1.0"
+    "@totoday/quinn-sdk": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",

package/src/index.ts

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
-import { Quinn, Privilege } from '@totoday/quinn-sdk';
+import { DEFAULT_QUINN_API_URL, Quinn, QuinnAuth, Privilege } from '@totoday/quinn-sdk';
 
 type QuinnCliConfig = {
   apiUrl?: string;
@@ -83,7 +83,7 @@ function writeConfig(configPath: string, config: QuinnCliConfig): void {
 
 function resolveRuntimeConfig(opts: GlobalOptions, fileConfig: QuinnCliConfig): QuinnCliConfig {
   return {
-    apiUrl: opts.apiUrl || process.env.QUINN_API_URL || fileConfig.apiUrl,
+    apiUrl: opts.apiUrl || process.env.QUINN_API_URL || fileConfig.apiUrl || DEFAULT_QUINN_API_URL,
     token: opts.apiToken || opts.token || process.env.QUINN_API_TOKEN || fileConfig.token,
     orgId: opts.orgId || process.env.QUINN_ORG_ID || fileConfig.orgId,
   };
@@ -91,9 +91,6 @@ function resolveRuntimeConfig(opts: GlobalOptions, fileConfig: QuinnCliConfig):
 
 function createClient(config: QuinnCliConfig): Quinn {
   const { apiUrl, token, orgId } = config;
-  if (!apiUrl) {
-    throw new Error('missing apiUrl: set --api-url or QUINN_API_URL or config');
-  }
   if (!token) {
     throw new Error('missing token: set --api-token/--token or QUINN_API_TOKEN or config');
   }
@@ -103,6 +100,69 @@ function createClient(config: QuinnCliConfig): Quinn {
   return new Quinn({ apiUrl, token, orgId });
 }
 
+function readPasswordFromStdin(): string {
+  const value = fs.readFileSync(0, 'utf8').trim();
+  if (!value) {
+    throw new Error('empty password from stdin');
+  }
+  return value;
+}
+
+async function promptPasswordHidden(prompt = 'Password: '): Promise<string> {
+  if (!process.stdin.isTTY) {
+    throw new Error('interactive password prompt requires TTY, use --password-stdin');
+  }
+  return await new Promise<string>((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let password = '';
+
+    const cleanup = () => {
+      stdin.off('data', onData);
+      if (stdin.isTTY) {
+        stdin.setRawMode(false);
+      }
+      stdin.pause();
+    };
+
+    const onData = (chunk: Buffer) => {
+      const text = chunk.toString('utf8');
+
+      if (text === '\u0003') {
+        cleanup();
+        reject(new Error('login cancelled'));
+        return;
+      }
+
+      if (text === '\r' || text === '\n') {
+        cleanup();
+        stdout.write('\n');
+        const value = password.trim();
+        if (!value) {
+          reject(new Error('password is required'));
+          return;
+        }
+        resolve(value);
+        return;
+      }
+
+      if (text === '\u007f' || text === '\b' || text === '\x08') {
+        if (password.length > 0) {
+          password = password.slice(0, -1);
+        }
+        return;
+      }
+
+      password += text;
+    };
+
+    stdout.write(prompt);
+    stdin.resume();
+    stdin.setRawMode(true);
+    stdin.on('data', onData);
+  });
+}
+
 function getContext(command: Command): {
   global: GlobalOptions;
   configPath: string;
@@ -165,8 +225,10 @@ program
     [
       '',
       'Examples:',
+      '  quinn login --email <email>',
+      '  echo "<password>" | quinn login --email <email> --password-stdin',
       '  quinn config set --api-url http://localhost:8090 --api-token <token> --org-id <orgId>',
-      '  quinn organizations details',
+      '  quinn organizations current',
       '  quinn members find alice',
       '  quinn members get user-1,user-2,user@example.com',
     ].join('\n')
@@ -243,28 +305,71 @@ configCmd.addHelpText(
   ].join('\n')
 );
 
-const orgCmd = program
-  .command('organizations')
-  .description('organization metadata and high-level stats');
-orgCmd
-  .command('current')
-  .description('get current organization basic info (id, name)')
-  .action(function () {
+program
+  .command('login')
+  .description('login and save token (+orgId) into config (password input is hidden by default)')
+  .requiredOption('--email <email>')
+  .option('--password <password>', 'DEPRECATED: avoid plain-text password in command history/process list')
+  .option('--password-stdin', 'read password from stdin')
+  .option('--org-id <id>', 'override org id if login response does not include one')
+  .action(function (opts: { email: string; password?: string; passwordStdin?: boolean; orgId?: string }) {
     return withHandler(async () => {
-      const { runtimeConfig } = getContext(this);
-      const quinn = createClient(runtimeConfig);
-      print(await quinn.organizations.get());
+      const { configPath, fileConfig, runtimeConfig } = getContext(this);
+      if (opts.password && opts.passwordStdin) {
+        throw new Error('cannot use --password and --password-stdin together');
+      }
+      let password = '';
+      if (opts.passwordStdin) {
+        password = readPasswordFromStdin();
+      } else if (opts.password) {
+        process.stderr.write(
+          'Warning: --password is deprecated and insecure. Use interactive prompt or --password-stdin.\n'
+        );
+        password = opts.password;
+      } else {
+        password = await promptPasswordHidden();
+      }
+      const auth = new QuinnAuth({
+        apiUrl: runtimeConfig.apiUrl,
+        configPath,
+      });
+      const login = await auth.login({
+        email: opts.email,
+        password,
+      });
+      const resolvedOrgId = opts.orgId || login.orgId || fileConfig.orgId;
+      if (!resolvedOrgId) {
+        throw new Error('orgId not found in login response, please pass --org-id');
+      }
+      const next: QuinnCliConfig = {
+        apiUrl: runtimeConfig.apiUrl || DEFAULT_QUINN_API_URL,
+        token: login.token,
+        orgId: resolvedOrgId,
+      };
+      writeConfig(configPath, next);
+      print({
+        ok: true,
+        configPath,
+        config: {
+          apiUrl: next.apiUrl,
+          token: maskToken(next.token),
+          orgId: next.orgId,
+        },
+      });
     });
   });
 
+const orgCmd = program
+  .command('organizations')
+  .description('organization metadata and high-level stats');
 orgCmd
-  .command('details')
-  .description('get organization details with aggregate stats')
+  .command('current')
+  .description('get current organization details with aggregate stats')
   .action(function () {
     return withHandler(async () => {
       const { runtimeConfig } = getContext(this);
       const quinn = createClient(runtimeConfig);
-      print(await quinn.organizations.getDetails());
+      print(await quinn.organizations.current());
     });
   });
 orgCmd.addHelpText(
@@ -273,7 +378,6 @@ orgCmd.addHelpText(
     '',
     'Examples:',
     '  quinn organizations current',
-    '  quinn organizations details',
   ].join('\n')
 );