@clarionstack/notesia 0.2.0 → 0.2.2

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/bin/notesia.mjs CHANGED
@@ -18,6 +18,8 @@ if (argv[0] === 'version' || argv[0] === '-v' || argv[0] === '--version') {
18
18
  process.exit(0);
19
19
  }
20
20
 
21
+ const ARG_ERROR_CODES = new Set(['INVALID_ARGS', 'INVALID_OP', 'MISSING_ARGS', 'SELECTOR_REQUIRED']);
22
+
21
23
  // Dispatch `notesia import` and `notesia mcp` to dedicated handlers
22
24
  if (argv[0] === 'import') {
23
25
  runImport(argv.slice(1)).catch((error) => {
@@ -32,7 +34,8 @@ if (argv[0] === 'import') {
32
34
  } else {
33
35
  runCli(argv).catch((error) => {
34
36
  const message = error?.message || 'notesia CLI failed';
35
- process.stderr.write(`${message}\n`);
36
- process.exit(1);
37
+ const prefix = error?.code ? `${error.code}: ` : '';
38
+ process.stderr.write(`${prefix}${message}\n`);
39
+ process.exit(ARG_ERROR_CODES.has(error?.code) ? 2 : 1);
37
40
  });
38
41
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clarionstack/notesia",
3
3
  "private": false,
4
- "version": "0.2.0",
4
+ "version": "0.2.2",
5
5
  "description": "Notesia desktop bridge CLI — read, write, and bulk-import notes",
6
6
  "type": "module",
7
7
  "files": [
package/src/client.mjs CHANGED
@@ -30,15 +30,23 @@ export function getDefaultBridgeInfoPath({
30
30
 
31
31
  export async function loadBridgeInfo({
32
32
  bridgeInfoPath = getDefaultBridgeInfoPath(),
33
+ readFile = fs.readFile,
33
34
  } = {}) {
34
35
  let raw;
35
36
  try {
36
- raw = await fs.readFile(bridgeInfoPath, 'utf8');
37
+ raw = await readFile(bridgeInfoPath, 'utf8');
37
38
  } catch (error) {
39
+ if (error?.code === 'EPERM' || error?.code === 'EACCES') {
40
+ throw new BridgeClientError(
41
+ 'BRIDGE_ACCESS_DENIED',
42
+ `Permission denied reading Notesia bridge info at ${bridgeInfoPath} (this shell may be sandboxed). Run outside the sandbox or allow access to TMPDIR.`,
43
+ { bridgeInfoPath, causeCode: error.code }
44
+ );
45
+ }
38
46
  if (error?.code === 'ENOENT') {
39
47
  throw new BridgeClientError(
40
48
  'NOTESIA_APP_NOT_RUNNING',
41
- 'Notesia desktop app bridge was not found. Start Notesia and try again.',
49
+ `Notesia desktop app bridge was not found at ${bridgeInfoPath}. Start Notesia and try again (if running in a sandboxed shell with a private TMPDIR, run outside the sandbox).`,
42
50
  { bridgeInfoPath }
43
51
  );
44
52
  }
@@ -137,12 +145,32 @@ export async function requestBridge(request, {
137
145
  });
138
146
 
139
147
  client.on('error', (error) => {
140
- if (error?.code === 'ENOENT' || error?.code === 'ECONNREFUSED') {
148
+ if (error?.code === 'EPERM' || error?.code === 'EACCES') {
149
+ doneReject(
150
+ new BridgeClientError(
151
+ 'BRIDGE_ACCESS_DENIED',
152
+ `Permission denied connecting to Notesia bridge at ${bridgeInfo.socketPath} (this shell may be sandboxed). Run outside the sandbox or allow Unix socket connections.`,
153
+ { socketPath: bridgeInfo.socketPath, causeCode: error.code }
154
+ )
155
+ );
156
+ return;
157
+ }
158
+ if (error?.code === 'ECONNREFUSED') {
159
+ doneReject(
160
+ new BridgeClientError(
161
+ 'NOTESIA_APP_NOT_RUNNING',
162
+ `Notesia bridge socket exists at ${bridgeInfo.socketPath} but connection was refused. Ensure the desktop app is running.`,
163
+ { socketPath: bridgeInfo.socketPath, causeCode: error.code }
164
+ )
165
+ );
166
+ return;
167
+ }
168
+ if (error?.code === 'ENOENT') {
141
169
  doneReject(
142
170
  new BridgeClientError(
143
171
  'NOTESIA_APP_NOT_RUNNING',
144
- 'Unable to connect to Notesia bridge. Ensure the desktop app is running.',
145
- { socketPath: bridgeInfo.socketPath }
172
+ `Unable to connect to Notesia bridge at ${bridgeInfo.socketPath}. Ensure the desktop app is running.`,
173
+ { socketPath: bridgeInfo.socketPath, causeCode: error.code }
146
174
  )
147
175
  );
148
176
  return;
package/src/commands.mjs CHANGED
@@ -16,7 +16,7 @@ import {
16
16
  readInputContent as defaultReadInputContent,
17
17
  } from './io.mjs';
18
18
 
19
- const SUPPORTED_OPS = new Set([
19
+ export const SUPPORTED_OPS = new Set([
20
20
  'get',
21
21
  'list',
22
22
  'store',
@@ -47,6 +47,7 @@ const OP_ALIASES = new Map([
47
47
  ['retrieve', 'get'],
48
48
  ['storage', 'store'],
49
49
  ['whoami', 'auth-status'],
50
+ ['folders', 'folder-list'],
50
51
  ]);
51
52
  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;
52
53
  const KB_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
@@ -168,6 +169,18 @@ function readFlagValue(args, index) {
168
169
  return value;
169
170
  }
170
171
 
172
+ function parseOptionalFolderId(rawValue, flagName) {
173
+ const normalized = String(rawValue ?? '').trim().toLowerCase();
174
+ if (normalized === '0' || normalized === 'null' || normalized === 'root') {
175
+ return 0;
176
+ }
177
+ const numeric = Number(rawValue);
178
+ if (!Number.isFinite(numeric) || numeric < 0) {
179
+ throw new CliCommandError('INVALID_ARGS', `${flagName} must be a non-negative number (or 0/null/root)`);
180
+ }
181
+ return numeric;
182
+ }
183
+
171
184
  export function parseArgs(argv = []) {
172
185
  const args = [...argv];
173
186
  const rawOp = args.shift();
@@ -260,6 +273,7 @@ export function parseArgs(argv = []) {
260
273
  limit: null,
261
274
  offset: null,
262
275
  threshold: null,
276
+ semantic: false,
263
277
  withMeta: false,
264
278
  query: null,
265
279
  conversationId: null,
@@ -302,10 +316,7 @@ export function parseArgs(argv = []) {
302
316
  }
303
317
 
304
318
  if (token === '--folder-id') {
305
- parsed.folderId = Number(readFlagValue(args, i));
306
- if (!Number.isFinite(parsed.folderId)) {
307
- throw new CliCommandError('INVALID_ARGS', '--folder-id must be a number');
308
- }
319
+ parsed.folderId = parseOptionalFolderId(readFlagValue(args, i), '--folder-id');
309
320
  i += 1;
310
321
  continue;
311
322
  }
@@ -352,11 +363,7 @@ export function parseArgs(argv = []) {
352
363
  }
353
364
 
354
365
  if (token === '--parent-id') {
355
- const parentId = Number(readFlagValue(args, i));
356
- if (!Number.isFinite(parentId) || parentId < 0) {
357
- throw new CliCommandError('INVALID_ARGS', '--parent-id must be a non-negative number');
358
- }
359
- parsed.parentId = parentId;
366
+ parsed.parentId = parseOptionalFolderId(readFlagValue(args, i), '--parent-id');
360
367
  i += 1;
361
368
  continue;
362
369
  }
@@ -391,6 +398,11 @@ export function parseArgs(argv = []) {
391
398
  continue;
392
399
  }
393
400
 
401
+ if (token === '--semantic') {
402
+ parsed.semantic = true;
403
+ continue;
404
+ }
405
+
394
406
  if (token === '--query') {
395
407
  parsed.query = readFlagValue(args, i);
396
408
  i += 1;
@@ -413,6 +425,16 @@ export function parseArgs(argv = []) {
413
425
  continue;
414
426
  }
415
427
 
428
+ if (token === '--tags') {
429
+ const rawTags = readFlagValue(args, i);
430
+ for (const item of rawTags.split(',')) {
431
+ const trimmed = item.trim();
432
+ if (trimmed) parsed.tags.push(trimmed);
433
+ }
434
+ i += 1;
435
+ continue;
436
+ }
437
+
416
438
  throw new CliCommandError('INVALID_ARGS', `Unknown argument: ${token} `);
417
439
  }
418
440
 
@@ -437,22 +459,22 @@ function usageText() {
437
459
  'Commands:',
438
460
  ' get --id <id>|--supabase-id <uuid>|--title <title> [--json] [--with-meta]',
439
461
  ' list [--limit <count>] [--offset <n>] [--folder-id <id>] [--tag <tag>] [--format table|json]',
440
- ' store [--title <title>] [--tag <tag>]... [--folder-id <id>] [--content <text>]',
441
- ' capture [--title <title>] [--tag <tag>]... [--content <text>] (saves to Inbox)',
442
- ' update --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>] [--title <new>]',
443
- ' append --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>]',
444
- ' prepend --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>]',
445
- ' search <query>|--query <text> [--limit <n>] [--threshold <0-1>] [--format text|json]',
446
- ' move --id <id>|--supabase-id <uuid>|--match-title <title> --folder-id <id> (0 = root)',
462
+ ' store [--title <title>] [--tag <tag>]... [--folder-id <id>] [--content <text>] [--format text|json]',
463
+ ' capture [--title <title>] [--tag <tag>]... [--content <text>] [--format text|json] (saves to Inbox)',
464
+ ' update --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>] [--title <new>] [--format text|json]',
465
+ ' append --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>] [--format text|json]',
466
+ ' prepend --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>] [--format text|json]',
467
+ ' search <query>|--query <text> [--limit <n>] [--threshold <0-1>] [--semantic] [--format text|json]',
468
+ ' move --id <id>|--supabase-id <uuid>|--match-title <title> --folder-id <id> [--format text|json] (0 = root)',
447
469
  ' open --id <id>|--supabase-id <uuid>|--title <title>',
448
- ' trash --id <id>|--supabase-id <uuid>|--match-title <title>',
470
+ ' trash --id <id>|--supabase-id <uuid>|--match-title <title> [--format text|json]',
449
471
  ' tags [--format table|json]',
450
472
  ' tag add --id <id>|--supabase-id <uuid>|--match-title <title> --tag <name> [--tag <name2>]...',
451
473
  ' tag remove --id <id>|--supabase-id <uuid>|--match-title <title> --tag <name> [--tag <name2>]...',
452
- ' folder list [--format table|json]',
474
+ ' folder list [--format table|json] (alias: folders)',
453
475
  ' folder create --name <name> [--parent-id <id>] [--icon <icon>] [--format text|json]',
454
476
  ' folder rename --id <id> --name <new> [--format text|json]',
455
- ' folder move --id <id> --parent-id <id> [--format text|json] (0 = root)',
477
+ ' folder move --id <id> --parent-id <id> [--format text|json] (0/null = root)',
456
478
  ' folder delete --id <id> [--format text|json] (empty folders only)',
457
479
  ' mcp (start stdio MCP server for external AI agents)',
458
480
  ' sync',
@@ -464,10 +486,10 @@ function usageText() {
464
486
  ' [--format text|json] [--quiet] [--verbose]',
465
487
  '',
466
488
  'AI Knowledge Base:',
467
- ' kb search --query <text> [--limit <n>] [--threshold <0-1>] [--format text|json]',
489
+ ' kb search --query <text> [--limit <n>] [--threshold <0-1>] [--semantic] [--format text|json]',
468
490
  ' kb ask --query <text> [--limit <n>] [--threshold <0-1>] [--conversation-id <uuid>] [--format text|json]',
469
491
  ' kb folders [--format text|json]',
470
- ' kb context --query <text> [--limit <n>] [--threshold <0-1>]',
492
+ ' kb context --query <text> [--limit <n>] [--threshold <0-1>] [--semantic]',
471
493
  '',
472
494
  'Pipe examples:',
473
495
  ' notesia get --id 12 > note.md',
@@ -528,7 +550,7 @@ function buildPayload(parsed, pipedContent) {
528
550
  if (parsed.op === 'store') {
529
551
  return {
530
552
  title: parsed.title || undefined,
531
- folder_id: parsed.folderId ?? null,
553
+ folder_id: parsed.folderId === null || parsed.folderId === undefined || parsed.folderId === 0 ? null : parsed.folderId,
532
554
  content: parsed.content ?? pipedContent ?? '',
533
555
  tags: parsed.tags,
534
556
  };
@@ -605,7 +627,12 @@ function buildPayload(parsed, pipedContent) {
605
627
  if (!parsed.query) {
606
628
  throw new CliCommandError('MISSING_ARGS', '--query is required for kb search');
607
629
  }
608
- return { query: parsed.query, limit: parsed.limit ?? 20, threshold: parsed.threshold ?? undefined };
630
+ return {
631
+ query: parsed.query,
632
+ limit: parsed.limit ?? 20,
633
+ threshold: parsed.threshold ?? undefined,
634
+ ...(parsed.semantic ? { semantic: true } : {}),
635
+ };
609
636
  }
610
637
 
611
638
  if (parsed.op === 'kb-folders') {
@@ -620,6 +647,7 @@ function buildPayload(parsed, pipedContent) {
620
647
  query: parsed.query,
621
648
  limit: parsed.limit ?? 5,
622
649
  threshold: parsed.threshold ?? undefined,
650
+ ...(parsed.semantic ? { semantic: true } : {}),
623
651
  };
624
652
  }
625
653
 
@@ -639,7 +667,12 @@ function buildPayload(parsed, pipedContent) {
639
667
  if (!parsed.query) {
640
668
  throw new CliCommandError('MISSING_ARGS', '--query is required for search');
641
669
  }
642
- return { query: parsed.query, limit: parsed.limit ?? 20, threshold: parsed.threshold ?? undefined };
670
+ return {
671
+ query: parsed.query,
672
+ limit: parsed.limit ?? 20,
673
+ threshold: parsed.threshold ?? undefined,
674
+ ...(parsed.semantic ? { semantic: true } : {}),
675
+ };
643
676
  }
644
677
 
645
678
  if (parsed.op === 'tags') {
package/src/io.mjs CHANGED
@@ -67,6 +67,17 @@ export function printMutationResult(result, {
67
67
  writeStdout(`${JSON.stringify(result ?? { ok: true }, null, 2)}\n`);
68
68
  return;
69
69
  }
70
+ if (result?.note && result.note.id != null) {
71
+ const parts = [`id: ${result.note.id}`];
72
+ if (result.note.supabase_id) parts.push(`supabase_id: ${result.note.supabase_id}`);
73
+ if (result.note.title) parts.push(`title: ${result.note.title}`);
74
+ writeStdout(`ok (${parts.join(', ')})\n`);
75
+ return;
76
+ }
77
+ if (result?.id != null) {
78
+ writeStdout(`ok (id: ${result.id})\n`);
79
+ return;
80
+ }
70
81
  writeStdout('ok\n');
71
82
  }
72
83
 
@@ -129,7 +140,11 @@ export function printListResult(result, {
129
140
 
130
141
  writeStdout(buildListTable(notes));
131
142
  if (typeof result?.total === 'number') {
132
- writeStdout(`Total: ${result.total}\n`);
143
+ const details = [];
144
+ if (typeof result?.offset === 'number' && result.offset > 0) details.push(`offset: ${result.offset}`);
145
+ if (result?.has_more) details.push('more available');
146
+ const suffix = details.length > 0 ? ` (${details.join(', ')})` : '';
147
+ writeStdout(`Total: ${result.total}${suffix}\n`);
133
148
  }
134
149
  }
135
150
 
package/src/mcp.mjs CHANGED
@@ -109,7 +109,7 @@ export const MCP_TOOLS = [
109
109
  required: ['query'],
110
110
  additionalProperties: false,
111
111
  },
112
- op: 'kb-search',
112
+ op: 'search',
113
113
  toPayload: (args = {}) => ({
114
114
  query: String(args.query ?? ''),
115
115
  limit: args.limit ?? 20,
@@ -385,7 +385,7 @@ const TOOL_BY_NAME = new Map(MCP_TOOLS.map((tool) => [tool.name, tool]));
385
385
 
386
386
  export function createMcpMessageHandler({
387
387
  requestBridge = defaultRequestBridge,
388
- serverVersion = '0.2.0',
388
+ serverVersion = '0.2.2',
389
389
  } = {}) {
390
390
  return async function handleMcpMessage(message) {
391
391
  if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0') {
@@ -545,7 +545,7 @@ export async function runMcpServer(args = [], {
545
545
  stdout = process.stdout,
546
546
  stderr = process.stderr,
547
547
  requestBridge = defaultRequestBridge,
548
- serverVersion = '0.2.0',
548
+ serverVersion = '0.2.2',
549
549
  } = {}) {
550
550
  if (args.includes('--help') || args.includes('-h')) {
551
551
  stdout.write(mcpUsageText());