@intflow/sentinelctl 0.1.0 → 0.3.0

package/README.md

@@ -1,91 +1,115 @@
 # sentinelctl
 
-Sentinel Fleet Console(`https://monitor.intflow.dev`)을 터미널에서 쓰는 명령행 도구입니다. 로그 검색, 장비 조회, 메타데이터 변경, 사용자 권한 관리를 지원합니다. 웹 콘솔과 같은 Intflow(Google Workspace) 로그인과 같은 역할 검사를 사용합니다.
+Command-line client for Sentinel Fleet Console (`https://monitor.intflow.dev`): search device logs, inspect device status and metrics, edit device metadata and manage console roles. It uses the same Intflow (Google Workspace) login and the same role checks as the web console.
 
-- Node.js 20 이상, 외부 의존성 없음
-- 권한: `viewer`는 조회만, `editor`는 메타데이터 변경까지, `admin`은 원본 로그 필드·가져오기/내보내기·사용자 관리까지 가능합니다. 권한은 서버가 판정하며 CLI는 서버 결과를 그대로 보여 줍니다.
+- Node.js 20+, no dependencies.
+- Roles: `viewer` reads, `editor` also edits metadata, `admin` also sees raw log fields, imports/exports metadata and manages users. The server enforces roles; the CLI also checks your role before sending a request that would be refused.
 
-## 설치
+## Install
 
 ```bash
-npm install -g @intflow/sentinelctl
+npm install -g @intflow/sentinelctl    # or the short alias: npm install -g sentinelctl
 ```
 
-## 로그인
+`sentinelctl` is an alias package that runs `@intflow/sentinelctl`. Install only one of them.
+
+## Log in
 
 ```bash
 sentinelctl login
 ```
 
-1. 터미널에 승인 주소와 확인 코드(예: `BCDF-GHJK`)가 나타나고 브라우저가 열립니다. 원격 셸이면 `--no-browser`를 주고 주소를 직접 엽니다.
-2. 브라우저에서 Intflow 계정으로 로그인한 뒤, 화면의 확인 코드가 터미널과 같은지 보고 **승인**합니다.
-3. CLI가 토큰(기본 30일)을 받아 자격 증명 파일에 0600 권한으로 저장합니다.
+1. The terminal prints an approval URL and a confirmation code (e.g. `BCDF-GHJK`) and opens the browser. Over SSH, add `--no-browser` and open the URL yourself.
+2. Sign in with your intflow.ai account, check that the browser shows the same code, and approve.
+3. The CLI stores a 30-day token in an owner-only (0600) credentials file.
 
 ```bash
 sentinelctl whoami
-sentinelctl sessions list          # 내 웹 세션·CLI 토큰
-sentinelctl logout                 # 서버에서 토큰 폐기 + 로컬 삭제
+sentinelctl sessions list          # your web sessions and CLI tokens
+sentinelctl logout                 # revoke on the server and delete local credentials
+```
+
+Credentials live in `~/.config/sentinelctl/credentials.json` (Linux/macOS) or `%APPDATA%\sentinelctl\credentials.json` (Windows); override with `SENTINELCTL_CONFIG`. The server is taken from `--server`, then `SENTINEL_URL`, then the saved profile, then the default. Automation can pass `SENTINEL_TOKEN` instead of a credentials file.
+
+## Getting help
+
+```bash
+sentinelctl --help                    # overview
+sentinelctl logs search --help        # one command: options, examples, required role, output fields
+sentinelctl help agents               # guide for AI agents and scripts
+sentinelctl commands --json           # machine-readable catalog of every command
 ```
 
-자격 증명 파일 위치는 Linux/macOS `~/.config/sentinelctl/credentials.json`, Windows `%APPDATA%\sentinelctl\credentials.json`이며 `SENTINELCTL_CONFIG`로 바꿀 수 있습니다. 서버는 `--server`, `SENTINEL_URL`, 저장된 프로필, 기본값 순서로 정합니다. 자동화에서는 파일 대신 `SENTINEL_TOKEN` 환경 변수를 쓸 수 있습니다.
+Mistyped commands and options get a suggestion (`Did you mean --range?`), and every error comes with a hint for the next step.
 
-## 로그
+## Logs
 
 ```bash
-sentinelctl logs search timeout -r 1h                      # 최근 1시간 "timeout" 검색
-sentinelctl logs search -a agent-123 -l error -r 24h --all # 장비·수준 필터, 모든 페이지
+sentinelctl logs search timeout -r 1h
+sentinelctl logs search -a <agent-id> -l error -r 24h --all
 sentinelctl logs search -s sshd.service --from 2026-09-30T00:00:00Z --to 2026-09-30T06:00:00Z
-sentinelctl logs search -l error -f                        # 새 오류 로그 따라가기(Ctrl+C 종료)
-sentinelctl logs search -q boom -o ndjson | jq .message    # 기계 처리용 출력
-sentinelctl logs context -a agent-123 -s app.service -t 2026-09-30T01:02:03.456Z
+sentinelctl logs search -l error -f                        # follow new errors (Ctrl+C to stop)
+sentinelctl logs search -q boom -o ndjson | jq .message
+sentinelctl logs context -a <agent-id> -s app.service -t 2026-09-30T01:02:03.456Z
 sentinelctl logs histogram -l error -r 24h
+sentinelctl logs stats -l error -r 1h --by source          # exact counts, one server-side query
+sentinelctl logs stats -l error -r 24h --by agent --top 10
+sentinelctl logs stats -a <agent-id> -r 7d --by message    # message patterns, numbers collapsed to <N>
 sentinelctl logs sources -r 24h
 ```
 
-검색 범위는 `15m`·`1h`·`6h`·`24h`·`7d` 또는 최대 30일의 `--from`/`--to`입니다. 한 페이지는 `-n 50|100|250`건이고 서버 상한 때문에 최대 10,000건까지 이어서 가져옵니다. `--fields`(원본 필드)는 관리자 전용이며 감사 로그에 남습니다.
+Windows are `15m`, `1h`, `6h`, `24h`, `7d`, or `--from`/`--to` up to 30 days. One page holds 50, 100 or 250 logs; when you ask for several pages (`--pages N`, at most 40, or `--all`) the CLI fetches 250 per request and stops at 10,000 logs. To answer "how many" or "which devices the most", use `logs stats`: it aggregates on the server and returns exact counts instead of downloading logs. `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds.
 
-## 장비와 메타데이터
+Each user can run 2 log queries at a time, web and CLI combined; a third concurrent query gets 429 and GET requests retry automatically.
+
+## Devices and metadata
 
 ```bash
 sentinelctl devices list --status offline
-sentinelctl devices list 서울 --site seoul --all -o json
-sentinelctl devices show agent-123 -r 24h
+sentinelctl devices list --focus attention --all -o json
+sentinelctl devices show <agent-id> -r 24h -o json
 sentinelctl devices lookup edge-01
+sentinelctl devices overview <agent-id> -r 7d
 sentinelctl health
 
-sentinelctl metadata get agent-123
-sentinelctl metadata history agent-123
-sentinelctl metadata set agent-123 --display-name "엣지 1" --maintainer 홍길동 --label site=seoul   # editor 이상
-sentinelctl metadata set agent-123 --lifecycle maintenance --maintenance-until 2026-10-01T09:00:00+09:00
-sentinelctl metadata rollback agent-123 --to 3
-sentinelctl metadata export --file backup.json                                                     # admin
-sentinelctl metadata import backup.json --dry-run                                                  # admin
+sentinelctl metadata get <agent-id>
+sentinelctl metadata history <agent-id>
+sentinelctl metadata set <agent-id> --display-name "Edge 1" --label site=seoul --dry-run      # editor
+sentinelctl metadata set <agent-id> --lifecycle maintenance --maintenance-until 2026-10-01T09:00:00+09:00
+sentinelctl metadata bulk id1 id2 id3 --role camera --dry-run                                # editor, up to 100
+sentinelctl metadata rollback <agent-id> --to 3
+sentinelctl metadata export --file backup.json                                               # admin
+sentinelctl metadata import backup.json --dry-run                                            # admin
 ```
 
-`metadata set`은 현재 변경 버전을 읽은 뒤 그 버전으로 수정합니다. 그 사이 다른 사람이 바꿨으면 서버가 `409`로 거부하므로 다시 실행하면 됩니다.
+`metadata set` and `metadata bulk` read the latest revision and apply on top of it. If someone saves in between, the server answers 409; run the command again.
 
-## 관리자
+## Admin
 
 ```bash
 sentinelctl admin users
-sentinelctl admin grant kim@intflow.ai --role editor   # 첫 로그인 전에도 지정 가능
-sentinelctl admin reset kim@intflow.ai                 # 콘솔 지정 권한 삭제(기본 viewer)
-sentinelctl admin disable kim@intflow.ai               # 접근 중지 + 모든 세션·CLI 토큰 즉시 종료
+sentinelctl admin grant kim@intflow.ai --role editor   # works before the first login
+sentinelctl admin reset kim@intflow.ai                 # back to the default viewer
+sentinelctl admin disable kim@intflow.ai               # block access and end all sessions now
 sentinelctl admin sessions --kind cli
-sentinelctl admin revoke <세션 ID>
+sentinelctl admin revoke <session-id>
+sentinelctl admin audit --cleanup
+sentinelctl admin operations -r 7d
 ```
 
-그 밖의 API는 `sentinelctl api /api/operations?range=7d`처럼 직접 호출할 수 있습니다.
+Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
+
+## Output and exit codes
 
-## 출력과 종료 코드
+- `-o table` (default), `-o json` (`--json`), `-o ndjson`. Data goes to stdout; summaries, hints and errors go to stderr (`--quiet` drops summaries and hints). With json/ndjson, an error is one stderr line: `{"error":{"status","code","message","hint","exitCode"}}`.
+- Exit codes: `0` success, `1` server or network error, `2` usage error, `3` not logged in or insufficient role.
+- Server error messages are Korean because the web console shares them; hints are English.
 
-- `-o table`(기본), `-o json`(`--json`), `-o ndjson`
-- 종료 코드: `0` 성공, `1` 서버·네트워크 오류, `2` 사용법 오류, `3` 인증 필요 또는 권한 부족
+## Publishing
 
-## 배포
+Publish the scoped package first, then the alias with the same version (`cli/unscoped/package.json` depends on it). Accounts with two-factor authentication need an interactive terminal for the browser approval.
 
 ```bash
-cd cli
-npm test
-npm publish --access public
+cd cli && npm test && npm publish --access public
+cd unscoped && npm publish --access public
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@intflow/sentinelctl",
-  "version": "0.1.0",
-  "description": "Sentinel Fleet Console 명령행 도구: 로그 검색, 장비 조회, 메타데이터·권한 관리",
+  "version": "0.3.0",
+  "description": "Sentinel Fleet Console CLI: search device logs, inspect status and metrics, edit metadata and manage roles",
   "type": "module",
   "bin": {
     "sentinelctl": "bin/sentinelctl.mjs"
@@ -24,5 +24,12 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "keywords": [
+    "sentinel",
+    "intflow",
+    "logs",
+    "monitoring",
+    "cli"
+  ]
 }

package/src/args.mjs

@@ -1,23 +1,50 @@
 export class UsageError extends Error {
-  constructor(message) {
+  constructor(message, { hint = null } = {}) {
     super(message);
     this.name = 'UsageError';
+    this.hint = hint;
   }
 }
 
-// 옵션 정의: { name: { alias, type: 'string'|'boolean'|'integer', multiple } }
-// "--name value", "--name=value", "-a value", "--flag", "--no-flag"를 지원한다.
+function editDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= left.length; i += 1) {
+    let diagonal = previous[0];
+    previous[0] = i;
+    for (let j = 1; j <= right.length; j += 1) {
+      const saved = previous[j];
+      previous[j] = Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+      diagonal = saved;
+    }
+  }
+  return previous[right.length];
+}
+
+export function closest(value, candidates) {
+  const input = String(value ?? '').toLowerCase();
+  let best = null;
+  for (const candidate of candidates) {
+    const distance = candidate.startsWith(input) && input.length >= 2 ? 0 : editDistance(input, candidate.toLowerCase());
+    if (!best || distance < best.distance) best = { candidate, distance };
+  }
+  return best && best.distance <= Math.max(1, Math.floor(best.candidate.length / 2)) ? best.candidate : null;
+}
+
 export function parseArguments(argv, definitions) {
   const options = {};
   const positionals = [];
   const aliases = new Map(Object.entries(definitions).filter(([, spec]) => spec.alias).map(([name, spec]) => [spec.alias, name]));
+  const unknown = (flag) => {
+    const suggestion = closest(flag.replace(/^-+/, ''), Object.keys(definitions));
+    return new UsageError(`Unknown option: ${flag}`, { hint: suggestion ? `Did you mean --${suggestion}?` : null });
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === '--') {
       positionals.push(...argv.slice(index + 1));
       break;
     }
-    if (!argument.startsWith('-') || argument === '-') {
+    if (!argument.startsWith('-') || argument === '-' || /^-\d/.test(argument)) {
       positionals.push(argument);
       continue;
     }
@@ -34,27 +61,31 @@ export function parseArguments(argv, definitions) {
       }
     } else {
       name = aliases.get(argument.slice(1));
-      if (!name) throw new UsageError(`알 수 없는 옵션입니다: ${argument}`);
+      if (!name) throw unknown(argument);
     }
     const spec = definitions[name];
-    if (!spec) throw new UsageError(`알 수 없는 옵션입니다: --${name}`);
+    if (!spec) throw unknown(`--${name}`);
     if (spec.type === 'boolean') {
-      if (value !== undefined) throw new UsageError(`--${name}에는 값을 줄 수 없습니다.`);
+      if (value !== undefined) throw new UsageError(`--${name} does not take a value.`);
       options[name] = true;
       continue;
     }
     if (value === undefined) {
       value = argv[index + 1];
-      if (value === undefined) throw new UsageError(`--${name}에 값이 필요합니다.`);
+      if (value === undefined) {
+        throw new UsageError(`--${name} requires a value.`, { hint: spec.choices ? `Allowed values: ${spec.choices.join(', ')}` : null });
+      }
       index += 1;
     }
     let parsed = value;
     if (spec.type === 'integer') {
       parsed = Number(value);
-      if (!Number.isInteger(parsed)) throw new UsageError(`--${name}은 정수여야 합니다.`);
+      if (!Number.isInteger(parsed)) throw new UsageError(`--${name} must be an integer: ${value}`);
     }
     if (spec.choices && !spec.choices.includes(parsed)) {
-      throw new UsageError(`--${name}은 ${spec.choices.join(', ')} 중 하나여야 합니다.`);
+      const suggestion = closest(String(parsed), spec.choices.map(String));
+      throw new UsageError(`--${name} must be one of ${spec.choices.join(', ')}: ${value}`,
+        { hint: suggestion ? `Did you mean --${name} ${suggestion}?` : null });
     }
     if (spec.multiple) (options[name] ??= []).push(parsed);
     else options[name] = parsed;
@@ -67,6 +98,6 @@ export function parseArguments(argv, definitions) {
 
 export function keyValue(value, label) {
   const separator = String(value).indexOf('=');
-  if (separator < 1) throw new UsageError(`${label}은 key=value 형식이어야 합니다: ${value}`);
+  if (separator < 1) throw new UsageError(`${label} must be key=value: ${value}`);
   return [value.slice(0, separator), value.slice(separator + 1)];
 }

package/src/client.mjs

@@ -21,7 +21,7 @@ export function createClient({ server, token = null, fetch: fetchImplementation
     }
     const headers = { accept: 'application/json', 'user-agent': userAgent };
     if (auth) {
-      if (!token) throw new ApiError('로그인이 필요합니다. sentinelctl login을 먼저 실행하세요.', { status: 401, code: 'not_logged_in' });
+      if (!token) throw new ApiError('Not logged in.', { status: 401, code: 'not_logged_in' });
       headers.authorization = `Bearer ${token}`;
     }
     if (body !== undefined) headers['content-type'] = 'application/json';
@@ -33,8 +33,8 @@ export function createClient({ server, token = null, fetch: fetchImplementation
           redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
         });
       } catch (error) {
-        const reason = error?.name === 'TimeoutError' ? '응답 시간이 초과되었습니다' : '연결하지 못했습니다';
-        throw new ApiError(`${url.origin}에 ${reason}.`, { code: 'network_error' });
+        const reason = error?.name === 'TimeoutError' ? 'timed out' : 'could not connect';
+        throw new ApiError(`Request to ${url.origin} ${reason}.`, { code: 'network_error' });
       }
       const text = await response.text();
       let payload = {};
@@ -44,16 +44,12 @@ export function createClient({ server, token = null, fetch: fetchImplementation
         payload = { error: text.slice(0, 200) };
       }
       const retryAfterSeconds = Number(response.headers.get('retry-after')) || null;
-      // 429는 서버가 알려 준 시간만큼 기다렸다가 GET만 다시 시도한다. 변경 요청은 중복 실행을 막기 위해 재시도하지 않는다.
       if (response.status === 429 && method === 'GET' && attempt < maxRetries) {
         await sleep(Math.min(retryAfterSeconds ?? 1, 30) * 1_000);
         continue;
       }
       if (response.ok || allowStatuses.includes(response.status)) return { status: response.status, body: payload };
-      let message = payload.error || `HTTP ${response.status}`;
-      if (response.status === 401 && auth) message = `${message} (sentinelctl login으로 다시 로그인하세요)`;
-      if (retryAfterSeconds) message += ` · ${retryAfterSeconds}초 뒤 다시 시도해 주세요.`;
-      throw new ApiError(message, { status: response.status, code: payload.code, retryAfterSeconds, body: payload });
+      throw new ApiError(payload.error || `HTTP ${response.status}`, { status: response.status, code: payload.code, retryAfterSeconds, body: payload });
     }
   }
   return {