sensemaking 0.9.2 → 0.9.3

package/dist/esm/cli/named.js

@@ -1,5 +1,6 @@
 import { search } from '../commands.js';
 import { printRows } from '../output.js';
+import { usageError } from './exit.js';
 import { CONFIG, FORMAT, formatOf, parse, parseK, runSql, SEARCH_FLAGS, withDb } from './shared.js';
 // Fallback when the first positional is not a command: a named query from config, either a
 // SQL string (run as-is) or a saved search (run through the `search` command's own machinery).
@@ -17,11 +18,7 @@ export default async function named(ctx, queryName) {
     const configPath = values.config;
     const cfg = ctx.resolveConfig(configPath);
     const entry = cfg.queries[queryName];
-    if (entry === undefined) {
-        console.error(`unknown query: "${queryName}"`);
-        console.error(`valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);
-        process.exit(2);
-    }
+    if (entry === undefined) usageError(`unknown query: "${queryName}"`, `valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);
     if (typeof entry === 'string') {
         runSql(cfg, entry, params, format, `query "${queryName}"`);
         return;

package/dist/esm/cli/named.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/named.ts"],"sourcesContent":["import { search } from '../commands.ts';\nimport { printRows } from '../output.ts';\nimport { CONFIG, FORMAT, formatOf, parse, parseK, runSql, SEARCH_FLAGS, withDb } from './shared.ts';\nimport type { Ctx } from './types.ts';\n\n// Fallback when the first positional is not a command: a named query from config, either a\n// SQL string (run as-is) or a saved search (run through the `search` command's own machinery).\n// Flags cover both shapes -- SEARCH_FLAGS override a saved search's fields the same way they\n// override a preset's.\nexport default async function named(ctx: Ctx, queryName: string): Promise<void> {\n  const usage = `usage: ${ctx.name} ${queryName} [params...] [--format table|json] [--config path] [--where \"<sql>\"] [--k n] [--preset name] [--include glob ...] [--lexical]`;\n  const { values, positionals: params } = parse(ctx.argv, usage, { ...SEARCH_FLAGS, ...FORMAT, ...CONFIG });\n  const format = formatOf(values);\n  const configPath = values.config as string | undefined;\n\n  const cfg = ctx.resolveConfig(configPath);\n  const entry = cfg.queries[queryName];\n  if (entry === undefined) {\n    console.error(`unknown query: \"${queryName}\"`);\n    console.error(`valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);\n    process.exit(2);\n  }\n\n  if (typeof entry === 'string') {\n    runSql(cfg, entry, params, format, `query \"${queryName}\"`);\n    return;\n  }\n  if ('sql' in entry) {\n    runSql(cfg, entry.sql, params, format, `query \"${queryName}\"`);\n    return;\n  }\n\n  // A saved search's text is fixed in config; there is nowhere for a positional to bind.\n  if (params.length > 0) {\n    ctx.usageError(`\"${queryName}\" is a saved search and takes no positional parameters; edit its \"search\" in sense.config.json, or use \"${ctx.name} search\" directly`);\n  }\n  const k = parseK(values.k as string | undefined, ctx.usageError) ?? entry.k;\n  const where = (values.where as string | undefined) ?? entry.where;\n  const preset = (values.preset as string | undefined) ?? entry.preset;\n  const include = (values.include as string[] | undefined) ?? entry.include;\n  // --lexical upgrades a saved search's semantic behavior the same way --where/--k\n  // override; absent means the saved value (the flag has no default false override).\n  const semantic = values.lexical ? false : entry.semantic;\n  await withDb(ctx, configPath, async (db, resolvedCfg) => printRows(await search(db, resolvedCfg, entry.search, { k, where, preset, include, semantic }), format));\n}\n"],"names":["search","printRows","CONFIG","FORMAT","formatOf","parse","parseK","runSql","SEARCH_FLAGS","withDb","named","ctx","queryName","values","usage","name","positionals","params","argv","format","configPath","config","cfg","resolveConfig","entry","queries","undefined","console","error","Object","keys","sort","join","process","exit","sql","length","usageError","k","where","preset","include","semantic","lexical","db","resolvedCfg"],"mappings":"AAAA,SAASA,MAAM,QAAQ,iBAAiB;AACxC,SAASC,SAAS,QAAQ,eAAe;AACzC,SAASC,MAAM,EAAEC,MAAM,EAAEC,QAAQ,EAAEC,KAAK,EAAEC,MAAM,EAAEC,MAAM,EAAEC,YAAY,EAAEC,MAAM,QAAQ,cAAc;AAGpG,2FAA2F;AAC3F,+FAA+F;AAC/F,6FAA6F;AAC7F,uBAAuB;AACvB,eAAe,eAAeC,MAAMC,GAAQ,EAAEC,SAAiB;QA2BnDN,SACKO,eACCA,gBACCA;IA7BjB,MAAMC,QAAQ,CAAC,OAAO,EAAEH,IAAII,IAAI,CAAC,CAAC,EAAEH,UAAU,6HAA6H,CAAC;IAC5K,MAAM,EAAEC,MAAM,EAAEG,aAAaC,MAAM,EAAE,GAAGZ,MAAMM,IAAIO,IAAI,EAAEJ,OAAO;QAAE,GAAGN,YAAY;QAAE,GAAGL,MAAM;QAAE,GAAGD,MAAM;IAAC;IACvG,MAAMiB,SAASf,SAASS;IACxB,MAAMO,aAAaP,OAAOQ,MAAM;IAEhC,MAAMC,MAAMX,IAAIY,aAAa,CAACH;IAC9B,MAAMI,QAAQF,IAAIG,OAAO,CAACb,UAAU;IACpC,IAAIY,UAAUE,WAAW;QACvBC,QAAQC,KAAK,CAAC,CAAC,gBAAgB,EAAEhB,UAAU,CAAC,CAAC;QAC7Ce,QAAQC,KAAK,CAAC,CAAC,eAAe,EAAEC,OAAOC,IAAI,CAACR,IAAIG,OAAO,EAAEM,IAAI,GAAGC,IAAI,CAAC,OAAO;QAC5EC,QAAQC,IAAI,CAAC;IACf;IAEA,IAAI,OAAOV,UAAU,UAAU;QAC7BjB,OAAOe,KAAKE,OAAOP,QAAQE,QAAQ,CAAC,OAAO,EAAEP,UAAU,CAAC,CAAC;QACzD;IACF;IACA,IAAI,SAASY,OAAO;QAClBjB,OAAOe,KAAKE,MAAMW,GAAG,EAAElB,QAAQE,QAAQ,CAAC,OAAO,EAAEP,UAAU,CAAC,CAAC;QAC7D;IACF;IAEA,uFAAuF;IACvF,IAAIK,OAAOmB,MAAM,GAAG,GAAG;QACrBzB,IAAI0B,UAAU,CAAC,CAAC,CAAC,EAAEzB,UAAU,wGAAwG,EAAED,IAAII,IAAI,CAAC,iBAAiB,CAAC;IACpK;IACA,MAAMuB,KAAIhC,UAAAA,OAAOO,OAAOyB,CAAC,EAAwB3B,IAAI0B,UAAU,eAArD/B,qBAAAA,UAA0DkB,MAAMc,CAAC;IAC3E,MAAMC,SAAS1B,gBAAAA,OAAO0B,KAAK,cAAZ1B,2BAAAA,gBAAuCW,MAAMe,KAAK;IACjE,MAAMC,UAAU3B,iBAAAA,OAAO2B,MAAM,cAAb3B,4BAAAA,iBAAwCW,MAAMgB,MAAM;IACpE,MAAMC,WAAW5B,kBAAAA,OAAO4B,OAAO,cAAd5B,6BAAAA,kBAA2CW,MAAMiB,OAAO;IACzE,iFAAiF;IACjF,mFAAmF;IACnF,MAAMC,WAAW7B,OAAO8B,OAAO,GAAG,QAAQnB,MAAMkB,QAAQ;IACxD,MAAMjC,OAAOE,KAAKS,YAAY,OAAOwB,IAAIC,cAAgB5C,UAAU,MAAMD,OAAO4C,IAAIC,aAAarB,MAAMxB,MAAM,EAAE;YAAEsC;YAAGC;YAAOC;YAAQC;YAASC;QAAS,IAAIvB;AAC3J"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/named.ts"],"sourcesContent":["import { search } from '../commands.ts';\nimport { printRows } from '../output.ts';\nimport { usageError } from './exit.ts';\nimport { CONFIG, FORMAT, formatOf, parse, parseK, runSql, SEARCH_FLAGS, withDb } from './shared.ts';\nimport type { Ctx } from './types.ts';\n\n// Fallback when the first positional is not a command: a named query from config, either a\n// SQL string (run as-is) or a saved search (run through the `search` command's own machinery).\n// Flags cover both shapes -- SEARCH_FLAGS override a saved search's fields the same way they\n// override a preset's.\nexport default async function named(ctx: Ctx, queryName: string): Promise<void> {\n  const usage = `usage: ${ctx.name} ${queryName} [params...] [--format table|json] [--config path] [--where \"<sql>\"] [--k n] [--preset name] [--include glob ...] [--lexical]`;\n  const { values, positionals: params } = parse(ctx.argv, usage, { ...SEARCH_FLAGS, ...FORMAT, ...CONFIG });\n  const format = formatOf(values);\n  const configPath = values.config as string | undefined;\n\n  const cfg = ctx.resolveConfig(configPath);\n  const entry = cfg.queries[queryName];\n  if (entry === undefined) usageError(`unknown query: \"${queryName}\"`, `valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);\n\n  if (typeof entry === 'string') {\n    runSql(cfg, entry, params, format, `query \"${queryName}\"`);\n    return;\n  }\n  if ('sql' in entry) {\n    runSql(cfg, entry.sql, params, format, `query \"${queryName}\"`);\n    return;\n  }\n\n  // A saved search's text is fixed in config; there is nowhere for a positional to bind.\n  if (params.length > 0) {\n    ctx.usageError(`\"${queryName}\" is a saved search and takes no positional parameters; edit its \"search\" in sense.config.json, or use \"${ctx.name} search\" directly`);\n  }\n  const k = parseK(values.k as string | undefined, ctx.usageError) ?? entry.k;\n  const where = (values.where as string | undefined) ?? entry.where;\n  const preset = (values.preset as string | undefined) ?? entry.preset;\n  const include = (values.include as string[] | undefined) ?? entry.include;\n  // --lexical upgrades a saved search's semantic behavior the same way --where/--k\n  // override; absent means the saved value (the flag has no default false override).\n  const semantic = values.lexical ? false : entry.semantic;\n  await withDb(ctx, configPath, async (db, resolvedCfg) => printRows(await search(db, resolvedCfg, entry.search, { k, where, preset, include, semantic }), format));\n}\n"],"names":["search","printRows","usageError","CONFIG","FORMAT","formatOf","parse","parseK","runSql","SEARCH_FLAGS","withDb","named","ctx","queryName","values","usage","name","positionals","params","argv","format","configPath","config","cfg","resolveConfig","entry","queries","undefined","Object","keys","sort","join","sql","length","k","where","preset","include","semantic","lexical","db","resolvedCfg"],"mappings":"AAAA,SAASA,MAAM,QAAQ,iBAAiB;AACxC,SAASC,SAAS,QAAQ,eAAe;AACzC,SAASC,UAAU,QAAQ,YAAY;AACvC,SAASC,MAAM,EAAEC,MAAM,EAAEC,QAAQ,EAAEC,KAAK,EAAEC,MAAM,EAAEC,MAAM,EAAEC,YAAY,EAAEC,MAAM,QAAQ,cAAc;AAGpG,2FAA2F;AAC3F,+FAA+F;AAC/F,6FAA6F;AAC7F,uBAAuB;AACvB,eAAe,eAAeC,MAAMC,GAAQ,EAAEC,SAAiB;QAuBnDN,SACKO,eACCA,gBACCA;IAzBjB,MAAMC,QAAQ,CAAC,OAAO,EAAEH,IAAII,IAAI,CAAC,CAAC,EAAEH,UAAU,6HAA6H,CAAC;IAC5K,MAAM,EAAEC,MAAM,EAAEG,aAAaC,MAAM,EAAE,GAAGZ,MAAMM,IAAIO,IAAI,EAAEJ,OAAO;QAAE,GAAGN,YAAY;QAAE,GAAGL,MAAM;QAAE,GAAGD,MAAM;IAAC;IACvG,MAAMiB,SAASf,SAASS;IACxB,MAAMO,aAAaP,OAAOQ,MAAM;IAEhC,MAAMC,MAAMX,IAAIY,aAAa,CAACH;IAC9B,MAAMI,QAAQF,IAAIG,OAAO,CAACb,UAAU;IACpC,IAAIY,UAAUE,WAAWzB,WAAW,CAAC,gBAAgB,EAAEW,UAAU,CAAC,CAAC,EAAE,CAAC,eAAe,EAAEe,OAAOC,IAAI,CAACN,IAAIG,OAAO,EAAEI,IAAI,GAAGC,IAAI,CAAC,OAAO;IAEnI,IAAI,OAAON,UAAU,UAAU;QAC7BjB,OAAOe,KAAKE,OAAOP,QAAQE,QAAQ,CAAC,OAAO,EAAEP,UAAU,CAAC,CAAC;QACzD;IACF;IACA,IAAI,SAASY,OAAO;QAClBjB,OAAOe,KAAKE,MAAMO,GAAG,EAAEd,QAAQE,QAAQ,CAAC,OAAO,EAAEP,UAAU,CAAC,CAAC;QAC7D;IACF;IAEA,uFAAuF;IACvF,IAAIK,OAAOe,MAAM,GAAG,GAAG;QACrBrB,IAAIV,UAAU,CAAC,CAAC,CAAC,EAAEW,UAAU,wGAAwG,EAAED,IAAII,IAAI,CAAC,iBAAiB,CAAC;IACpK;IACA,MAAMkB,KAAI3B,UAAAA,OAAOO,OAAOoB,CAAC,EAAwBtB,IAAIV,UAAU,eAArDK,qBAAAA,UAA0DkB,MAAMS,CAAC;IAC3E,MAAMC,SAASrB,gBAAAA,OAAOqB,KAAK,cAAZrB,2BAAAA,gBAAuCW,MAAMU,KAAK;IACjE,MAAMC,UAAUtB,iBAAAA,OAAOsB,MAAM,cAAbtB,4BAAAA,iBAAwCW,MAAMW,MAAM;IACpE,MAAMC,WAAWvB,kBAAAA,OAAOuB,OAAO,cAAdvB,6BAAAA,kBAA2CW,MAAMY,OAAO;IACzE,iFAAiF;IACjF,mFAAmF;IACnF,MAAMC,WAAWxB,OAAOyB,OAAO,GAAG,QAAQd,MAAMa,QAAQ;IACxD,MAAM5B,OAAOE,KAAKS,YAAY,OAAOmB,IAAIC,cAAgBxC,UAAU,MAAMD,OAAOwC,IAAIC,aAAahB,MAAMzB,MAAM,EAAE;YAAEkC;YAAGC;YAAOC;YAAQC;YAASC;QAAS,IAAIlB;AAC3J"}

package/dist/esm/cli/shared.d.ts

@@ -1,18 +1,23 @@
-import type { ParseArgsOptionsConfig } from 'node:util';
 import type { ResolvedConfig } from '../config.js';
 import type { OpenResult } from '../db.js';
 import type { Ctx } from './types.js';
-export declare const FORMAT: ParseArgsOptionsConfig;
-export declare const CONFIG: ParseArgsOptionsConfig;
-export declare const SEARCH_FLAGS: ParseArgsOptionsConfig;
-type Values = Record<string, string | boolean | string[] | undefined>;
+export interface Flag {
+    type: 'string' | 'boolean';
+    default?: string | boolean;
+    multiple?: boolean;
+    short?: string;
+}
+export type Flags = Record<string, Flag>;
+export declare const FORMAT: Flags;
+export declare const CONFIG: Flags;
+export declare const SEARCH_FLAGS: Flags;
+export type Values = Record<string, string | boolean | string[] | undefined>;
 export declare function formatOf(values: Values): 'table' | 'json';
-export declare function parse(argv: string[], usage: string, options: ParseArgsOptionsConfig): {
+export declare function parse(argv: string[], usage: string, flags?: Flags): {
     values: Values;
     positionals: string[];
 };
-export declare function parseK(k: string | undefined, usageError: (message: string) => never): number | undefined;
+export declare function parseK(k: string | undefined, usageErrorFn: (message: string) => never): number | undefined;
 export declare function printWarnings(warnings: string[]): void;
 export declare function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void>;
 export declare function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string): void;
-export {};

package/dist/esm/cli/shared.js

@@ -1,8 +1,8 @@
-import { parseArgs } from 'node:util';
+import getopts from 'getopts-compat';
 import { open } from '../db.js';
 import { printRows } from '../output.js';
 import { searchError } from '../search-error.js';
-// Spreadable option fragments -- one flag name keeps one meaning across every command's table.
+import { ExitError, usageError } from './exit.js';
 export const FORMAT = {
     format: {
         type: 'string',
@@ -36,45 +36,70 @@ export const SEARCH_FLAGS = {
 export function formatOf(values) {
     return values.format === 'json' ? 'json' : 'table';
 }
-// Per-command parseArgs: strict (a foreign flag exits 2), and every table gets --help for free.
-export function parse(argv, usage, options) {
-    let values;
-    let positionals;
-    try {
-        ({ values, positionals } = parseArgs({
-            args: argv,
-            options: {
-                ...options,
-                help: {
-                    type: 'boolean',
-                    default: false,
-                    short: 'h'
-                }
-            },
-            strict: true,
-            allowPositionals: true
-        }));
-    } catch (err) {
-        console.error(err.message);
-        console.error(usage);
-        process.exit(2);
+// Per-command parse: strict (a foreign flag exits 2), and every table gets --help for free.
+export function parse(argv, usage, flags = {}) {
+    const table = {
+        ...flags,
+        help: {
+            type: 'boolean',
+            default: false,
+            short: 'h'
+        }
+    };
+    const string = [];
+    const boolean = [];
+    const alias = {};
+    const defaults = {};
+    for (const [name, flag] of Object.entries(table)){
+        (flag.type === 'boolean' ? boolean : string).push(name);
+        if (flag.default !== undefined) defaults[name] = flag.default;
+        if (flag.short !== undefined) alias[name] = flag.short;
     }
-    if (values.help) {
+    // getopts is lenient about undeclared flags -- they land in the result and are silently
+    // ignored, which is the bug 0.9.2 fixed. Record the first and fail below; returning false
+    // also keeps it out of the result. `--k -1` arrives here as unknown option "1", because
+    // getopts reads a leading dash as a new option rather than as --k's value; the message is
+    // blunter than the old one but it is still a usage error rather than a silent default.
+    let unknown;
+    const parsed = getopts(argv, {
+        string,
+        boolean,
+        alias,
+        default: defaults,
+        unknown: (name)=>{
+            if (unknown === undefined) unknown = name;
+            return false;
+        }
+    });
+    if (unknown !== undefined) usageError(`unknown option: ${unknown}`, usage);
+    if (parsed.help) {
         console.log(usage);
-        process.exit(0);
+        throw new ExitError(0);
+    }
+    // Two getopts shapes the callers must not see: an unset string flag reads as "" rather
+    // than undefined, and a flag passed once reads as a string rather than a one-element
+    // array. Both matter -- `?? saved.field` means "flag absent", and --include is a list.
+    const values = {};
+    for (const [name, flag] of Object.entries(table)){
+        const raw = parsed[name];
+        if (flag.type === 'boolean') values[name] = raw;
+        else if (flag.multiple) values[name] = raw === '' ? undefined : Array.isArray(raw) ? raw : [
+            raw
+        ];
+        else values[name] = raw === '' ? undefined : raw;
     }
     return {
         values,
-        positionals
+        positionals: parsed._
     };
 }
 // --k must be a positive integer: SQLite reads a bound LIMIT of -1 as "unlimited" and 0 as
 // "nothing", and parseInt would silently truncate "5.9" -- all three are caller mistakes
 // worth a usage error, matching the config-level SavedSearch validation.
-export function parseK(k, usageError) {
+export function parseK(k, usageErrorFn) {
     if (k === undefined) return undefined;
     const parsed = Number(k);
-    if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--k expects a positive integer, got "${k}"`);
+    if (!Number.isInteger(parsed) || parsed <= 0) usageErrorFn(`--k expects a positive integer, got "${k}"`);
     return parsed;
 }
 // Shared open-query-close envelope for commands that touch the tree.
@@ -95,10 +120,7 @@ export async function withDb(ctx, configPath, fn) {
 export function runSql(cfg, sql, params, format, label) {
     var _sql_match;
     const placeholderCount = ((_sql_match = sql.match(/\?/g)) !== null && _sql_match !== void 0 ? _sql_match : []).length;
-    if (params.length !== placeholderCount) {
-        console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);
-        process.exit(2);
-    }
+    if (params.length !== placeholderCount) usageError(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);
     const { db, warnings } = open(cfg);
     printWarnings(warnings);
     let rows;

package/dist/esm/cli/shared.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/shared.ts"],"sourcesContent":["import type { ParseArgsOptionsConfig } from 'node:util';\nimport { parseArgs } from 'node:util';\nimport type { ResolvedConfig } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport { searchError } from '../search-error.ts';\nimport type { Ctx } from './types.ts';\n\n// Spreadable option fragments -- one flag name keeps one meaning across every command's table.\nexport const FORMAT: ParseArgsOptionsConfig = { format: { type: 'string', default: 'table' } };\nexport const CONFIG: ParseArgsOptionsConfig = { config: { type: 'string' } };\nexport const SEARCH_FLAGS: ParseArgsOptionsConfig = {\n  where: { type: 'string' },\n  k: { type: 'string' },\n  preset: { type: 'string' },\n  include: { type: 'string', multiple: true },\n  lexical: { type: 'boolean', default: false },\n};\n\ntype Values = Record<string, string | boolean | string[] | undefined>;\n\nexport function formatOf(values: Values): 'table' | 'json' {\n  return values.format === 'json' ? 'json' : 'table';\n}\n\n// Per-command parseArgs: strict (a foreign flag exits 2), and every table gets --help for free.\nexport function parse(argv: string[], usage: string, options: ParseArgsOptionsConfig): { values: Values; positionals: string[] } {\n  let values: Values;\n  let positionals: string[];\n  try {\n    ({ values, positionals } = parseArgs({\n      args: argv,\n      options: { ...options, help: { type: 'boolean', default: false, short: 'h' } },\n      strict: true,\n      allowPositionals: true,\n    }));\n  } catch (err) {\n    console.error((err as Error).message);\n    console.error(usage);\n    process.exit(2);\n  }\n  if (values.help) {\n    console.log(usage);\n    process.exit(0);\n  }\n  return { values, positionals };\n}\n\n// --k must be a positive integer: SQLite reads a bound LIMIT of -1 as \"unlimited\" and 0 as\n// \"nothing\", and parseInt would silently truncate \"5.9\" -- all three are caller mistakes\n// worth a usage error, matching the config-level SavedSearch validation.\nexport function parseK(k: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (k === undefined) return undefined;\n  const parsed = Number(k);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--k expects a positive integer, got \"${k}\"`);\n  return parsed;\n}\n\n// Shared open-query-close envelope for commands that touch the tree.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport async function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) {\n    console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n    process.exit(2);\n  }\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  let rows: Row[];\n  try {\n    rows = db.prepare(sql).all(...params) as Row[];\n  } catch (err) {\n    db.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5\n    // punctuation trap applies -- the bound parameters are the search terms there. SQL\n    // without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(err as Error, params.join(' '));\n    throw err;\n  }\n  printRows(rows, format);\n  db.close();\n}\n"],"names":["parseArgs","open","printRows","searchError","FORMAT","format","type","default","CONFIG","config","SEARCH_FLAGS","where","k","preset","include","multiple","lexical","formatOf","values","parse","argv","usage","options","positionals","args","help","short","strict","allowPositionals","err","console","error","message","process","exit","log","parseK","usageError","undefined","parsed","Number","isInteger","printWarnings","warnings","w","warn","withDb","ctx","configPath","fn","cfg","resolveConfig","db","close","runSql","sql","params","label","placeholderCount","match","length","rows","prepare","all","test","join"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/shared.ts"],"sourcesContent":["import getopts from 'getopts-compat';\nimport type { ResolvedConfig } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport { searchError } from '../search-error.ts';\nimport { ExitError, usageError } from './exit.ts';\nimport type { Ctx } from './types.ts';\n\n// Flag descriptors, spreadable so one flag name keeps one meaning across every command's\n// table. parse() converts them to the getopts call the rest of the CLIs here make directly.\nexport interface Flag {\n  type: 'string' | 'boolean';\n  default?: string | boolean;\n  multiple?: boolean;\n  short?: string;\n}\nexport type Flags = Record<string, Flag>;\n\nexport const FORMAT: Flags = { format: { type: 'string', default: 'table' } };\nexport const CONFIG: Flags = { config: { type: 'string' } };\nexport const SEARCH_FLAGS: Flags = {\n  where: { type: 'string' },\n  k: { type: 'string' },\n  preset: { type: 'string' },\n  include: { type: 'string', multiple: true },\n  lexical: { type: 'boolean', default: false },\n};\n\nexport type Values = Record<string, string | boolean | string[] | undefined>;\n\nexport function formatOf(values: Values): 'table' | 'json' {\n  return values.format === 'json' ? 'json' : 'table';\n}\n\n// Per-command parse: strict (a foreign flag exits 2), and every table gets --help for free.\nexport function parse(argv: string[], usage: string, flags: Flags = {}): { values: Values; positionals: string[] } {\n  const table: Flags = { ...flags, help: { type: 'boolean', default: false, short: 'h' } };\n  const string: string[] = [];\n  const boolean: string[] = [];\n  const alias: Record<string, string> = {};\n  const defaults: Record<string, string | boolean> = {};\n  for (const [name, flag] of Object.entries(table)) {\n    (flag.type === 'boolean' ? boolean : string).push(name);\n    if (flag.default !== undefined) defaults[name] = flag.default;\n    if (flag.short !== undefined) alias[name] = flag.short;\n  }\n\n  // getopts is lenient about undeclared flags -- they land in the result and are silently\n  // ignored, which is the bug 0.9.2 fixed. Record the first and fail below; returning false\n  // also keeps it out of the result. `--k -1` arrives here as unknown option \"1\", because\n  // getopts reads a leading dash as a new option rather than as --k's value; the message is\n  // blunter than the old one but it is still a usage error rather than a silent default.\n  let unknown: string | undefined;\n  const parsed = getopts(argv, {\n    string,\n    boolean,\n    alias,\n    default: defaults,\n    unknown: (name: string): boolean => {\n      if (unknown === undefined) unknown = name;\n      return false;\n    },\n  });\n  if (unknown !== undefined) usageError(`unknown option: ${unknown}`, usage);\n  if (parsed.help) {\n    console.log(usage);\n    throw new ExitError(0);\n  }\n\n  // Two getopts shapes the callers must not see: an unset string flag reads as \"\" rather\n  // than undefined, and a flag passed once reads as a string rather than a one-element\n  // array. Both matter -- `?? saved.field` means \"flag absent\", and --include is a list.\n  const values: Values = {};\n  for (const [name, flag] of Object.entries(table)) {\n    const raw = parsed[name];\n    if (flag.type === 'boolean') values[name] = raw as boolean;\n    else if (flag.multiple) values[name] = raw === '' ? undefined : Array.isArray(raw) ? (raw as string[]) : [raw as string];\n    else values[name] = raw === '' ? undefined : (raw as string);\n  }\n  return { values, positionals: parsed._ };\n}\n\n// --k must be a positive integer: SQLite reads a bound LIMIT of -1 as \"unlimited\" and 0 as\n// \"nothing\", and parseInt would silently truncate \"5.9\" -- all three are caller mistakes\n// worth a usage error, matching the config-level SavedSearch validation.\nexport function parseK(k: string | undefined, usageErrorFn: (message: string) => never): number | undefined {\n  if (k === undefined) return undefined;\n  const parsed = Number(k);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageErrorFn(`--k expects a positive integer, got \"${k}\"`);\n  return parsed;\n}\n\n// Shared open-query-close envelope for commands that touch the tree.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport async function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) usageError(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  let rows: Row[];\n  try {\n    rows = db.prepare(sql).all(...params) as Row[];\n  } catch (err) {\n    db.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5\n    // punctuation trap applies -- the bound parameters are the search terms there. SQL\n    // without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(err as Error, params.join(' '));\n    throw err;\n  }\n  printRows(rows, format);\n  db.close();\n}\n"],"names":["getopts","open","printRows","searchError","ExitError","usageError","FORMAT","format","type","default","CONFIG","config","SEARCH_FLAGS","where","k","preset","include","multiple","lexical","formatOf","values","parse","argv","usage","flags","table","help","short","string","boolean","alias","defaults","name","flag","Object","entries","push","undefined","unknown","parsed","console","log","raw","Array","isArray","positionals","_","parseK","usageErrorFn","Number","isInteger","printWarnings","warnings","w","warn","withDb","ctx","configPath","fn","cfg","resolveConfig","db","close","runSql","sql","params","label","placeholderCount","match","length","rows","prepare","all","err","test","join"],"mappings":"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"}

package/dist/esm/cli.js

@@ -1,11 +1,13 @@
 import { createRequire } from 'node:module';
-import { parseArgs } from 'node:util';
+import exit from 'exit-compat';
+import getopts from 'getopts-compat';
+import { ExitError, usageError } from './cli/exit.js';
 import { COMMANDS, USAGE } from './cli/index.js';
 import { loadConfig, SUPPORTED_CONFIG_VERSION } from './config.js';
 // Parsing and dispatch only. Commands live in src/cli/, one file each, lazy-loaded --
 // nothing tree- or dependency-heavy may be imported at the top of this file. Flags parse
 // per command (each command's own parse() call); this file only handles the bare top-level
-// flags (--version/--help/--list/--config) and dispatch.
+// flags (--version/--help/--list/--config) and dispatch, and owns the single exit.
 // Works from dist/cjs and dist/esm alike: walk up past the dist type-marker package.json.
 function packageVersion() {
     const load = createRequire(import.meta.url);
@@ -40,87 +42,79 @@ function resolveConfigFor(name, configPath) {
     }
     return cfg;
 }
-// Thrown errors -> exit 1 with the message verbatim; usage errors exit 2 directly.
-export default async function cli(argv, name) {
-    const first = argv[0];
-    // No command word, or the first token looks like a flag: the only flags this level knows.
-    if (!first || first.startsWith('-')) {
-        let values;
-        try {
-            ({ values } = parseArgs({
-                args: argv,
-                options: {
-                    version: {
-                        type: 'boolean',
-                        default: false,
-                        short: 'v'
-                    },
-                    help: {
-                        type: 'boolean',
-                        default: false,
-                        short: 'h'
-                    },
-                    list: {
-                        type: 'boolean',
-                        default: false
-                    },
-                    config: {
-                        type: 'string'
-                    }
-                },
-                allowPositionals: true
-            }));
-        } catch (err) {
-            console.error(err.message);
-            console.error(usage(name));
-            process.exit(2);
+// The top level knows four flags and nothing else; everything past the command word is the
+// command's to parse. Reached only when there is no command word, or the first token is a flag.
+function topLevel(argv, name) {
+    let unknown;
+    const opts = getopts(argv, {
+        string: [
+            'config'
+        ],
+        boolean: [
+            'version',
+            'help',
+            'list'
+        ],
+        alias: {
+            version: 'v',
+            help: 'h'
+        },
+        default: {
+            version: false,
+            help: false,
+            list: false
+        },
+        unknown: (flag)=>{
+            if (unknown === undefined) unknown = flag;
+            return false;
         }
-        try {
-            if (values.version) {
-                console.log(`v${packageVersion()}`);
-                return;
-            }
-            if (values.help) {
-                console.log(usage(name));
-                return;
-            }
-            if (values.list) {
-                const queries = resolveConfigFor(name, values.config).queries;
-                for (const queryName of Object.keys(queries).sort()){
-                    const entry = queries[queryName];
-                    const isSavedSearch = typeof entry === 'object' && entry !== null && 'search' in entry;
-                    console.log(isSavedSearch ? `${queryName}  (search)` : queryName);
-                }
-                return;
-            }
-        } catch (err) {
-            console.error(err.message);
-            process.exit(1);
-        }
-        console.error(usage(name));
-        process.exit(2);
+    });
+    if (unknown !== undefined) usageError(`unknown option: ${unknown}`, usage(name));
+    if (opts.version) {
+        console.log(packageVersion());
+        return;
     }
-    // find -> search (breaking rename): one release of a pointer instead of "unknown query".
-    if (first === 'find') {
-        console.error(`${name}: find is now search`);
-        console.error(usage(name));
-        process.exit(2);
+    if (opts.help) {
+        console.log(usage(name));
+        return;
     }
-    const ctx = {
-        name,
-        argv: argv.slice(1),
-        resolveConfig: (configPath)=>resolveConfigFor(name, configPath),
-        usageError (message) {
-            console.error(message);
-            process.exit(2);
+    if (opts.list) {
+        const queries = resolveConfigFor(name, opts.config === '' ? undefined : opts.config).queries;
+        for (const queryName of Object.keys(queries).sort()){
+            const entry = queries[queryName];
+            const isSavedSearch = typeof entry === 'object' && entry !== null && 'search' in entry;
+            console.log(isSavedSearch ? `${queryName}  (search)` : queryName);
         }
-    };
+        return;
+    }
+    console.error(usage(name));
+    throw new ExitError(2);
+}
+// ExitError carries a chosen code; anything else is an error -> exit 1 with its message.
+export default async function cli(argv, name) {
     try {
+        const first = argv[0];
+        if (!first || first.startsWith('-')) {
+            topLevel(argv, name);
+            return;
+        }
+        // find -> search (breaking rename): one release of a pointer instead of "unknown query".
+        if (first === 'find') usageError(`${name}: find is now search`, usage(name));
+        const ctx = {
+            name,
+            argv: argv.slice(1),
+            resolveConfig: (configPath)=>resolveConfigFor(name, configPath),
+            usageError: (message)=>usageError(message)
+        };
         const load = COMMANDS[first];
         if (load) await (await load()).default(ctx);
         else await (await import('./cli/named.js')).default(ctx, first);
     } catch (err) {
+        if (err instanceof ExitError) {
+            exit(err.code);
+            return;
+        }
         console.error(err.message);
-        process.exit(1);
+        exit(1);
     }
 }

package/dist/esm/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport { parseArgs } from 'node:util';\nimport { COMMANDS, USAGE } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\nimport { loadConfig, SUPPORTED_CONFIG_VERSION } from './config.ts';\n\n// Parsing and dispatch only. Commands live in src/cli/, one file each, lazy-loaded --\n// nothing tree- or dependency-heavy may be imported at the top of this file. Flags parse\n// per command (each command's own parse() call); this file only handles the bare top-level\n// flags (--version/--help/--list/--config) and dispatch.\n\n// Works from dist/cjs and dist/esm alike: walk up past the dist type-marker package.json.\nfunction packageVersion(): string {\n  const load = createRequire(import.meta.url);\n  for (const rel of ['../package.json', '../../package.json', '../../../package.json']) {\n    try {\n      const pkg = load(rel) as { name?: string; version?: string };\n      if (pkg.name === 'sensemaking' && pkg.version) return pkg.version;\n    } catch {}\n  }\n  return 'unknown';\n}\n\nfunction usage(name: string): string {\n  const lines = Object.values(USAGE).map((u) => `       ${name} ${u}`);\n  return [`usage: ${name} <name> [params...] [--format table|json] [--config path]`, ...lines, `       ${name} --list`, `       ${name} --version`].join('\\n');\n}\n\nfunction resolveConfigFor(name: string, configPath: string | undefined) {\n  const cfg = loadConfig(configPath);\n  if (cfg.migratedFrom !== undefined) {\n    console.warn(`${name}: migrated ${cfg.configPath} from config version ${cfg.migratedFrom} to ${SUPPORTED_CONFIG_VERSION}`);\n  }\n  if (cfg.unknownKeys !== undefined) {\n    console.warn(`${name}: ${cfg.configPath} sets ${cfg.unknownKeys.join(', ')}, which this build does not read (no effect); see schema.json for the keys it does`);\n  }\n  return cfg;\n}\n\n// Thrown errors -> exit 1 with the message verbatim; usage errors exit 2 directly.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n  const first = argv[0];\n\n  // No command word, or the first token looks like a flag: the only flags this level knows.\n  if (!first || first.startsWith('-')) {\n    let values: Record<string, string | boolean | undefined>;\n    try {\n      ({ values } = parseArgs({\n        args: argv,\n        options: {\n          version: { type: 'boolean', default: false, short: 'v' },\n          help: { type: 'boolean', default: false, short: 'h' },\n          list: { type: 'boolean', default: false },\n          config: { type: 'string' },\n        },\n        allowPositionals: true,\n      }));\n    } catch (err) {\n      console.error((err as Error).message);\n      console.error(usage(name));\n      process.exit(2);\n    }\n\n    try {\n      if (values.version) {\n        console.log(`v${packageVersion()}`);\n        return;\n      }\n      if (values.help) {\n        console.log(usage(name));\n        return;\n      }\n      if (values.list) {\n        const queries = resolveConfigFor(name, values.config as string | undefined).queries;\n        for (const queryName of Object.keys(queries).sort()) {\n          const entry = queries[queryName];\n          const isSavedSearch = typeof entry === 'object' && entry !== null && 'search' in entry;\n          console.log(isSavedSearch ? `${queryName}  (search)` : queryName);\n        }\n        return;\n      }\n    } catch (err) {\n      console.error((err as Error).message);\n      process.exit(1);\n    }\n\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  // find -> search (breaking rename): one release of a pointer instead of \"unknown query\".\n  if (first === 'find') {\n    console.error(`${name}: find is now search`);\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  const ctx: Ctx = {\n    name,\n    argv: argv.slice(1),\n    resolveConfig: (configPath) => resolveConfigFor(name, configPath),\n    usageError(message) {\n      console.error(message);\n      process.exit(2);\n    },\n  };\n\n  try {\n    const load = COMMANDS[first];\n    if (load) await (await load()).default(ctx);\n    else await (await import('./cli/named.ts')).default(ctx, first);\n  } catch (err) {\n    console.error((err as Error).message);\n    process.exit(1);\n  }\n}\n"],"names":["createRequire","parseArgs","COMMANDS","USAGE","loadConfig","SUPPORTED_CONFIG_VERSION","packageVersion","load","url","rel","pkg","name","version","usage","lines","Object","values","map","u","join","resolveConfigFor","configPath","cfg","migratedFrom","undefined","console","warn","unknownKeys","cli","argv","first","startsWith","args","options","type","default","short","help","list","config","allowPositionals","err","error","message","process","exit","log","queries","queryName","keys","sort","entry","isSavedSearch","ctx","slice","resolveConfig","usageError"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport exit from 'exit-compat';\nimport getopts from 'getopts-compat';\nimport { ExitError, usageError } from './cli/exit.ts';\nimport { COMMANDS, USAGE } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\nimport { loadConfig, SUPPORTED_CONFIG_VERSION } from './config.ts';\n\n// Parsing and dispatch only. Commands live in src/cli/, one file each, lazy-loaded --\n// nothing tree- or dependency-heavy may be imported at the top of this file. Flags parse\n// per command (each command's own parse() call); this file only handles the bare top-level\n// flags (--version/--help/--list/--config) and dispatch, and owns the single exit.\n\n// Works from dist/cjs and dist/esm alike: walk up past the dist type-marker package.json.\nfunction packageVersion(): string {\n  const load = createRequire(import.meta.url);\n  for (const rel of ['../package.json', '../../package.json', '../../../package.json']) {\n    try {\n      const pkg = load(rel) as { name?: string; version?: string };\n      if (pkg.name === 'sensemaking' && pkg.version) return pkg.version;\n    } catch {}\n  }\n  return 'unknown';\n}\n\nfunction usage(name: string): string {\n  const lines = Object.values(USAGE).map((u) => `       ${name} ${u}`);\n  return [`usage: ${name} <name> [params...] [--format table|json] [--config path]`, ...lines, `       ${name} --list`, `       ${name} --version`].join('\\n');\n}\n\nfunction resolveConfigFor(name: string, configPath: string | undefined) {\n  const cfg = loadConfig(configPath);\n  if (cfg.migratedFrom !== undefined) {\n    console.warn(`${name}: migrated ${cfg.configPath} from config version ${cfg.migratedFrom} to ${SUPPORTED_CONFIG_VERSION}`);\n  }\n  if (cfg.unknownKeys !== undefined) {\n    console.warn(`${name}: ${cfg.configPath} sets ${cfg.unknownKeys.join(', ')}, which this build does not read (no effect); see schema.json for the keys it does`);\n  }\n  return cfg;\n}\n\n// The top level knows four flags and nothing else; everything past the command word is the\n// command's to parse. Reached only when there is no command word, or the first token is a flag.\nfunction topLevel(argv: string[], name: string): void {\n  let unknown: string | undefined;\n  const opts = getopts(argv, {\n    string: ['config'],\n    boolean: ['version', 'help', 'list'],\n    alias: { version: 'v', help: 'h' },\n    default: { version: false, help: false, list: false },\n    unknown: (flag: string): boolean => {\n      if (unknown === undefined) unknown = flag;\n      return false;\n    },\n  });\n  if (unknown !== undefined) usageError(`unknown option: ${unknown}`, usage(name));\n\n  if (opts.version) {\n    console.log(packageVersion());\n    return;\n  }\n  if (opts.help) {\n    console.log(usage(name));\n    return;\n  }\n  if (opts.list) {\n    const queries = resolveConfigFor(name, opts.config === '' ? undefined : (opts.config as string)).queries;\n    for (const queryName of Object.keys(queries).sort()) {\n      const entry = queries[queryName];\n      const isSavedSearch = typeof entry === 'object' && entry !== null && 'search' in entry;\n      console.log(isSavedSearch ? `${queryName}  (search)` : queryName);\n    }\n    return;\n  }\n  console.error(usage(name));\n  throw new ExitError(2);\n}\n\n// ExitError carries a chosen code; anything else is an error -> exit 1 with its message.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n  try {\n    const first = argv[0];\n    if (!first || first.startsWith('-')) {\n      topLevel(argv, name);\n      return;\n    }\n\n    // find -> search (breaking rename): one release of a pointer instead of \"unknown query\".\n    if (first === 'find') usageError(`${name}: find is now search`, usage(name));\n\n    const ctx: Ctx = {\n      name,\n      argv: argv.slice(1),\n      resolveConfig: (configPath) => resolveConfigFor(name, configPath),\n      usageError: (message) => usageError(message),\n    };\n\n    const load = COMMANDS[first];\n    if (load) await (await load()).default(ctx);\n    else await (await import('./cli/named.ts')).default(ctx, first);\n  } catch (err) {\n    if (err instanceof ExitError) {\n      exit(err.code);\n      return;\n    }\n    console.error((err as Error).message);\n    exit(1);\n  }\n}\n"],"names":["createRequire","exit","getopts","ExitError","usageError","COMMANDS","USAGE","loadConfig","SUPPORTED_CONFIG_VERSION","packageVersion","load","url","rel","pkg","name","version","usage","lines","Object","values","map","u","join","resolveConfigFor","configPath","cfg","migratedFrom","undefined","console","warn","unknownKeys","topLevel","argv","unknown","opts","string","boolean","alias","help","default","list","flag","log","queries","config","queryName","keys","sort","entry","isSavedSearch","error","cli","first","startsWith","ctx","slice","resolveConfig","message","err","code"],"mappings":"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"}

package/dist/esm/db.js

@@ -1,3 +1,8 @@
+// The package's Node floor (>=22.16) is set here and nowhere else: node:sqlite arrived in
+// 22.5, but FTS5 -- which search.ts's whole lexical half is built on -- and
+// StatementSync.columns() both landed in 22.16. 22.15 fails with "no such module: fts5".
+// Nothing outside this file, features/, and commands.ts needs anything past Node 12, so
+// raise the floor only for a sqlite capability, and lower it for nothing.
 import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';