@clarionstack/notesia 0.1.0 → 0.1.1

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Notesia CLI
2
2
 
3
- Local CLI for reading, updating, and bulk-importing notes in Notesia through the desktop app bridge.
3
+ Local CLI for reading, searching, tagging, and bulk-importing notes in Notesia through the desktop app bridge. Includes AI knowledge base queries, quick capture to Inbox, and deep link navigation.
4
4
 
5
5
  ## Requirements
6
6
 
@@ -23,10 +23,26 @@ npm install -g @clarionstack/notesia
23
23
  - `notesia store --title "<title>" [--tag <tag>]... [--folder-id <id>] [--content <text>]`
24
24
  - `notesia update --id <id>|... [--content <text>] [--title "<new title>"]`
25
25
  - `notesia append --id <id>|... [--content <text>]`
26
+ - `notesia prepend --id <id>|... [--content <text>]`
27
+ - `notesia move --id <id>|... --folder-id <id>` *(use 0 for root)*
26
28
  - `notesia trash --id <id>|...`
29
+ - `notesia capture --title "<title>" [--content <text>] [--tag <tag>]...`
30
+ - `notesia open --id <id>|--title "<title>"`
27
31
  - `notesia sync`
28
32
  - `notesia auth status [--format text|json]`
29
33
 
34
+ ### Search
35
+
36
+ - `notesia search <query> [--limit <n>] [--format text|json]`
37
+
38
+ Alias for `notesia kb search`. Full-text search across all notes by title and content.
39
+
40
+ ### Tags
41
+
42
+ - `notesia tags [--format text|json]` — List all tags with note counts
43
+ - `notesia tag add --id <id>|... --tag <tag> [--tag <tag>]...` — Add tags to a note
44
+ - `notesia tag remove --id <id>|... --tag <tag> [--tag <tag>]...` — Remove tags from a note
45
+
30
46
  ### Bulk Import
31
47
 
32
48
  ```
@@ -62,6 +78,13 @@ Notes exceeding 100,000 characters are automatically split into multiple parts.
62
78
 
63
79
  `kb ask` automatically reuses the same conversation in the same terminal session. Use `--conversation-id` only when you want to override/reset the session.
64
80
 
81
+ ### Deep Links
82
+
83
+ Open a note in the desktop app via URL scheme:
84
+
85
+ - `com.notesia.app://open?id=<id>` — Open by local ID
86
+ - `com.notesia.app://open?title=<title>` — Open by title
87
+
65
88
  ## Examples
66
89
 
67
90
  ### Basic note operations
@@ -77,6 +100,47 @@ notesia sync
77
100
  notesia auth status
78
101
  ```
79
102
 
103
+ ### Search, move, open, and capture
104
+
105
+ ```bash
106
+ # Full-text search
107
+ notesia search "meeting notes"
108
+ notesia search "meeting" --json | jq '.notes[].title'
109
+
110
+ # Move a note to a different folder
111
+ notesia move --id 12 --folder-id 3
112
+
113
+ # Open a note in the desktop app
114
+ notesia open --title "My Note"
115
+
116
+ # Quick capture to Inbox
117
+ notesia capture --title "Quick idea" --content "Look into this later"
118
+ ```
119
+
120
+ ### Prepend and pipe examples
121
+
122
+ ```bash
123
+ # Prepend content before existing note body
124
+ echo "Important: " | notesia prepend --id 5
125
+
126
+ # Capture from clipboard (macOS)
127
+ pbpaste | notesia capture --title "Clipboard"
128
+ ```
129
+
130
+ ### Tags
131
+
132
+ ```bash
133
+ # List all tags with usage counts
134
+ notesia tags
135
+ notesia tags --format json
136
+
137
+ # Add tags to a note
138
+ notesia tag add --id 42 --tag project --tag important
139
+
140
+ # Remove tags from a note
141
+ notesia tag remove --id 42 --tag draft
142
+ ```
143
+
80
144
  ### Bulk import
81
145
 
82
146
  ```bash
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clarionstack/notesia",
3
3
  "private": false,
4
- "version": "0.1.0",
4
+ "version": "0.1.1",
5
5
  "description": "Notesia desktop bridge CLI — read, write, and bulk-import notes",
6
6
  "type": "module",
7
7
  "files": [
package/src/commands.mjs CHANGED
@@ -7,15 +7,18 @@ import {
7
7
  printListResult,
8
8
  printRetrieveResult,
9
9
  printMutationResult,
10
+ printOpenResult,
10
11
  printAuthStatusResult,
11
12
  printKbResult,
13
+ printTagsResult,
12
14
  readInputContent as defaultReadInputContent,
13
15
  } from './io.mjs';
14
16
 
15
- const SUPPORTED_OPS = new Set(['get', 'list', 'store', 'update', 'append', 'sync', 'auth-status', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask', 'trash']);
17
+ const SUPPORTED_OPS = new Set(['get', 'list', 'store', 'update', 'append', 'prepend', 'move', 'open', 'sync', 'auth-status', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask', 'trash', 'search', 'capture', 'tags', 'tag-add', 'tag-remove']);
16
18
  const OP_ALIASES = new Map([
17
19
  ['retrieve', 'get'],
18
20
  ['storage', 'store'],
21
+ ['whoami', 'auth-status'],
19
22
  ]);
20
23
  const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
21
24
  const KB_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
@@ -171,6 +174,24 @@ export function parseArgs(argv = []) {
171
174
  }
172
175
  }
173
176
 
177
+ if (rawOp === 'tag') {
178
+ const subcommand = args.shift();
179
+ if (!subcommand || subcommand === '--help' || subcommand === '-h') {
180
+ return { op: 'help' };
181
+ }
182
+ const tagOps = { add: 'tag-add', remove: 'tag-remove' };
183
+ if (!tagOps[subcommand]) {
184
+ throw new CliCommandError('INVALID_OP', `Unsupported tag command: ${subcommand}. Use 'tags' to list or 'tag add/remove'.`);
185
+ }
186
+ op = tagOps[subcommand];
187
+ }
188
+
189
+ if (rawOp === 'search') {
190
+ if (args.length > 0 && !args[0].startsWith('--')) {
191
+ args.unshift('--query', args.shift());
192
+ }
193
+ }
194
+
174
195
  if (!op || op === '--help' || op === '-h') {
175
196
  return { op: 'help' };
176
197
  }
@@ -309,7 +330,7 @@ export function parseArgs(argv = []) {
309
330
  const selector = {};
310
331
  if (parsed.id !== null) selector.id = parsed.id;
311
332
  if (parsed.supabaseId) selector.supabase_id = parsed.supabaseId;
312
- if (parsed.title && op === 'get') selector.title = parsed.title;
333
+ if (parsed.title && (op === 'get' || op === 'open')) selector.title = parsed.title;
313
334
  if (Object.keys(selector).length > 0) parsed.selector = selector;
314
335
 
315
336
  return parsed;
@@ -323,9 +344,17 @@ function usageText() {
323
344
  ' get --id <id>|--supabase-id <uuid>|--title <title> [--json] [--with-meta]',
324
345
  ' list [--limit <count>] [--format table|json]',
325
346
  ' store [--title <title>] [--tag <tag>]... [--folder-id <id>] [--content <text>]',
347
+ ' capture [--title <title>] [--tag <tag>]... [--content <text>] (saves to Inbox)',
326
348
  ' update --id <id>|--supabase-id <uuid>|--title <title> [--content <text>] [--title <new>]',
327
349
  ' append --id <id>|--supabase-id <uuid>|--title <title> [--content <text>]',
350
+ ' prepend --id <id>|--supabase-id <uuid>|--title <title> [--content <text>]',
351
+ ' search <query>|--query <text> [--limit <n>] [--threshold <0-1>] [--format text|json]',
352
+ ' move --id <id>|--supabase-id <uuid>|--title <title> --folder-id <id> (0 = root)',
353
+ ' open --id <id>|--supabase-id <uuid>|--title <title>',
328
354
  ' trash --id <id>|--supabase-id <uuid>|--title <title>',
355
+ ' tags [--format table|json]',
356
+ ' tag add --id <id>|... --tag <name> [--tag <name2>]...',
357
+ ' tag remove --id <id>|... --tag <name> [--tag <name2>]...',
329
358
  ' sync',
330
359
  ' auth status [--format text|json]',
331
360
  '',
@@ -370,6 +399,10 @@ function buildPayload(parsed, pipedContent) {
370
399
  };
371
400
  }
372
401
 
402
+ if (parsed.op === 'open') {
403
+ return { selector: requireSelector(parsed) };
404
+ }
405
+
373
406
  if (parsed.op === 'list') {
374
407
  return {
375
408
  limit: parsed.limit ?? 100,
@@ -393,6 +426,14 @@ function buildPayload(parsed, pipedContent) {
393
426
  };
394
427
  }
395
428
 
429
+ if (parsed.op === 'capture') {
430
+ return {
431
+ title: parsed.title || undefined,
432
+ content: parsed.content ?? pipedContent ?? '',
433
+ tags: parsed.tags,
434
+ };
435
+ }
436
+
396
437
  if (parsed.op === 'update') {
397
438
  const content = parsed.content ?? pipedContent;
398
439
  const hasContent = content !== undefined;
@@ -424,6 +465,30 @@ function buildPayload(parsed, pipedContent) {
424
465
  };
425
466
  }
426
467
 
468
+ if (parsed.op === 'prepend') {
469
+ const content = parsed.content ?? pipedContent;
470
+ if (content === undefined || content === '') {
471
+ throw new CliCommandError(
472
+ 'MISSING_CONTENT',
473
+ 'Prepend requires non-empty --content or piped stdin'
474
+ );
475
+ }
476
+ return {
477
+ selector: requireSelector(parsed),
478
+ content,
479
+ };
480
+ }
481
+
482
+ if (parsed.op === 'move') {
483
+ if (parsed.folderId === null || parsed.folderId === undefined) {
484
+ throw new CliCommandError('MISSING_ARGS', '--folder-id is required for move (use 0 for root)');
485
+ }
486
+ return {
487
+ selector: requireSelector(parsed),
488
+ folder_id: parsed.folderId === 0 ? null : parsed.folderId,
489
+ };
490
+ }
491
+
427
492
  if (parsed.op === 'trash') {
428
493
  return { selector: requireSelector(parsed) };
429
494
  }
@@ -462,6 +527,27 @@ function buildPayload(parsed, pipedContent) {
462
527
  };
463
528
  }
464
529
 
530
+ if (parsed.op === 'search') {
531
+ if (!parsed.query) {
532
+ throw new CliCommandError('MISSING_ARGS', '--query is required for search');
533
+ }
534
+ return { query: parsed.query, limit: parsed.limit ?? 20, threshold: parsed.threshold ?? undefined };
535
+ }
536
+
537
+ if (parsed.op === 'tags') {
538
+ return {};
539
+ }
540
+
541
+ if (parsed.op === 'tag-add' || parsed.op === 'tag-remove') {
542
+ if (parsed.tags.length === 0) {
543
+ throw new CliCommandError('MISSING_ARGS', '--tag is required for tag add/remove');
544
+ }
545
+ return {
546
+ selector: requireSelector(parsed),
547
+ tags: parsed.tags,
548
+ };
549
+ }
550
+
465
551
  throw new CliCommandError('INVALID_OP', `Unsupported command: ${parsed.op} `);
466
552
  }
467
553
 
@@ -479,7 +565,7 @@ export async function runCli(argv = [], {
479
565
  return { ok: true, help: true };
480
566
  }
481
567
 
482
- const needsPipedInput = ['store', 'update', 'append'].includes(parsed.op) && parsed.content === undefined;
568
+ const needsPipedInput = ['store', 'update', 'append', 'prepend', 'capture'].includes(parsed.op) && parsed.content === undefined;
483
569
  const pipedContent = needsPipedInput ? await readInputContent() : undefined;
484
570
 
485
571
  const payload = buildPayload(parsed, pipedContent);
@@ -526,8 +612,12 @@ export async function runCli(argv = [], {
526
612
  format: parsed.format,
527
613
  writeStdout,
528
614
  });
529
- } else if (['kb-search', 'kb-folders', 'kb-context', 'kb-ask'].includes(parsed.op)) {
530
- printKbResult(parsed.op, response.data, { format: parsed.format, writeStdout });
615
+ } else if (parsed.op === 'open') {
616
+ printOpenResult(response.data, { format: parsed.format, writeStdout });
617
+ } else if (parsed.op === 'tags') {
618
+ printTagsResult(response.data, { format: parsed.format === 'text' ? 'table' : parsed.format, writeStdout });
619
+ } else if (['search', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask'].includes(parsed.op)) {
620
+ printKbResult(parsed.op === 'search' ? 'kb-search' : parsed.op, response.data, { format: parsed.format, writeStdout });
531
621
  } else {
532
622
  printMutationResult(response.data, {
533
623
  format: parsed.format,
package/src/io.mjs CHANGED
@@ -47,6 +47,18 @@ export function printRetrieveResult(result, {
47
47
  writeStdout(String(result?.content ?? ''));
48
48
  }
49
49
 
50
+ export function printOpenResult(result, {
51
+ format = 'text',
52
+ writeStdout = defaultWriteStdout,
53
+ } = {}) {
54
+ if (format === 'json') {
55
+ writeStdout(`${JSON.stringify(result ?? {}, null, 2)}\n`);
56
+ return;
57
+ }
58
+ const title = result?.title || 'Untitled';
59
+ writeStdout(`Opened: ${title} (id: ${result?.id ?? 'unknown'})\n`);
60
+ }
61
+
50
62
  export function printMutationResult(result, {
51
63
  format = 'text',
52
64
  writeStdout = defaultWriteStdout,
@@ -153,6 +165,32 @@ export function printAuthStatusResult(result, {
153
165
  writeStdout(`${lines.join('\n')}\n`);
154
166
  }
155
167
 
168
+ export function printTagsResult(result, {
169
+ format = 'table',
170
+ writeStdout = defaultWriteStdout,
171
+ } = {}) {
172
+ if (format === 'json') {
173
+ writeStdout(`${JSON.stringify(result ?? { tags: [], total: 0 }, null, 2)}\n`);
174
+ return;
175
+ }
176
+ const tags = Array.isArray(result?.tags) ? result.tags : [];
177
+ if (tags.length === 0) {
178
+ writeStdout('No tags found.\n');
179
+ return;
180
+ }
181
+ const headers = ['ID', 'NAME', 'NOTES'];
182
+ const rows = tags.map((t) => [
183
+ formatCell(t.id),
184
+ formatCell(t.name),
185
+ formatCell(t.note_count),
186
+ ]);
187
+ const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
188
+ const renderRow = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join(' ').trimEnd();
189
+ const lines = [renderRow(headers), widths.map((w) => '-'.repeat(w)).join(' '), ...rows.map(renderRow)];
190
+ writeStdout(`${lines.join('\n')}\n`);
191
+ if (result?.total != null) writeStdout(`Total: ${result.total}\n`);
192
+ }
193
+
156
194
  export function printKbResult(op, result, {
157
195
  format = 'text',
158
196
  writeStdout = defaultWriteStdout,