@dinoxx/dinox-cli 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# Dinox CLI 使用说明（普通用户版）
+
+`dino` 是一个命令行工具，用来管理你的 Dinox 数据（笔记、标签、卡片盒等）。
+
+如果你不熟悉技术细节也没关系，按这份文档一步一步操作就能用。
+
+---
+
+## 1. 先看你要做什么
+
+常见需求：
+
+1. 登录账号：`dino auth login ...`
+2. 同步数据：`dino sync`
+3. 搜索笔记：`dino note search "关键词"`
+4. 新建笔记：`dino note create ...`
+5. 新建标签：`dino tag add ...`
+6. 新建卡片盒：`dino box add ...`
+7. 看当前版本：`dino info`
+
+---
+
+## 2. 安装前准备
+
+你需要先安装 Node.js（建议 LTS，且版本 >= 20）。
+
+检查是否已安装：
+
+```bash
+node -v
+npm -v
+```
+
+---
+
+## 3. 安装方法（macOS / Windows）
+
+## 3.1 macOS
+
+### 方式 A：普通用户推荐（全局安装）
+
+1. 安装 Node.js（若未安装）：
+
+```bash
+brew install node
+```
+
+2. 安装 CLI：
+
+```bash
+npm install -g @dinoxx/dinox-cli
+```
+
+3. 验证：
+
+```bash
+dino info
+```
+
+---
+
+## 3.2 Windows
+
+### 方式 A：普通用户推荐（全局安装）
+
+1. 安装 Node.js（若未安装）：
+
+```powershell
+winget install OpenJS.NodeJS.LTS
+```
+
+2. 安装 CLI（PowerShell 或 CMD）：
+
+```powershell
+npm install -g @dinoxx/dinox-cli
+```
+
+3. 验证：
+
+```powershell
+dino info
+```
+
+---
+
+## 4. 第一次使用（建议照抄）
+
+## 第 1 步：登录
+
+```bash
+dino auth login "Bearer <你的token>"
+```
+
+## 第 2 步：同步
+
+```bash
+dino sync
+```
+
+## 第 3 步：看状态（可选）
+
+```bash
+dino auth status
+```
+
+---
+
+## 5. 最常用命令
+
+## 5.1 笔记
+
+搜索笔记：
+
+```bash
+dino note search "AI"
+dino note search "AI" --days 7
+dino note search "AI" --from 2026-02-01 --to 2026-02-28
+```
+
+创建笔记：
+
+```bash
+dino note create \
+  --title "今天的记录" \
+  --content "# 标题\n\n正文内容"
+```
+
+按 ID 查看：
+
+```bash
+dino note get <note-id>
+dino note detail <note-id>
+```
+
+删除笔记（软删除）：
+
+```bash
+dino note delete <note-id>
+```
+
+## 5.2 标签
+
+列出标签：
+
+```bash
+dino tag list
+```
+
+新增标签（两种写法都可以）：
+
+```bash
+dino tag add "工作/项目A"
+dino tag add --name "工作/项目A" --emoji "🧠"
+```
+
+## 5.3 卡片盒
+
+列出卡片盒：
+
+```bash
+dino box list
+```
+
+新增卡片盒（两种写法都可以）：
+
+```bash
+dino box add "Inbox"
+dino box add --name "Inbox" --description "用于存放待整理的想法和资料"
+```
+
+`--description` 很有用：它能帮助 AI 更准确地把笔记分到正确卡片盒。
+
+## 5.4 Prompt
+
+```bash
+dino prompt list
+```
+
+## 5.5 配置
+
+查看全部配置：
+
+```bash
+dino config get
+```
+
+查看某一项：
+
+```bash
+dino config get sync.timeoutMs
+```
+
+设置某一项：
+
+```bash
+dino config set sync.timeoutMs 20000
+```
+
+---
+
+## 6. macOS 和 Windows 的使用差异
+
+## 6.1 路径位置不同
+
+配置文件：
+
+1. macOS: `~/Library/Application Support/dinox/config.json`
+2. Windows: `%APPDATA%\dinox\config.json`
+
+本地数据库：
+
+1. macOS: `~/Library/Application Support/dinox/powersync.sqlite`
+2. Windows: `%LOCALAPPDATA%\dinox\powersync.sqlite`
+
+## 6.2 多行命令写法不同
+
+macOS / Linux（bash/zsh）用 `\` 续行：
+
+```bash
+dino note create \
+  --title "标题" \
+  --content "正文"
+```
+
+Windows PowerShell 用反引号 `` ` `` 续行：
+
+```powershell
+dino note create `
+  --title "标题" `
+  --content "正文"
+```
+
+## 6.3 `@file` 参数在 Windows 建议加引号
+
+比如从文件读取正文：
+
+```bash
+dino note create --title "测试" --content @./note.md
+```
+
+在 PowerShell 建议写成：
+
+```powershell
+dino note create --title "测试" --content "@.\note.md"
+```
+
+这样更稳，不容易被 shell 误解析。
+
+---
+
+## 7. 常见问题
+
+## Q1：报错 `Missing persisted userId. Run dino auth login first.`
+
+你还没有完成登录。执行：
+
+```bash
+dino auth login "Bearer <token>"
+```
+
+## Q2：创建笔记时报 `Unknown tags` 或 `Unknown zettel box names`
+
+说明你填的标签/卡片盒不存在，先创建再重试：
+
+```bash
+dino tag add "你的标签"
+dino box add "你的卡片盒"
+```
+
+## Q3：我设置了 `powersync.endpoint` 但没生效
+
+这两个配置是固定的，不允许修改：
+
+1. `powersync.endpoint = https://powersync.dinoai.fun`
+2. `powersync.uploadBaseUrl = https://dinoai.chatgo.pro`
+
+---
+
+## 8. 查看帮助
+
+随时可以看帮助：
+
+```bash
+dino --help
+dino <命令> --help
+dino <命令> <子命令> --help
+```
+
+例如：
+
+```bash
+dino note --help
+dino note create --help
+```

package/dist/auth/userInfo.d.ts

@@ -0,0 +1,14 @@
+import type { DinoxConfig, ResolvedDinoxConfig } from '../config/types.js';
+export type AuthIdentity = {
+    userId: string;
+    username: string | null;
+    email: string | null;
+    syncedAt: string;
+};
+export declare function fetchUserInfoWithAuthorization(input: {
+    authorization: string;
+    config: ResolvedDinoxConfig;
+    signal?: AbortSignal;
+}): Promise<AuthIdentity>;
+export declare function refreshAndPersistAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;
+export declare function resolveAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;

package/dist/auth/userInfo.js

@@ -0,0 +1,115 @@
+import { saveConfig } from '../config/store.js';
+import { DinoxError } from '../utils/errors.js';
+const AUTH_CODE_OK = '000000';
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeOptionalNullableString(value) {
+    const text = normalizeOptionalString(value);
+    return text ?? null;
+}
+function parseUserInfoResult(payload) {
+    if (!payload || typeof payload !== 'object') {
+        throw new DinoxError('User info response is not a JSON object');
+    }
+    const body = payload;
+    if ('code' in body) {
+        const code = String(body.code ?? '');
+        if (code && code !== AUTH_CODE_OK) {
+            throw new DinoxError(`User info request failed: ${String(body.msg ?? 'unknown error')}`);
+        }
+        const wrapped = body.data;
+        if (!wrapped || typeof wrapped !== 'object') {
+            throw new DinoxError('User info response does not include data');
+        }
+        return wrapped;
+    }
+    return body;
+}
+function parseIdentity(payload) {
+    const parsed = parseUserInfoResult(payload);
+    const userId = normalizeOptionalString(parsed.userId ?? parsed.user_id ?? parsed.id);
+    if (!userId) {
+        throw new DinoxError('User info response is missing id');
+    }
+    return {
+        userId,
+        username: normalizeOptionalNullableString(parsed.username),
+        email: normalizeOptionalNullableString(parsed.email),
+        syncedAt: new Date().toISOString(),
+    };
+}
+function resolveUserInfoEndpoint(config) {
+    const base = normalizeOptionalString(config.powersync.uploadBaseUrl) ?? normalizeOptionalString(config.powersync.tokenEndpoint);
+    if (!base) {
+        throw new DinoxError('Missing backend base URL for user info');
+    }
+    try {
+        const url = new URL('/auth/userInfo', base);
+        return url.toString();
+    }
+    catch (error) {
+        throw new DinoxError(`Invalid backend base URL: ${base}`, { cause: error });
+    }
+}
+export async function fetchUserInfoWithAuthorization(input) {
+    const authorization = normalizeOptionalString(input.authorization);
+    if (!authorization) {
+        throw new DinoxError('Authorization is required for user info');
+    }
+    const endpoint = resolveUserInfoEndpoint(input.config);
+    const response = await fetch(endpoint, {
+        method: 'GET',
+        headers: {
+            Authorization: authorization,
+            'Content-Type': 'application/json',
+        },
+        signal: input.signal,
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new DinoxError(`User info request failed (${response.status}): ${body || endpoint}`);
+    }
+    const payload = await response.json().catch(() => null);
+    return parseIdentity(payload);
+}
+export async function refreshAndPersistAuthIdentity(rawConfig, resolvedConfig) {
+    const authorization = normalizeOptionalString(resolvedConfig.auth.authorization);
+    if (!authorization) {
+        throw new DinoxError('Authorization is required to fetch user info');
+    }
+    const identity = await fetchUserInfoWithAuthorization({
+        authorization,
+        config: resolvedConfig,
+    });
+    const nextConfig = {
+        ...rawConfig,
+        auth: {
+            ...(rawConfig.auth ?? {}),
+            authorization: rawConfig.auth?.authorization ?? authorization,
+            userId: identity.userId,
+            username: identity.username,
+            email: identity.email,
+            userInfoSyncedAt: identity.syncedAt,
+        },
+    };
+    await saveConfig(nextConfig);
+    return identity;
+}
+export async function resolveAuthIdentity(rawConfig, resolvedConfig) {
+    const savedUserId = normalizeOptionalString(rawConfig.auth?.userId ?? resolvedConfig.auth.userId);
+    const syncedAt = normalizeOptionalString(rawConfig.auth?.userInfoSyncedAt ?? resolvedConfig.auth.userInfoSyncedAt);
+    if (savedUserId) {
+        return {
+            userId: savedUserId,
+            username: normalizeOptionalNullableString(rawConfig.auth?.username ?? resolvedConfig.auth.username),
+            email: normalizeOptionalNullableString(rawConfig.auth?.email ?? resolvedConfig.auth.email),
+            syncedAt: syncedAt ?? new Date().toISOString(),
+        };
+    }
+    throw new DinoxError('Missing persisted userId. Run `dino auth login` first.');
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createCli(): Command;

package/dist/cli.js

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import { registerAuthCommands } from './commands/auth/index.js';
+import { registerBoxesCommand } from './commands/boxes/index.js';
+import { registerConfigCommands } from './commands/config/index.js';
+import { registerInfoCommand } from './commands/info/index.js';
+import { registerNoteCommands } from './commands/notes/index.js';
+import { registerPromptCommands } from './commands/prompt/index.js';
+import { registerSyncCommand } from './commands/sync.js';
+import { registerTagsCommand } from './commands/tags/index.js';
+import { getPackageVersion } from './utils/version.js';
+export function createCli() {
+    const program = new Command();
+    program
+        .name('dino')
+        .description('Dinox CLI')
+        .version(getPackageVersion())
+        .showHelpAfterError();
+    program
+        .option('--json', 'output machine-readable YAML')
+        .option('--offline', 'skip connect/sync and only use local cache')
+        .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
+        .option('--verbose', 'enable verbose logging');
+    registerAuthCommands(program);
+    registerBoxesCommand(program);
+    registerConfigCommands(program);
+    registerInfoCommand(program);
+    registerSyncCommand(program);
+    registerPromptCommands(program);
+    registerTagsCommand(program);
+    registerNoteCommands(program);
+    return program;
+}

package/dist/cliTypes.d.ts

@@ -0,0 +1,6 @@
+export type GlobalOptions = {
+    json?: boolean;
+    offline?: boolean;
+    syncTimeout?: string;
+    verbose?: boolean;
+};

package/dist/cliTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/auth/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAuthCommands(program: Command): void;

package/dist/commands/auth/index.js

@@ -0,0 +1,193 @@
+import fs from 'node:fs/promises';
+import { loadConfig, saveConfig } from '../../config/store.js';
+import { resolveConfig } from '../../config/resolve.js';
+import { getPowerSyncDbPath } from '../../config/paths.js';
+import { redactAuthorization } from '../../utils/redact.js';
+import { DinoxError } from '../../utils/errors.js';
+import { printYaml } from '../../utils/output.js';
+import { refreshAndPersistAuthIdentity } from '../../auth/userInfo.js';
+import { connectPowerSync, getStatusSnapshot } from '../../powersync/runtime.js';
+import { fetchCredentialsWithAuthorization } from '../../powersync/connector.js';
+function parseSyncTimeoutMs(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new DinoxError('--sync-timeout must be a positive integer');
+    }
+    return Math.trunc(parsed);
+}
+export function registerAuthCommands(program) {
+    const auth = program
+        .command('auth')
+        .description('Authentication and PowerSync connectivity commands');
+    auth
+        .command('login')
+        .description('Save authorization token and verify PowerSync connectivity')
+        .argument('<authorization>', 'full Authorization header value (e.g. "Bearer <token>")')
+        .option('--no-verify', 'skip credential exchange and initial sync')
+        .action(async (authorization, options, command) => {
+        const auth = authorization?.trim();
+        if (!auth) {
+            throw new DinoxError('Authorization token is required');
+        }
+        const config = await loadConfig();
+        config.auth = { ...(config.auth ?? {}), authorization: auth };
+        await saveConfig(config);
+        const resolved = resolveConfig(config);
+        const globals = command.optsWithGlobals?.() ?? {};
+        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? resolved.sync.timeoutMs;
+        const jsonOutput = Boolean(globals.json);
+        if (!options.verify) {
+            const result = {
+                ok: true,
+                verified: false,
+                authorization: redactAuthorization(auth),
+            };
+            if (jsonOutput) {
+                printYaml(result);
+            }
+            else {
+                console.log('Login saved (verification skipped).');
+            }
+            return;
+        }
+        // 1) Token exchange sanity check.
+        await fetchCredentialsWithAuthorization({
+            authorization: auth,
+            endpoint: resolved.powersync.endpoint,
+            credentialsUrl: resolved.powersync.tokenEndpoint,
+        });
+        // 1.5) Fetch and persist user identity.
+        const identity = await refreshAndPersistAuthIdentity(config, resolved);
+        // 2) Connect + initial sync.
+        const { db, dbPath, stale } = await connectPowerSync({
+            config: resolved,
+            offline: false,
+            timeoutMs,
+        });
+        try {
+            const status = getStatusSnapshot(db);
+            const result = {
+                ok: true,
+                verified: true,
+                endpoint: resolved.powersync.endpoint,
+                dbPath,
+                stale,
+                lastSyncedAt: status.lastSyncedAt,
+                userId: identity.userId,
+            };
+            if (jsonOutput) {
+                printYaml(result);
+            }
+            else {
+                console.log('Login verified.');
+                console.log(`- endpoint: ${result.endpoint}`);
+                console.log(`- db: ${result.dbPath}`);
+                console.log(`- userId: ${result.userId}`);
+                if (result.lastSyncedAt) {
+                    console.log(`- lastSyncedAt: ${result.lastSyncedAt}`);
+                }
+                if (stale) {
+                    console.log('- warning: initial sync timed out; local cache may be stale');
+                }
+            }
+        }
+        finally {
+            await db.close().catch(() => undefined);
+        }
+    });
+    auth
+        .command('logout')
+        .description('Clear saved authorization token')
+        .option('--clear-local-db', 'delete the local PowerSync SQLite database')
+        .action(async (options) => {
+        const config = await loadConfig();
+        if (config.auth) {
+            config.auth.authorization = undefined;
+        }
+        await saveConfig(config);
+        if (options.clearLocalDb) {
+            const dbPath = getPowerSyncDbPath();
+            await fs.rm(dbPath, { force: true }).catch(() => undefined);
+        }
+    });
+    auth
+        .command('status')
+        .description('Show current login and sync status')
+        .action(async (_options, command) => {
+        const config = await loadConfig();
+        const resolved = resolveConfig(config);
+        const globals = command.optsWithGlobals?.() ?? {};
+        const offline = Boolean(globals.offline);
+        const jsonOutput = Boolean(globals.json);
+        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? resolved.sync.timeoutMs;
+        const dbPath = getPowerSyncDbPath();
+        const base = {
+            loggedIn: Boolean(resolved.auth.authorization),
+            authorization: redactAuthorization(resolved.auth.authorization),
+            userId: resolved.auth.userId ?? null,
+            username: resolved.auth.username ?? null,
+            email: resolved.auth.email ?? null,
+            powersync: {
+                endpoint: resolved.powersync.endpoint ?? null,
+                tokenEndpoint: resolved.powersync.tokenEndpoint ?? null,
+                uploadBaseUrl: resolved.powersync.uploadBaseUrl ?? null,
+                uploadV4Path: resolved.powersync.uploadV4Path,
+                uploadV2Path: resolved.powersync.uploadV2Path,
+            },
+            dbPath,
+        };
+        if (offline || !resolved.auth.authorization || !resolved.powersync.endpoint || !resolved.powersync.tokenEndpoint) {
+            const payload = { ...base, offline: true };
+            if (jsonOutput) {
+                printYaml(payload);
+            }
+            else {
+                console.log(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
+                if (payload.userId) {
+                    console.log(`userId: ${payload.userId}`);
+                }
+                console.log(`db: ${payload.dbPath}`);
+                console.log(`powersync.endpoint: ${payload.powersync.endpoint ?? '(unset)'}`);
+                console.log(`powersync.tokenEndpoint: ${payload.powersync.tokenEndpoint ?? '(unset)'}`);
+                console.log(`powersync.uploadBaseUrl: ${payload.powersync.uploadBaseUrl ?? '(unset)'}`);
+            }
+            return;
+        }
+        const { db, stale } = await connectPowerSync({
+            config: resolved,
+            offline: false,
+            timeoutMs,
+        });
+        try {
+            const status = getStatusSnapshot(db);
+            const payload = { ...base, offline: false, stale, status };
+            if (jsonOutput) {
+                printYaml(payload);
+            }
+            else {
+                console.log(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
+                if (payload.userId) {
+                    console.log(`userId: ${payload.userId}`);
+                }
+                console.log(`db: ${payload.dbPath}`);
+                console.log(`connected: ${payload.status.connected ? 'yes' : 'no'}`);
+                if (payload.status.lastSyncedAt) {
+                    console.log(`lastSyncedAt: ${payload.status.lastSyncedAt}`);
+                }
+                console.log(`dataFlow: downloading=${payload.status.dataFlowStatus.downloading} uploading=${payload.status.dataFlowStatus.uploading}`);
+                if (payload.stale) {
+                    console.log('warning: sync timed out; local cache may be stale');
+                }
+            }
+        }
+        finally {
+            await db.close().catch(() => undefined);
+        }
+    });
+    auth.action((_options, command) => {
+        command.outputHelp();
+    });
+}

package/dist/commands/boxes/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerBoxesCommand(program: Command): void;