@kesflow/kf 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# `@kesflow/kf`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI for KesFlow staff agents. Requires Node.js 22 or newer and a personal token from **Nội bộ → Kết nối của tôi**.
+
+```sh
+npm install -g @kesflow/kf
+```
+
+Đăng nhập: bảo người dùng mở một terminal riêng và gõ `kf login`, rồi dán token vào ô ẩn (ô chat Claude Code với `!` không có terminal nên không dùng được). Agent không tự chạy `kf login`, không bao giờ hỏi hay nhận token trong chat. `kf logout` removes the local file; revoke the token on the ops page.
+
+Commands use the operation IDs from `GET /ops` exactly: `kf <op-id>`. Run `kf --help` for the live list, `kf schema <op-id>` for JSON Schema, or `kf <op-id> --help` for flags. The CLI keeps no persistent operations cache.
+
+```sh
+kf status
+kf ops
+kf lms-buoi --lop-ma THUCLI
+kf lms-doi-ten --tep-id UUID --ten 'Tên mới'
+kf lms-ghi-recap --json '{"buoi_id":"UUID","recap_md":"# Buổi học","de_bai_md":null}'
+kf lms-dang-buoi --buoi-id UUID --gui-thu false --yes
+kf lms upload slide.html --buoi-id UUID
+```
+
+Use `--dry-run` to validate an operation without writing and `--pretty` for indented JSON. High-risk operations require `--yes`. Normal output is one JSON line on stdout; errors are one JSON line on stderr. Exit codes: 0 success, 2 usage, 3 authentication or permission, 4 business error, 5 server or network.
+
+Credentials are stored in `~/.config/kf/credentials.json` (directory mode 700, file mode 600). `KF_API_URL` is honoured by `kf login` and saved with the token. Changing it later requires another login. Plain HTTP is accepted only for localhost loopback tests.
+
+## Skill cho Claude Code
+
+Gói kèm skill `kf-cli` (hướng dẫn agent dùng `kf` đúng cách). Cài một lần:
+
+```
+mkdir -p ~/.claude/skills/kf-cli && cp "$(npm root -g)/@kesflow/kf/SKILL.md" ~/.claude/skills/kf-cli/SKILL.md
+```

package/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: kf-cli
+description: Thao tác nội bộ KesFlow qua CLI `kf` thay cho bấm màn ops — chốt buổi học LMS (gắn record từ Drive, tải slide, đổi tên/gỡ tệp, ghi recap/bài tập/chuẩn bị, đăng buổi), xem lớp và buổi mình phụ trách. Dùng khi nhân sự KesFlow nhờ "chốt buổi", "up slide/record lên LMS", "ghi recap", "đăng buổi", "đổi tên record", "xem buổi lớp TA05" hoặc nhắc tới `kf`. Không dùng cho việc ngoài danh sách `kf --help` (tiền, ghi danh, gửi mail tự do chưa có trong CLI).
+---
+
+# kf — CLI nội bộ KesFlow cho agent
+
+`kf` gọi Agent API của KesFlow **nhân danh người đang đăng nhập**; quyền do DB quyết định theo vai của người đó, y như màn ops.
+
+## Đăng nhập — người dùng tự làm, KHÔNG qua chat
+- Chưa đăng nhập (`kf status` thoát mã 3, `NOT_LOGGED_IN`) hoặc token hết hạn/thu hồi (401): bảo người dùng
+  1. vào ops → **Kết nối của tôi** → **Tạo token** (đặt tên máy);
+  2. **mở một terminal riêng** (ô chat Claude Code với `!` không có terminal nên không dùng được), gõ `kf login`, dán token vào ô ẩn.
+- **Không bao giờ** hỏi, nhận, đọc, in hay ghi token. Không tự chạy `kf login`. Không đọc `~/.config/kf/credentials.json`.
+
+## Cách dùng
+- Danh sách thao tác (lấy trực tiếp từ server, luôn đúng): `kf --help`. Tham số một thao tác: `kf <op> --help`, `kf schema <op>`.
+- Gọi: `kf <op> --<tham-so> <giá trị>` hoặc `kf <op> --json '{...}'`. Kết quả: một dòng JSON (`--pretty` để đọc).
+- Không chắc thì chạy thử trước: thêm `--dry-run` (chỉ kiểm, không ghi gì).
+- Tải tệp từ máy lên buổi học: `kf lms upload <tệp> --buoi-id <id> [--loai slide_pdf|slide_html|record|video_xem_truoc] [--ten ...]`.
+- Tìm `buoi-id`: `kf status` (lớp tôi phụ trách) → `kf lms-buoi --lop-ma <MÃ LỚP>`.
+
+## Thao tác rủi ro cao (`[high]`, cần `--yes`)
+- Ví dụ `lms-dang-buoi --gui-thu true` gửi thư cho **cả lớp thật**.
+- Chỉ thêm `--yes` **sau khi người dùng đồng ý rõ trong chat** với đúng nội dung: buổi nào, lớp nào, có gửi thư không. Không tự suy ra ý định gửi thư.
+- `--yes` không thay người duyệt; người dùng nên để Claude Code hỏi quyền trước lệnh `kf … --yes`.
+
+## Đọc kết quả
+| Mã thoát | Nghĩa | Làm gì |
+|---|---|---|
+| 0 | OK | báo kết quả |
+| 2 | Sai cách dùng / thiếu `--yes` / cấu hình | sửa lệnh; cấu hình lỗi → nhắc đăng nhập lại ở terminal riêng |
+| 3 | 401 (token) / 403 `khong_vai` (không có vai với lớp/buổi đó) | 401 → nhắc đăng nhập lại; 403 → báo người dùng không có quyền, không thử đường khác |
+| 4 | Lỗi nghiệp vụ (`LMS_*`, vd `LMS_DA_CO_RECORD`) | đọc mã, báo người dùng |
+| 5 | Mạng/server; `AGENT_TAT` = Agent API đang tắt | báo người dùng, không thử lại liên tục |
+
+`lms-dang-buoi` có thể trả `da_dang:false, thieu:["record"]`: buổi chưa có record sẵn sàng nên chưa đăng — không phải lỗi.

package/dist/api.d.ts

@@ -0,0 +1,8 @@
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly code: string;
+    readonly http: number | null;
+    constructor(message: string, exitCode: number, code: string, http?: number | null);
+}
+export declare function httpExit(status: number): number;
+export declare function request(baseUrl: string, token: string, path: string, body?: Record<string, unknown>): Promise<unknown>;

package/dist/api.js

@@ -0,0 +1,50 @@
+export class CliError extends Error {
+    exitCode;
+    code;
+    http;
+    constructor(message, exitCode, code, http = null) {
+        super(message);
+        this.exitCode = exitCode;
+        this.code = code;
+        this.http = http;
+    }
+}
+export function httpExit(status) {
+    if (status === 401 || status === 403)
+        return 3;
+    if (status >= 400 && status < 500)
+        return 4;
+    return 5;
+}
+export async function request(baseUrl, token, path, body) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/${path}`, {
+            method: body === undefined ? 'GET' : 'POST',
+            headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+            redirect: 'error',
+        });
+    }
+    catch (error) {
+        const redirect = error instanceof TypeError && /redirect/i.test(String(error.cause ?? error.message));
+        throw new CliError(redirect ? 'Agent API trả chuyển hướng — bị chặn để giữ token' : 'Không kết nối được Agent API', 5, redirect ? 'REDIRECT' : 'NETWORK');
+    }
+    if (response.status === 401)
+        throw new CliError('token hết hạn/đã thu hồi — mở terminal riêng và gõ `kf login`', 3, 'HTTP_401', 401);
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch {
+        throw new CliError('Agent API trả dữ liệu không hợp lệ', 5, 'BAD_RESPONSE', response.status);
+    }
+    if (!response.ok) {
+        const obj = data && typeof data === 'object' ? data : {};
+        const candidate = typeof obj.ma === 'string' ? obj.ma : typeof obj.loai === 'string' ? obj.loai : '';
+        const code = /^[A-Za-z][A-Za-z0-9_]{0,79}$/.test(candidate) ? candidate : `HTTP_${response.status}`;
+        throw new CliError(code, httpExit(response.status), code, response.status);
+    }
+    return data;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function hiddenToken(): Promise<string>;

package/dist/cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { stdin, stderr, stdout } from 'node:process';
+import { openSync } from 'node:fs';
+import { emitKeypressEvents } from 'node:readline';
+import { ReadStream } from 'node:tty';
+import { parseArgs } from 'node:util';
+import { CliError, request } from './api.js';
+import { apiUrl, deleteCredentials, readCredentials, saveCredentials } from './config.js';
+import { operationHelp, parseBody, parseOps } from './ops.js';
+import { upload } from './upload.js';
+import { QUICKSTART } from './kesflow.js';
+function print(value, pretty = false, token = '') {
+    const encoded = redact(JSON.stringify(value, null, pretty ? 2 : undefined), token);
+    stdout.write(`${encoded}\n`);
+}
+function redact(value, token = '') {
+    return value.replaceAll(token || '\u0000', '[REDACTED]').replace(/kf_pat_[0-9a-f]{64}/g, '[REDACTED]');
+}
+function labelFromMe(value) {
+    const envelope = value && typeof value === 'object' ? value : {};
+    const data = envelope.du_lieu && typeof envelope.du_lieu === 'object' ? envelope.du_lieu : envelope;
+    for (const key of ['email', 'ten', 'name'])
+        if (typeof data[key] === 'string')
+            return data[key];
+    return 'KesFlow staff';
+}
+export async function hiddenToken() {
+    let fd = null;
+    let input;
+    if (stdin.isTTY && typeof stdin.setRawMode === 'function')
+        input = stdin;
+    else {
+        try {
+            fd = openSync('/dev/tty', 'r+');
+            input = new ReadStream(fd);
+        }
+        catch {
+            throw new CliError('kf login cần một terminal thật: mở terminal riêng và gõ `kf login` (ô chat Claude Code với ! không có terminal)', 2, 'TTY_REQUIRED');
+        }
+    }
+    let token = '';
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            const onKeypress = (text, key) => {
+                if (key.name === 'return' || key.name === 'enter') {
+                    cleanup();
+                    stderr.write('\n');
+                    resolve(token);
+                    return;
+                }
+                if ((key.ctrl && ['c', 'd'].includes(key.name || ''))) {
+                    cleanup();
+                    stderr.write('\n');
+                    reject(new CliError('Đã huỷ đăng nhập', 2, 'CANCELLED'));
+                    return;
+                }
+                if (key.name === 'backspace') {
+                    token = token.slice(0, -1);
+                    return;
+                }
+                if (!key.ctrl && !key.meta && text && !text.includes('\x1b') && !key.sequence?.includes('\x1b'))
+                    token += text;
+            };
+            const cleanup = () => input.off('keypress', onKeypress);
+            input.on('keypress', onKeypress);
+            stderr.write('Dán token (ẩn), Enter để tiếp tục: ');
+        });
+    }
+    finally {
+        input.setRawMode(false);
+        input.pause();
+        if (fd !== null)
+            input.destroy(); // ReadStream owns fd and closes it
+    }
+}
+function validToken(token) {
+    if (!/^kf_pat_[0-9a-f]{64}$/.test(token))
+        throw new CliError('Token không hợp lệ; mở terminal riêng và gõ `kf login` lại', 2, 'TOKEN');
+    return token;
+}
+function requireCredentials(value) {
+    if (!value)
+        throw new CliError('Chưa đăng nhập; mở terminal riêng và gõ kf login', 3, 'NOT_LOGGED_IN');
+    validToken(value.token);
+    return value;
+}
+function uploadArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, options: {
+                'buoi-id': { type: 'string' }, loai: { type: 'string' }, ten: { type: 'string' },
+                'dry-run': { type: 'boolean' }, pretty: { type: 'boolean' },
+            }, strict: true, allowPositionals: true });
+    }
+    catch (error) {
+        throw new CliError(error.message, 2, 'USAGE');
+    }
+    const file = parsed.positionals[0];
+    const values = parsed.values;
+    if (!file || parsed.positionals.length !== 1 || !values['buoi-id'])
+        throw new CliError('Dùng: kf lms upload <file> --buoi-id <uuid>', 2, 'USAGE');
+    return { file, buoiId: values['buoi-id'], loai: values.loai,
+        ten: values.ten, dryRun: values['dry-run'], pretty: Boolean(values.pretty) };
+}
+async function liveOps(baseUrl, token) {
+    return parseOps(await request(baseUrl, token, 'ops'));
+}
+async function run(args) {
+    const command = args.shift();
+    if (command === 'login') {
+        if (args.length)
+            throw new CliError('kf login không nhận token qua tham số hoặc cờ', 2, 'USAGE');
+        const token = validToken((await hiddenToken()).trim());
+        const baseUrl = apiUrl();
+        const me = await request(baseUrl, token, 'me', {});
+        const label = labelFromMe(me);
+        await saveCredentials({ token, baseUrl, label });
+        print({ loai: 'ok', label, base_url: baseUrl }, false, token);
+        return;
+    }
+    if (command === 'logout') {
+        if (args.length)
+            throw new CliError('kf logout không nhận tham số', 2, 'USAGE');
+        await deleteCredentials();
+        print({ loai: 'ok', message: 'Đã xoá token trên máy. Thu hồi token trên trang Kết nối của tôi trong ops.' });
+        return;
+    }
+    const isHelp = !command || command === '--help' || command === '-h' || command === 'help';
+    let saved = null;
+    let baseUrl = '';
+    try {
+        saved = await readCredentials();
+        baseUrl = apiUrl(saved || undefined);
+    }
+    catch (error) {
+        // --help must still print the quickstart when the config is broken or KF_API_URL mismatches.
+        if (!isHelp)
+            throw error;
+        stdout.write(QUICKSTART);
+        stdout.write(`\n${error instanceof Error ? error.message : 'Cấu hình kf lỗi'}\n`);
+        return;
+    }
+    if (command === 'status') {
+        if (args.length > 1 || (args.length === 1 && args[0] !== '--pretty'))
+            throw new CliError('kf status chỉ nhận --pretty', 2, 'USAGE');
+        const creds = requireCredentials(saved);
+        print(await request(baseUrl, creds.token, 'me', {}), args.includes('--pretty'), creds.token);
+        return;
+    }
+    if (isHelp) {
+        stdout.write(QUICKSTART);
+        if (saved) {
+            if (!/^kf_pat_[0-9a-f]{64}$/.test(saved.token)) {
+                stdout.write('\nToken không hợp lệ — mở terminal riêng và gõ `kf login`\n');
+                return;
+            }
+            let ops;
+            try {
+                ops = await liveOps(baseUrl, saved.token);
+            }
+            catch (error) {
+                if (error instanceof CliError && error.http === 401) {
+                    stdout.write('\ntoken hết hạn/đã thu hồi — mở terminal riêng và gõ `kf login`\n');
+                    return;
+                }
+                throw error;
+            }
+            stdout.write('\nLive ops / Thao tác hiện có:\n');
+            for (const group of ['general', ...new Set(ops.filter((op) => op.id.includes('-')).map((op) => op.id.split('-')[0]))]) {
+                const items = ops.filter((op) => (op.id.includes('-') ? op.id.split('-')[0] : 'general') === group);
+                if (items.length)
+                    stdout.write(`  ${group}:\n${items.map((op) => `    ${op.id} [${op.risk}] ${op.tom_tat}`).join('\n')}\n`);
+            }
+        }
+        else
+            stdout.write('\nRun `kf login` in a separate terminal to list live operations.\n');
+        return;
+    }
+    const creds = requireCredentials(saved);
+    if (command === 'ops') {
+        if (args.length > 1 || (args.length === 1 && args[0] !== '--pretty'))
+            throw new CliError('kf ops chỉ nhận --pretty', 2, 'USAGE');
+        print(await liveOps(baseUrl, creds.token), args.includes('--pretty'), creds.token);
+        return;
+    }
+    if (command === 'lms' && args[0] === 'upload') {
+        args.shift();
+        const opts = uploadArgs(args);
+        print(await upload(baseUrl, creds.token, opts), opts.pretty, creds.token);
+        return;
+    }
+    const ops = await liveOps(baseUrl, creds.token);
+    const id = command === 'schema' ? args.shift() : command;
+    const op = ops.find((item) => item.id === id);
+    if (!op)
+        throw new CliError(`Không có thao tác: ${id || command}`, 2, 'USAGE');
+    if (command === 'schema') {
+        if (args.length > 1 || (args.length === 1 && args[0] !== '--pretty'))
+            throw new CliError('schema chỉ nhận --pretty', 2, 'USAGE');
+        print(op.input, args.includes('--pretty'), creds.token);
+        return;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        stdout.write(`${operationHelp(op)}\n`);
+        return;
+    }
+    const { body, pretty } = parseBody(op, args);
+    print(await request(baseUrl, creds.token, op.id, body), pretty, creds.token);
+}
+// Agents often pipe output (`kf --help | head`); a closed pipe is not an error.
+stdout.on('error', (error) => { if (error.code === 'EPIPE')
+    process.exit(0); throw error; });
+run(process.argv.slice(2)).catch((error) => {
+    const e = error instanceof CliError ? error : new CliError('Lỗi hệ thống', 5, 'INTERNAL');
+    stderr.write(`${redact(JSON.stringify({ error: e.message, code: e.code, http: e.http }))}\n`);
+    process.exitCode = e.exitCode;
+});

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export type Credentials = {
+    token: string;
+    baseUrl: string;
+    label: string;
+};
+export declare const credentialsPath: () => string;
+export declare function apiUrl(saved?: Credentials): string;
+export declare function readCredentials(): Promise<Credentials | null>;
+export declare function saveCredentials(value: Credentials): Promise<void>;
+export declare function deleteCredentials(): Promise<void>;

package/dist/config.js

@@ -0,0 +1,62 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { CLI_NAME, DEFAULT_API_URL } from './kesflow.js';
+import { CliError } from './api.js';
+export const credentialsPath = () => join(homedir(), '.config', CLI_NAME, 'credentials.json');
+export function apiUrl(saved) {
+    const normalize = (value) => {
+        let url;
+        try {
+            url = new URL(value);
+        }
+        catch {
+            throw new CliError('KF_API_URL không hợp lệ', 2, 'CONFIG');
+        }
+        const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) || url.username || url.password || url.search || url.hash)
+            throw new CliError('KF_API_URL không hợp lệ; chỉ localhost được dùng HTTP', 2, 'CONFIG');
+        return url.toString().replace(/\/$/, '');
+    };
+    const savedUrl = saved ? normalize(saved.baseUrl) : null;
+    const override = process.env.KF_API_URL;
+    const value = normalize(override === undefined ? savedUrl || DEFAULT_API_URL : override);
+    if (savedUrl && override !== undefined && value !== savedUrl)
+        throw new CliError('KF_API_URL khác nơi đã đăng nhập — mở terminal riêng và gõ `kf login` lại', 2, 'CONFIG');
+    return value;
+}
+export async function readCredentials() {
+    try {
+        const raw = JSON.parse(await readFile(credentialsPath(), 'utf8'));
+        if (!raw || typeof raw !== 'object')
+            throw new Error('credentials.json không hợp lệ');
+        const value = raw;
+        if (typeof value.token !== 'string' || typeof value.baseUrl !== 'string' || typeof value.label !== 'string') {
+            throw new Error('credentials.json không hợp lệ');
+        }
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new CliError('credentials.json không hợp lệ; mở terminal riêng và gõ `kf login` lại', 2, 'CONFIG');
+    }
+}
+export async function saveCredentials(value) {
+    const path = credentialsPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await chmod(dirname(path), 0o700);
+    const temp = `${path}.${process.pid}.tmp`;
+    try {
+        await writeFile(temp, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+        await chmod(temp, 0o600);
+        await rename(temp, path);
+        await chmod(path, 0o600);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+export async function deleteCredentials() {
+    await rm(credentialsPath(), { force: true });
+}

package/dist/kesflow.d.ts

@@ -0,0 +1,4 @@
+/** KesFlow-specific defaults and agent help. The API/schema interpreter is in api.ts and ops.ts. */
+export declare const CLI_NAME = "kf";
+export declare const DEFAULT_API_URL = "https://kesflow.vn/api/agent/v1";
+export declare const QUICKSTART = "AGENT QUICKSTART / B\u1EAET \u0110\u1EA6U CHO AGENT\n  \u0110\u0103ng nh\u1EADp: b\u1EA3o ng\u01B0\u1EDDi d\u00F9ng m\u1EDF m\u1ED9t terminal ri\u00EAng v\u00E0 g\u00F5 `kf login`, r\u1ED3i d\u00E1n token v\u00E0o \u00F4 \u1EA9n (\u00F4 chat Claude Code v\u1EDBi `!` kh\u00F4ng c\u00F3 terminal n\u00EAn kh\u00F4ng d\u00F9ng \u0111\u01B0\u1EE3c). Agent kh\u00F4ng t\u1EF1 ch\u1EA1y `kf login`, kh\u00F4ng bao gi\u1EDD h\u1ECFi hay nh\u1EADn token trong chat.\n  High-risk ops (--yes): ch\u1EC9 th\u00EAm --yes sau khi ng\u01B0\u1EDDi d\u00F9ng \u0111\u1ED3ng \u00FD r\u00F5 trong chat v\u1EDBi \u0111\u00FAng n\u1ED9i dung s\u1EBD l\u00E0m.\n  kf ops                  List live operations / Li\u1EC7t k\u00EA thao t\u00E1c\n  kf schema lms-doi-ten   Inspect input JSON Schema\n  kf lms-doi-ten --tep-id <uuid> --ten 'T\u00EAn m\u1EDBi'\n  kf lms-dang-buoi --buoi-id <uuid> --gui-thu false --yes\n  kf lms upload slide.html --buoi-id <uuid>\n\nCommands use registry IDs exactly: kf <op-id> [flags]. Output: one JSON line.\nExit: 0 OK, 2 usage, 3 auth/permission, 4 business, 5 network/server.\n";

package/dist/kesflow.js

@@ -0,0 +1,15 @@
+/** KesFlow-specific defaults and agent help. The API/schema interpreter is in api.ts and ops.ts. */
+export const CLI_NAME = 'kf';
+export const DEFAULT_API_URL = 'https://kesflow.vn/api/agent/v1';
+export const QUICKSTART = `AGENT QUICKSTART / BẮT ĐẦU CHO AGENT
+  Đăng nhập: bảo người dùng mở một terminal riêng và gõ \`kf login\`, rồi dán token vào ô ẩn (ô chat Claude Code với \`!\` không có terminal nên không dùng được). Agent không tự chạy \`kf login\`, không bao giờ hỏi hay nhận token trong chat.
+  High-risk ops (--yes): chỉ thêm --yes sau khi người dùng đồng ý rõ trong chat với đúng nội dung sẽ làm.
+  kf ops                  List live operations / Liệt kê thao tác
+  kf schema lms-doi-ten   Inspect input JSON Schema
+  kf lms-doi-ten --tep-id <uuid> --ten 'Tên mới'
+  kf lms-dang-buoi --buoi-id <uuid> --gui-thu false --yes
+  kf lms upload slide.html --buoi-id <uuid>
+
+Commands use registry IDs exactly: kf <op-id> [flags]. Output: one JSON line.
+Exit: 0 OK, 2 usage, 3 auth/permission, 4 business, 5 network/server.
+`;

package/dist/ops.d.ts

@@ -0,0 +1,24 @@
+export type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    description?: string;
+    enum?: unknown[];
+    anyOf?: JsonSchema[];
+    default?: unknown;
+};
+export type Operation = {
+    id: string;
+    tom_tat: string;
+    risk: 'read' | 'write' | 'high';
+    roles: string[];
+    input: JsonSchema;
+};
+export declare function parseOps(value: unknown): Operation[];
+export declare function parseBody(op: Operation, args: string[]): {
+    body: Record<string, unknown>;
+    pretty: boolean;
+    dryRun: boolean;
+    yes: boolean;
+};
+export declare function operationHelp(op: Operation): string;

package/dist/ops.js

@@ -0,0 +1,101 @@
+import { CliError } from './api.js';
+import { parseArgs } from 'node:util';
+export function parseOps(value) {
+    if (!Array.isArray(value) || !value.every((op) => op && typeof op.id === 'string' && /^[a-z][a-z0-9-]*$/.test(op.id)
+        && typeof op.tom_tat === 'string' && ['read', 'write', 'high'].includes(op.risk)
+        && op.input && typeof op.input === 'object'))
+        throw new CliError('/ops không hợp lệ', 5, 'BAD_OPS');
+    return value;
+}
+function scalar(schema, raw) {
+    const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+    const choices = schema.anyOf || [schema];
+    const kind = types.find((type) => type !== 'null') || choices.flatMap((s) => Array.isArray(s.type) ? s.type : s.type ? [s.type] : []).find((type) => type !== 'null');
+    if (raw === 'null' && (types.includes('null') || choices.some((s) => s.type === 'null')))
+        return null;
+    if (kind === 'boolean') {
+        if (raw !== 'true' && raw !== 'false')
+            throw new CliError('Giá trị boolean phải là true hoặc false', 2, 'USAGE');
+        return raw === 'true';
+    }
+    if (kind === 'number' || kind === 'integer') {
+        const value = Number(raw);
+        if (!Number.isFinite(value) || (kind === 'integer' && !Number.isInteger(value)))
+            throw new CliError('Giá trị số không hợp lệ', 2, 'USAGE');
+        return value;
+    }
+    if (kind !== 'string')
+        throw new CliError('Thuộc tính phức tạp: dùng --json', 2, 'USAGE');
+    if (schema.enum && !schema.enum.includes(raw))
+        throw new CliError(`Giá trị phải là ${schema.enum.join('|')}`, 2, 'USAGE');
+    return raw;
+}
+export function parseBody(op, args) {
+    let body = {};
+    let pretty = false, dryRun = false, yes = false;
+    const props = op.input.properties || {};
+    const options = {
+        pretty: { type: 'boolean' }, 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' }, json: { type: 'string' },
+    };
+    for (const name of Object.keys(props))
+        options[name.replaceAll('_', '-')] = { type: 'string' };
+    let tokens;
+    try {
+        tokens = parseArgs({ args, options, strict: true, allowPositionals: false, tokens: true }).tokens;
+    }
+    catch (error) {
+        throw new CliError(error.message, 2, 'USAGE');
+    }
+    for (const token of tokens || []) {
+        if (token.kind !== 'option')
+            continue;
+        const flag = token.name;
+        if (flag === 'pretty') {
+            pretty = true;
+            continue;
+        }
+        if (flag === 'dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (flag === 'yes') {
+            yes = true;
+            continue;
+        }
+        if (flag === 'json') {
+            const raw = token.value;
+            if (!raw)
+                throw new CliError('--json cần object', 2, 'USAGE');
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object')
+                    throw new Error();
+                body = { ...body, ...parsed };
+            }
+            catch {
+                throw new CliError('--json cần object JSON hợp lệ', 2, 'USAGE');
+            }
+            continue;
+        }
+        const key = flag.replaceAll('-', '_');
+        const raw = token.value;
+        if (raw === undefined)
+            throw new CliError(`Thiếu giá trị: --${flag}`, 2, 'USAGE');
+        body[key] = scalar(props[key], raw);
+    }
+    if (op.risk === 'high' && !yes)
+        throw new CliError('Thao tác rủi ro cao cần --yes', 2, 'USAGE');
+    if (yes && op.risk === 'high')
+        body.xac_nhan = true;
+    if (dryRun)
+        body.dry_run = true;
+    return { body, pretty, dryRun, yes };
+}
+export function operationHelp(op) {
+    const props = Object.entries(op.input.properties || {}).map(([name, schema]) => {
+        const required = op.input.required?.includes(name) ? ' (required)' : '';
+        const type = schema.type || schema.anyOf?.map((s) => s.type).filter(Boolean).join('|') || 'JSON';
+        return `  --${name.replaceAll('_', '-')} <${type}>${required}`;
+    }).join('\n');
+    return `${op.id} [${op.risk}] — ${op.tom_tat}\nRoles: ${op.roles.join(', ')}\n${props}\n  --json '<object>'  --dry-run  --pretty${op.risk === 'high' ? '  --yes (required)' : ''}`;
+}

package/dist/upload.d.ts

@@ -0,0 +1,9 @@
+type UploadOptions = {
+    file: string;
+    buoiId: string;
+    loai?: string;
+    ten?: string;
+    dryRun?: boolean;
+};
+export declare function upload(baseUrl: string, token: string, opts: UploadOptions): Promise<unknown>;
+export {};

package/dist/upload.js

@@ -0,0 +1,85 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { Transform } from 'node:stream';
+import { CliError, request } from './api.js';
+const mimeByExtension = {
+    '.pdf': { mime: 'application/pdf', loai: 'slide_pdf' },
+    '.html': { mime: 'text/html', loai: 'slide_html' },
+    '.htm': { mime: 'text/html', loai: 'slide_html' },
+    '.mp4': { mime: 'video/mp4', loai: 'record' },
+    '.webm': { mime: 'video/webm', loai: 'record' },
+    '.mov': { mime: 'video/quicktime', loai: 'record' },
+};
+async function step(name, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw new CliError(`${name}: ${error.message}`, error.exitCode, error.code, error.http);
+        throw new CliError(`${name}: lỗi hệ thống`, 5, 'INTERNAL');
+    }
+}
+function dataOf(value, step) {
+    const envelope = value && typeof value === 'object' ? value : {};
+    const data = envelope.du_lieu;
+    if (!data || typeof data !== 'object')
+        throw new CliError(`${step}: thiếu du_lieu`, 5, 'BAD_RESPONSE');
+    return data;
+}
+export async function upload(baseUrl, token, opts) {
+    const fileType = mimeByExtension[extname(opts.file).toLowerCase()];
+    if (!fileType)
+        throw new CliError('Đuôi tệp không hỗ trợ (pdf, html, mp4, webm, mov)', 2, 'USAGE');
+    const loai = opts.loai || fileType.loai;
+    const allowed = fileType.mime.startsWith('video/') ? ['record', 'video_xem_truoc'] : [fileType.loai];
+    if (!allowed.includes(loai))
+        throw new CliError('--loai không khớp kiểu tệp', 2, 'USAGE');
+    let size;
+    try {
+        const info = await stat(opts.file);
+        if (!info.isFile())
+            throw new Error();
+        size = info.size;
+    }
+    catch {
+        throw new CliError('Không đọc được tệp', 2, 'FILE');
+    }
+    const createResponse = await step('tep-tao', () => request(baseUrl, token, 'lms-tep-tao', {
+        buoi_id: opts.buoiId, loai, ten: opts.ten || basename(opts.file), kich_thuoc: size, mime: fileType.mime,
+        ...(opts.dryRun ? { dry_run: true } : {}),
+    }));
+    if (opts.dryRun)
+        return createResponse;
+    const created = dataOf(createResponse, 'tep-tao');
+    if (typeof created.id !== 'string' || typeof created.put_url !== 'string')
+        throw new CliError('tep-tao: thiếu id/put_url', 5, 'BAD_RESPONSE');
+    let sent = 0;
+    const meter = new Transform({
+        transform(chunk, _encoding, callback) {
+            sent += chunk.length;
+            process.stderr.write(`\r${sent}/${size} bytes`);
+            callback(null, chunk);
+        },
+    });
+    try {
+        const response = await fetch(created.put_url, {
+            method: 'PUT',
+            headers: { 'Content-Type': fileType.mime, 'Content-Length': String(size) },
+            body: createReadStream(opts.file).pipe(meter),
+            duplex: 'half',
+            signal: AbortSignal.timeout(120_000),
+            redirect: 'error',
+        });
+        process.stderr.write('\n');
+        if (!response.ok)
+            throw new CliError(`PUT thất bại (${response.status})`, 5, 'UPLOAD_FAILED', response.status);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('PUT thất bại', 5, 'UPLOAD_FAILED');
+    }
+    return step('tep-xac-nhan', () => request(baseUrl, token, 'lms-tep-xac-nhan', { buoi_id: opts.buoiId, tep_id: created.id }));
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@kesflow/kf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "KesFlow agent CLI",
+  "type": "module",
+  "bin": {
+    "kf": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.2",
+    "typescript": "5.7.2"
+  },
+  "license": "UNLICENSED"
+}