@odyssey365/cli 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/config.js ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * 자격증명 저장소 — 프로필(계정) 여러 개를 한 파일에 둔다.
3
+ *
4
+ * MCP 커넥터는 연결 하나에 계정 하나라 개인 계정과 운영(admin) 계정을 오갈 수 없었다.
5
+ * CLI 는 호출마다 프로필을 고르게 해 이 문제를 푼다(`odyssey -p admin list_todos`).
6
+ *
7
+ * 위치: $ODYSSEY_CONFIG_DIR 또는 ~/.odyssey/cli/credentials.json (디렉터리 0700 · 파일 0600).
8
+ * 토큰은 평문이다 — gh·gcloud·firebase-tools 의 파일 저장 폴백과 같은 수준이다.
9
+ * 쓰기는 임시 파일 + rename 으로 원자적으로 한다(동시 실행 두 개가 반쯤 쓴 파일을 읽지 않게).
10
+ */
11
+ import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
12
+ import { homedir } from 'node:os';
13
+ import { dirname, join } from 'node:path';
14
+ export const DEFAULT_SERVER = 'https://mcp-odyssey30-60.odyssey365.app';
15
+ export const DEFAULT_PROFILE = 'default';
16
+ /** 프로필 이름 규칙 — 파일 키·셸 인자로 안전한 범위만. */
17
+ export const PROFILE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
18
+ export function configDir() {
19
+ const fromEnv = process.env.ODYSSEY_CONFIG_DIR;
20
+ if (fromEnv && fromEnv.trim())
21
+ return fromEnv;
22
+ return join(homedir(), '.odyssey', 'cli');
23
+ }
24
+ export function credentialsPath() {
25
+ return join(configDir(), 'credentials.json');
26
+ }
27
+ /** 끝 슬래시를 떼어 서버 URL 을 한 모양으로 맞춘다(캐시 키·비교용). */
28
+ export function normalizeServer(url) {
29
+ return url.trim().replace(/\/+$/, '');
30
+ }
31
+ function emptyFile() {
32
+ return { version: 1, profiles: {} };
33
+ }
34
+ export function loadCredentials() {
35
+ let raw;
36
+ try {
37
+ raw = readFileSync(credentialsPath(), 'utf-8');
38
+ }
39
+ catch {
40
+ return emptyFile();
41
+ }
42
+ try {
43
+ const parsed = JSON.parse(raw);
44
+ return {
45
+ version: 1,
46
+ defaultProfile: parsed.defaultProfile,
47
+ profiles: parsed.profiles ?? {},
48
+ };
49
+ }
50
+ catch {
51
+ throw new Error(`자격증명 파일을 읽을 수 없습니다(JSON 손상): ${credentialsPath()}\n` +
52
+ '파일을 지우고 `odyssey login` 으로 다시 로그인하세요.');
53
+ }
54
+ }
55
+ export function saveCredentials(file) {
56
+ writePrivateFile(credentialsPath(), JSON.stringify(file, null, 2) + '\n');
57
+ }
58
+ /** 0600 파일을 원자적으로 쓴다. Windows 에서 chmod 는 효과가 없다(무시). */
59
+ export function writePrivateFile(path, content) {
60
+ const dir = dirname(path);
61
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
62
+ const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
63
+ writeFileSync(tmp, content, { mode: 0o600 });
64
+ try {
65
+ chmodSync(tmp, 0o600);
66
+ }
67
+ catch {
68
+ // 권한 모델이 다른 파일시스템 — 무시
69
+ }
70
+ renameWithRetry(tmp, path);
71
+ }
72
+ /**
73
+ * Windows 는 백신·색인기·다른 odyssey 실행이 대상 파일을 잠깐 쥐고 있으면 rename 이 EPERM/EBUSY/EACCES 로
74
+ * 실패한다(교체 자체는 지원). 게임 기록기처럼 백그라운드에서 여럿이 부를 때 흔하다 — 짧게 몇 번 다시 해 본다.
75
+ */
76
+ function renameWithRetry(from, to) {
77
+ const transient = new Set(['EPERM', 'EBUSY', 'EACCES']);
78
+ for (let attempt = 0;; attempt++) {
79
+ try {
80
+ renameSync(from, to);
81
+ return;
82
+ }
83
+ catch (e) {
84
+ const code = e.code ?? '';
85
+ if (!transient.has(code) || attempt >= 9) {
86
+ try {
87
+ unlinkSync(from);
88
+ }
89
+ catch {
90
+ // 임시 파일 정리 실패는 무시
91
+ }
92
+ throw e;
93
+ }
94
+ // 동기 대기 50ms·100ms… (최대 ~2초) — 이 CLI 는 한 번 실행에 한 번 쓰므로 블로킹이 문제되지 않는다
95
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
96
+ }
97
+ }
98
+ }
99
+ /** 읽고 → 고치고 → 쓴다. 고치는 함수가 반환한 값을 그대로 돌려준다. */
100
+ export function updateCredentials(mutate) {
101
+ const file = loadCredentials();
102
+ const result = mutate(file);
103
+ saveCredentials(file);
104
+ return result;
105
+ }
106
+ export function assertProfileName(name) {
107
+ if (!PROFILE_NAME_RE.test(name)) {
108
+ throw new UsageError(`프로필 이름 "${name}" 은 쓸 수 없습니다 — 영문·숫자·_·- 로 32자 이하(첫 글자는 영문·숫자).`);
109
+ }
110
+ }
111
+ /** 사용법 오류(종료 코드 2). */
112
+ export class UsageError extends Error {
113
+ constructor(message) {
114
+ super(message);
115
+ this.name = 'UsageError';
116
+ }
117
+ }
118
+ /** 로그인이 필요하거나 자격증명이 죽었다(종료 코드 3). */
119
+ export class AuthRequiredError extends Error {
120
+ constructor(message) {
121
+ super(message);
122
+ this.name = 'AuthRequiredError';
123
+ }
124
+ }
package/dist/files.js ADDED
@@ -0,0 +1,58 @@
1
+ /**
2
+ * 로컬 파일 붙이기 — 도구 입력의 `image: { file: "경로" }` 를 보내기 전에 읽어 `{ data: base64, name }` 으로 바꾼다.
3
+ *
4
+ * 서버(MCP)는 바이트만 받는다 — 서버가 로컬 경로를 열 수는 없고, 임의 URL 을 받아 오는 길은 일부러 닫았다
5
+ * (snapshot-images.ts). 커넥터로 붙은 AI 는 파일을 못 읽지만 CLI 는 읽는다: 스냅샷 지면에 스크린샷을 올리는
6
+ * 운영 흐름이 이 한 단계로 열린다.
7
+ *
8
+ * - 바꾸는 자리는 **`image` 키의 객체**뿐이다(create_snapshot · update_snapshot · create_snapshot_draft 의 사진 칸).
9
+ * 이름이 다른 키의 `file` 은 손대지 않는다 — 다른 도구의 문자열을 파일로 오인해 읽어 보내면 안 된다.
10
+ * - 상대 경로는 `--input` 파일이 있는 폴더 기준(원고 JSON 옆에 그림을 두는 흐름), 없으면 지금 폴더.
11
+ *
12
+ * 이력: document/90-process/work-log/261011 MCP 스냅샷 AI 왕복 생성·수정 역할 어휘 통일 서식 표기.md
13
+ */
14
+ import { readFileSync, statSync } from 'node:fs';
15
+ import { basename, isAbsolute, resolve } from 'node:path';
16
+ import { UsageError } from './config.js';
17
+ /** 서버 상한(한 장 10MB)보다 먼저 막는다 — 큰 파일을 base64 로 부풀려 보낸 뒤 거절받지 않게. */
18
+ export const MAX_INLINE_FILE_BYTES = 10 * 1024 * 1024;
19
+ /** 붙인 파일 수 — 호출부가 안내에 쓴다. */
20
+ export function inlineImageFiles(value, baseDir) {
21
+ let count = 0;
22
+ const visit = (node) => {
23
+ if (Array.isArray(node)) {
24
+ node.forEach(visit);
25
+ return;
26
+ }
27
+ if (!node || typeof node !== 'object')
28
+ return;
29
+ const obj = node;
30
+ for (const [key, child] of Object.entries(obj)) {
31
+ if (key === 'image' && child && typeof child === 'object' && !Array.isArray(child)) {
32
+ const img = child;
33
+ if (typeof img.file === 'string' && img.data === undefined) {
34
+ const path = isAbsolute(img.file) ? img.file : resolve(baseDir, img.file);
35
+ let size;
36
+ try {
37
+ size = statSync(path).size;
38
+ }
39
+ catch {
40
+ throw new UsageError(`image.file 을 찾지 못했습니다: ${path}`);
41
+ }
42
+ if (size > MAX_INLINE_FILE_BYTES) {
43
+ throw new UsageError(`image.file 이 ${(size / 1024 / 1024).toFixed(1)}MB 입니다 — 한 장은 10MB 까지입니다: ${path}`);
44
+ }
45
+ img.data = readFileSync(path).toString('base64');
46
+ if (img.name === undefined)
47
+ img.name = basename(path);
48
+ delete img.file;
49
+ count += 1;
50
+ continue;
51
+ }
52
+ }
53
+ visit(child);
54
+ }
55
+ };
56
+ visit(value);
57
+ return count;
58
+ }
package/dist/guide.js ADDED
@@ -0,0 +1,113 @@
1
+ /**
2
+ * AI 에이전트용 설명서 — `odyssey agent-guide`.
3
+ *
4
+ * 다른 AI(Claude Code·Codex·Gemini CLI·Cursor 등)가 이 CLI 를 처음 만나도 쓸 수 있게, 설명서를 CLI 자신이 낸다.
5
+ * 파일로 따로 두지 않는 이유: 계정(프로필)과 서버 사용 지침은 실행할 때마다 다를 수 있다 — 설명서가 그 순간의 사실을 말해야 한다.
6
+ *
7
+ * odyssey agent-guide 전문(사용법 + 로그인된 계정 + 서버 사용 지침 실시간)
8
+ * odyssey agent-guide --skill Claude Code·Codex 스킬 파일(SKILL.md) — "시작할 때 agent-guide 를 읽어라" 가리킴
9
+ * odyssey agent-guide --snippet AGENTS.md·CLAUDE.md·GEMINI.md 등에 붙일 짧은 절
10
+ *
11
+ * AGENTS.md(여러 코딩 에이전트가 함께 읽는 관례)는 **에이전트가 일하는 프로젝트 폴더에 두는 파일**이다 — 도구가
12
+ * 미리 실어 둘 수 없으니, 그 파일에 넣을 내용(--snippet)을 CLI 가 내고 그 내용이 "시작할 때 agent-guide 를 실행하라"고
13
+ * 가리킨다(`odyssey agent-guide --snippet >> AGENTS.md`).
14
+ *
15
+ * 서버 사용 지침(MCP instructions)은 MCP 커넥터라면 연결 때 받는 것인데, CLI 는 왕복을 줄이려 initialize 를
16
+ * 건너뛰어 받지 못했다 — 전문 모드가 initialize 를 한 번 보내 그대로 싣는다.
17
+ *
18
+ * 이력: document/90-process/work-log/261010 Odyssey CLI agent-guide 에이전트 설명서 서버 지침.md
19
+ */
20
+ const CORE_RULES = `- **사용자의 데이터다.** 쓰기는 사용자 앱 화면·알림에 그대로 나타난다. 요청 범위를 넘는 생성·수정을 하지 않는다.
21
+ - \`[쓰기·덮어씀]\` 도구와 \`delete_*\` 는 사용자가 그 변경을 분명히 원할 때만 부른다(삭제는 휴지통으로 가지만 그래도 먼저 확인).
22
+ - 없는 UID·도구·파라미터를 추측하지 않는다 — \`odyssey search\`·\`list_*\` 로 찾는다. 이름으로 찾을 땐 \`search\` 가 먼저다.
23
+ - 쓰기 뒤에는 \`get_*\`/\`list_*\` 로 다시 읽어 결과를 확인하고, 실제로 한 일만 보고한다.
24
+ - 로그인(\`odyssey login\`)은 브라우저 인증이 필요한 **사람의 일**이다. 종료 코드 3 이면 사용자에게 부탁하고, 비밀번호·토큰을 직접 다루지 않는다.`;
25
+ function profileSection(input) {
26
+ const lines = ['## 계정(프로필)', ''];
27
+ if (input.envToken) {
28
+ lines.push('환경변수 `ODYSSEY_TOKEN` 이 설정돼 있어 `-p` 를 주지 않은 호출은 그 토큰의 계정으로 간다.', '');
29
+ }
30
+ if (input.profiles.length === 0) {
31
+ lines.push('로그인된 프로필이 없다. 사용자에게 터미널에서 `odyssey login` 을 실행해 브라우저로 로그인해 달라고 부탁한다.', '(계정을 여럿 쓰려면 `odyssey login -p <이름>` 으로 이름을 붙인다.)');
32
+ }
33
+ else {
34
+ lines.push('| 프로필 | 계정 | |', '|---|---|---|');
35
+ for (const p of input.profiles) {
36
+ const who = p.email ?? (p.auth === 'apiKey' ? '(API 키 — 계정 정보 없음)' : '(알 수 없음)');
37
+ lines.push(`| \`${p.name}\` | ${who} | ${p.isDefault ? '기본' : `\`-p ${p.name}\``} |`);
38
+ }
39
+ lines.push('', '- `-p <프로필>` 을 주지 않으면 기본 프로필이다. 사용자가 계정을 말하지 않았으면 기본으로 한다.', '- 여러 계정을 다룰 때는 쓰기 전에 `odyssey whoami -p <프로필>` 로 의도한 계정인지 확인한다.');
40
+ }
41
+ return lines.join('\n');
42
+ }
43
+ function instructionsSection(input) {
44
+ const from = input.instructionsFrom ? ` — 프로필 \`${input.instructionsFrom}\` 로 받음` : '';
45
+ if (input.serverInstructions) {
46
+ return `## 서버 사용 지침 (실시간${from})\n\nOdyssey 서버가 모든 AI 클라이언트에 주는 지침이다. 아래 \`getGuide\` 같은 이름은 \`odyssey getGuide\` 로 부른다.\n\n${input.serverInstructions.trim()}`;
47
+ }
48
+ return `## 서버 사용 지침\n\n받지 못했다${input.serverInstructionsError ? ` (${input.serverInstructionsError})` : ''}. 로그인한 뒤 \`odyssey agent-guide\` 를 다시 실행하면 여기에 실린다.\n복잡한 생성·구성(보드 꾸리기 등) 전에는 \`odyssey getGuide\` 로 지침 목록을 보고, 맞는 것을 \`odyssey getGuide --guideIds <ID>\` 로 읽은 뒤 그 절차를 따른다.`;
49
+ }
50
+ /** 전문 — 사용법 + 계정 + 서버 지침. */
51
+ export function renderAgentGuide(input) {
52
+ return `# Odyssey CLI — AI 에이전트 설명서 (odyssey ${input.version})
53
+
54
+ 이 문서는 \`odyssey agent-guide\` 의 출력이다. 작업을 시작할 때 한 번 실행해 읽는다 — 계정·서버 지침은 그때그때 다를 수 있다.
55
+
56
+ ## 무엇인가
57
+
58
+ Odyssey(계획·기록·회고 앱) 사용자의 데이터 — 할일·메모·루틴·기록(측정값)·일정·타임라인·리포트·프로젝트 보드·댓글·스냅샷·컬렉션 — 를
59
+ 읽고 쓰는 CLI 다. 도구는 서버(${input.server})가 정의한다 — Odyssey MCP 서버와 같은 도구다.
60
+
61
+ ${profileSection(input)}
62
+
63
+ ## 작업 순서
64
+
65
+ 1. **찾기** — \`odyssey tools [검색어]\`: 도구 목록. \`[읽기]\`·\`[쓰기]\`·\`[쓰기·덮어씀]\` 표시.
66
+ 2. **확인** — \`odyssey describe <도구>\`: 설명 전문·파라미터. 설명에 적힌 선행 조건(먼저 부를 도구·읽을 지침)을 따른다.
67
+ 3. **실행** — \`odyssey <도구> --파라미터 값 …\`, 또는 JSON 을 표준입력으로 \`odyssey <도구> --input -\`.
68
+ 4. **확인** — 쓰기 뒤 다시 읽어 확인한다.
69
+
70
+ ## 파라미터 적는 법
71
+
72
+ - \`--key 값\` · \`--key=값\` · 불리언 \`--flag\` / \`--no-flag\` · 배열은 반복(\`--tags a --tags b\`) 또는 JSON
73
+ - 객체 안쪽은 점 경로(\`--deadline.endTime 2026-10-20T18:00:00+09:00\`) 또는 JSON(\`--checklist '[{"title":"a"}]'\`) · null 은 \`null\`
74
+ - 필수 파라미터가 하나뿐이면 위치 인자: \`odyssey get_todo <todoId>\`
75
+ - 여러 값·특수 문자가 섞이면 \`--input -\` 에 JSON 객체를 넣는 편이 안전하다(셸 따옴표 문제 없음)
76
+ - 시각은 오프셋을 붙인 ISO 8601(\`+09:00\` 또는 \`Z\`)
77
+ - 같은 일을 다시 보낼 수 있는 자동화면 \`dedupeKey\` 를 준다(\`create_timeline_event\`·\`add_record_trace\` — 같은 키 = 한 번만 기록)
78
+
79
+ ## 출력과 종료 코드
80
+
81
+ - stdout 은 결과 JSON(파이프면 한 줄), stderr 는 안내·오류. 이미지를 돌려주는 도구는 파일로 저장하고 \`{"images":[{"path":…}]}\` 를 준다.
82
+ - \`0\` 성공 · \`1\` 도구 오류(메시지를 읽고 고쳐 다시 — 틀린 파라미터면 서버가 맞는 이름을 알려 준다) · \`2\` 사용법 오류 ·
83
+ \`3\` 로그인 필요(사람의 일) · \`4\` 네트워크(잠시 뒤 재시도)
84
+ - \`-o text\` 는 서버가 만든 요약 텍스트, \`-o raw\` 는 MCP 결과 전체.
85
+
86
+ ## 지켜야 할 것
87
+
88
+ ${CORE_RULES}
89
+
90
+ ${instructionsSection(input)}
91
+ `;
92
+ }
93
+ /** AGENTS.md·CLAUDE.md·GEMINI.md·Cursor 규칙 등에 붙일 짧은 절 — 기계마다 다른 계정 정보는 싣지 않는다. */
94
+ export function renderSnippet() {
95
+ return `## Odyssey (\`odyssey\` CLI)
96
+
97
+ Odyssey(계획·기록·회고 앱)의 데이터 — 할일·메모·루틴·기록·일정·타임라인·프로젝트 보드·스냅샷 — 는 \`odyssey\` CLI 로 읽고 쓴다.
98
+
99
+ - **작업을 시작할 때 \`odyssey agent-guide\` 를 실행해 읽는다** — 사용법·로그인된 계정·최신 서버 지침이 나온다.
100
+ - 도구: \`odyssey tools\` → \`odyssey describe <도구>\` → \`odyssey <도구> --파라미터 값\`(또는 \`--input -\` 에 JSON). 결과는 JSON.
101
+ - 계정: \`-p <프로필>\`. 종료 코드 3 = 로그인 필요 → 사용자에게 \`odyssey login\` 을 부탁한다.
102
+ ${CORE_RULES}
103
+ `;
104
+ }
105
+ /** Claude Code·Codex 스킬 파일(SKILL.md). */
106
+ export function renderSkill() {
107
+ return `---
108
+ name: odyssey
109
+ description: Odyssey(계획·기록·회고 앱) 사용자 데이터 — 할일·메모·루틴·기록(측정값)·일정·타임라인·프로젝트 보드·댓글·스냅샷·컬렉션 — 를 \`odyssey\` CLI 로 읽고 쓴다. 사용자가 Odyssey 나 그 안의 할일·메모·기록·일정·타임라인·보드를 언급하거나 다뤄 달라고 할 때, 여러 Odyssey 계정(-p 프로필)을 오갈 때 사용.
110
+ ---
111
+
112
+ ${renderSnippet()}`;
113
+ }