sensemaking 0.1.0

package/dist/cjs/watch.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "runWatch", {
+    enumerable: true,
+    get: function() {
+        return runWatch;
+    }
+});
+var _nodefs = require("node:fs");
+var _configts = require("./config.js");
+var _dbts = require("./db.js");
+var _errorsts = require("./errors.js");
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+// Watch is a cache pre-warmer, not a correctness mechanism: every query
+// `open()` reconciles against the filesystem regardless, so a missed or
+// coalesced fs event can never change a query result -- it only moves one
+// file's parse from ahead-of-time to query-time. That's why any event, of
+// any kind, triggers the exact same response: a debounced full reconcile.
+// Per-file event handling would be complexity with no correctness payoff.
+var DEBOUNCE_MS = 200;
+var HEARTBEAT_INTERVAL_MS = 5000;
+var STALE_HEARTBEAT_MS = 15000;
+function runWatch(_0) {
+    return _async_to_generator(function(cfg) {
+        var opts, _opts_onEvent, onEvent, _open, db, dbPath, initialWarnings, initialParsed, baseDir, existingHeartbeat, age, touchHeartbeat, debounceTimer, scheduleReconcile, watcher, heartbeatTimer;
+        var _arguments = arguments;
+        return _ts_generator(this, function(_state) {
+            opts = _arguments.length > 1 && _arguments[1] !== void 0 ? _arguments[1] : {};
+            onEvent = (_opts_onEvent = opts.onEvent) !== null && _opts_onEvent !== void 0 ? _opts_onEvent : function() {};
+            _open = (0, _dbts.open)(cfg), db = _open.db, dbPath = _open.dbPath, initialWarnings = _open.warnings, initialParsed = _open.parsed;
+            baseDir = cfg.baseDir;
+            existingHeartbeat = (0, _dbts.getMeta)(db, 'watch_heartbeat');
+            if (existingHeartbeat && !opts.force) {
+                age = Date.now() - Date.parse(existingHeartbeat);
+                if (age >= 0 && age < STALE_HEARTBEAT_MS) {
+                    db.close();
+                    throw new _errorsts.SenseError('WATCH_ACTIVE', "another watcher appears active (heartbeat ".concat(Math.round(age / 1000), "s ago); use --force to override"));
+                }
+            }
+            onEvent({
+                type: 'started',
+                baseDir: baseDir,
+                dbPath: dbPath
+            });
+            if (initialWarnings.length > 0 || initialParsed > 0) {
+                onEvent({
+                    type: 'reconciled',
+                    parsed: initialParsed,
+                    total: (0, _dbts.docCount)(db),
+                    warnings: initialWarnings
+                });
+            }
+            touchHeartbeat = function touchHeartbeat() {
+                (0, _dbts.setMeta)(db, 'watch_heartbeat', new Date().toISOString());
+                (0, _dbts.setMeta)(db, 'watch_pid', String(process.pid));
+            };
+            touchHeartbeat();
+            debounceTimer = null;
+            scheduleReconcile = function scheduleReconcile() {
+                if (debounceTimer) clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(function() {
+                    debounceTimer = null;
+                    try {
+                        var _reconcile = (0, _dbts.reconcile)(db, cfg, baseDir), parsed = _reconcile.parsed, warnings = _reconcile.warnings;
+                        onEvent({
+                            type: 'reconciled',
+                            parsed: parsed,
+                            total: (0, _dbts.docCount)(db),
+                            warnings: warnings
+                        });
+                    } catch (err) {
+                        onEvent({
+                            type: 'reconcile-error',
+                            message: err.message
+                        });
+                    }
+                }, DEBOUNCE_MS);
+            };
+            // Ignore events from our own state dir: the heartbeat writes cache.db
+            // every few seconds, and without this filter each write would schedule a
+            // (harmless but pointless) reconcile forever — a perpetual self-trigger.
+            watcher = (0, _nodefs.watch)(baseDir, {
+                recursive: true
+            }, function(_event, filename) {
+                if (typeof filename === 'string' && filename.startsWith(_configts.STATE_DIR)) return;
+                scheduleReconcile();
+            });
+            heartbeatTimer = setInterval(touchHeartbeat, HEARTBEAT_INTERVAL_MS);
+            return [
+                2,
+                new Promise(function(resolveShutdown) {
+                    var cleanExit = function cleanExit() {
+                        clearInterval(heartbeatTimer);
+                        if (debounceTimer) clearTimeout(debounceTimer);
+                        watcher.close();
+                        (0, _dbts.setMeta)(db, 'watch_heartbeat', null);
+                        (0, _dbts.setMeta)(db, 'watch_pid', null);
+                        db.close();
+                        resolveShutdown();
+                    };
+                    process.once('SIGINT', cleanExit);
+                    process.once('SIGTERM', cleanExit);
+                })
+            ];
+        });
+    }).apply(this, arguments);
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/watch.ts"],"sourcesContent":["import { watch as fsWatch } from 'node:fs';\nimport type { ResolvedConfig } from './config.ts';\nimport { STATE_DIR } from './config.ts';\nimport { docCount, getMeta, open, reconcile, setMeta } from './db.ts';\nimport { SenseError } from './errors.ts';\n\n// Watch is a cache pre-warmer, not a correctness mechanism: every query\n// `open()` reconciles against the filesystem regardless, so a missed or\n// coalesced fs event can never change a query result -- it only moves one\n// file's parse from ahead-of-time to query-time. That's why any event, of\n// any kind, triggers the exact same response: a debounced full reconcile.\n// Per-file event handling would be complexity with no correctness payoff.\nconst DEBOUNCE_MS = 200;\nconst HEARTBEAT_INTERVAL_MS = 5000;\nconst STALE_HEARTBEAT_MS = 15000;\n\n// This module never prints -- it emits events via `onEvent` and throws on\n// the one exit-worthy condition (a live watcher already present). cli.ts is\n// the only place that touches console/process.exit.\nexport type WatchEvent = { type: 'started'; baseDir: string; dbPath: string } | { type: 'reconciled'; parsed: number; total: number; warnings: string[] } | { type: 'reconcile-error'; message: string };\n\nexport interface WatchOptions {\n  force?: boolean;\n  onEvent?: (event: WatchEvent) => void;\n}\n\n// Runs in the foreground until SIGINT/SIGTERM; never forks or daemonizes --\n// process lifecycle belongs to the OS (launchd/systemd/terminal). Resolves\n// on clean shutdown; throws SenseError(\"WATCH_ACTIVE\", ...) if another\n// watcher's heartbeat is still fresh and `--force` wasn't given.\nexport async function runWatch(cfg: ResolvedConfig, opts: WatchOptions = {}): Promise<void> {\n  const onEvent = opts.onEvent ?? (() => {});\n  const { db, dbPath, warnings: initialWarnings, parsed: initialParsed } = open(cfg);\n  const baseDir = cfg.baseDir;\n\n  const existingHeartbeat = getMeta(db, 'watch_heartbeat');\n  if (existingHeartbeat && !opts.force) {\n    const age = Date.now() - Date.parse(existingHeartbeat);\n    if (age >= 0 && age < STALE_HEARTBEAT_MS) {\n      db.close();\n      throw new SenseError('WATCH_ACTIVE', `another watcher appears active (heartbeat ${Math.round(age / 1000)}s ago); use --force to override`);\n    }\n  }\n\n  onEvent({ type: 'started', baseDir, dbPath });\n  if (initialWarnings.length > 0 || initialParsed > 0) {\n    onEvent({ type: 'reconciled', parsed: initialParsed, total: docCount(db), warnings: initialWarnings });\n  }\n\n  const touchHeartbeat = () => {\n    setMeta(db, 'watch_heartbeat', new Date().toISOString());\n    setMeta(db, 'watch_pid', String(process.pid));\n  };\n  touchHeartbeat();\n\n  let debounceTimer: NodeJS.Timeout | null = null;\n  const scheduleReconcile = () => {\n    if (debounceTimer) clearTimeout(debounceTimer);\n    debounceTimer = setTimeout(() => {\n      debounceTimer = null;\n      try {\n        const { parsed, warnings } = reconcile(db, cfg, baseDir);\n        onEvent({ type: 'reconciled', parsed, total: docCount(db), warnings });\n      } catch (err) {\n        onEvent({ type: 'reconcile-error', message: (err as Error).message });\n      }\n    }, DEBOUNCE_MS);\n  };\n\n  // Ignore events from our own state dir: the heartbeat writes cache.db\n  // every few seconds, and without this filter each write would schedule a\n  // (harmless but pointless) reconcile forever — a perpetual self-trigger.\n  const watcher = fsWatch(baseDir, { recursive: true }, (_event, filename) => {\n    if (typeof filename === 'string' && filename.startsWith(STATE_DIR)) return;\n    scheduleReconcile();\n  });\n  const heartbeatTimer = setInterval(touchHeartbeat, HEARTBEAT_INTERVAL_MS);\n\n  return new Promise<void>((resolveShutdown) => {\n    const cleanExit = () => {\n      clearInterval(heartbeatTimer);\n      if (debounceTimer) clearTimeout(debounceTimer);\n      watcher.close();\n      setMeta(db, 'watch_heartbeat', null);\n      setMeta(db, 'watch_pid', null);\n      db.close();\n      resolveShutdown();\n    };\n    process.once('SIGINT', cleanExit);\n    process.once('SIGTERM', cleanExit);\n  });\n}\n"],"names":["runWatch","DEBOUNCE_MS","HEARTBEAT_INTERVAL_MS","STALE_HEARTBEAT_MS","cfg","opts","onEvent","open","db","dbPath","initialWarnings","initialParsed","baseDir","existingHeartbeat","age","touchHeartbeat","debounceTimer","scheduleReconcile","watcher","heartbeatTimer","warnings","parsed","getMeta","force","Date","now","parse","close","SenseError","Math","round","type","length","total","docCount","setMeta","toISOString","String","process","pid","clearTimeout","setTimeout","reconcile","err","message","fsWatch","recursive","_event","filename","startsWith","STATE_DIR","setInterval","Promise","resolveShutdown","cleanExit","clearInterval","once"],"mappings":"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"}

package/dist/esm/cli.d.ts

@@ -0,0 +1 @@
+export default function cli(argv: string[], name: string): Promise<void>;

package/dist/esm/cli.js

@@ -0,0 +1,171 @@
+import { parseArgs } from 'node:util';
+import { initConfig, loadConfig } from './config.js';
+import { docCount, getMeta, open, rebuild } from './db.js';
+import { printRows } from './output.js';
+import { runWatch } from './watch.js';
+function usage(name) {
+    return `usage: ${name} <name> [params...] [--format table|json] [--config path]\n` + `       ${name} query "<sql>" [params...]\n` + `       ${name} --list\n` + `       ${name} init\n` + `       ${name} watch [--force]\n` + `       ${name} status\n` + `       ${name} rebuild`;
+}
+function parseCliArgs(argv, name) {
+    try {
+        return parseArgs({
+            args: argv,
+            options: {
+                format: {
+                    type: 'string',
+                    default: 'table'
+                },
+                config: {
+                    type: 'string'
+                },
+                list: {
+                    type: 'boolean',
+                    default: false
+                },
+                force: {
+                    type: 'boolean',
+                    default: false
+                },
+                help: {
+                    type: 'boolean',
+                    default: false,
+                    short: 'h'
+                }
+            },
+            allowPositionals: true
+        });
+    } catch (err) {
+        console.error(err.message);
+        console.error(usage(name));
+        process.exit(2);
+    }
+}
+function printWarnings(warnings) {
+    for (const w of warnings)console.warn(w);
+}
+// Shared tail of both the named-query and ad-hoc `query` paths. An unbound
+// `?` silently binds NULL and returns misleading empty results — fail
+// loudly instead. (Naive count; queries putting '?' in string literals
+// would miscount, which none of ours do.)
+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);
+    }
+    const { db, warnings } = open(cfg);
+    printWarnings(warnings);
+    const rows = db.prepare(sql).all(...params);
+    printRows(rows, format);
+    db.close();
+}
+function logWatchEvent(event) {
+    if (event.type === 'started') {
+        console.log(`sense watch: watching ${event.baseDir}`);
+        console.log(`sense watch: db ${event.dbPath}`);
+        return;
+    }
+    if (event.type === 'reconciled') {
+        printWarnings(event.warnings);
+        if (event.parsed > 0) {
+            console.log(`sense watch: reconciled, ${event.parsed} file(s) reparsed (${event.total} total)`);
+        }
+        return;
+    }
+    console.error(`sense watch: reconcile error: ${event.message}`);
+}
+// Everything below that can throw (bad JSON, a config `version` newer than
+// this build supports, another watcher's fresh heartbeat, a SQLite error)
+// is caught by the top-level handler below and reported as exit 1 with the
+// error's message verbatim. Usage errors (missing/unknown query name, wrong
+// parameter count) exit(2) directly instead of throwing.
+export default async function cli(argv, name) {
+    const { values, positionals } = parseCliArgs(argv, name);
+    if (values.help) {
+        console.log(usage(name));
+        process.exit(0);
+    }
+    // cli.ts's only config knowledge is the --config flag; discovery, parsing,
+    // and version-gating all live in config.ts.
+    const resolveConfig = ()=>loadConfig(values.config);
+    try {
+        const [first, ...rest] = positionals;
+        if (first === 'init') {
+            const configPath = initConfig(process.cwd());
+            console.log(`created ${configPath}`);
+            console.log('edit the queries to fit your tree, then: sense --list');
+            process.exit(0);
+        }
+        if (first === 'watch') {
+            const cfg = resolveConfig();
+            await runWatch(cfg, {
+                force: values.force,
+                onEvent: logWatchEvent
+            });
+            process.exit(0);
+        }
+        if (first === 'status') {
+            const cfg = resolveConfig();
+            const { db, dbPath, warnings } = open(cfg);
+            printWarnings(warnings);
+            console.log(`db: ${dbPath}`);
+            console.log(`docs: ${docCount(db)}`);
+            const heartbeat = getMeta(db, 'watch_heartbeat');
+            if (heartbeat) {
+                const ageSec = Math.round((Date.now() - Date.parse(heartbeat)) / 1000);
+                console.log(`watcher: last heartbeat ${ageSec}s ago`);
+            } else {
+                console.log('watcher: no watcher');
+            }
+            db.close();
+            process.exit(0);
+        }
+        if (first === 'rebuild') {
+            const cfg = resolveConfig();
+            const result = rebuild(cfg);
+            printWarnings(result.warnings);
+            console.log(`rebuilt: ${docCount(result.db)} docs`);
+            result.db.close();
+            process.exit(0);
+        }
+        if (values.list) {
+            const cfg = resolveConfig();
+            for (const queryName of Object.keys(cfg.queries).sort())console.log(queryName);
+            process.exit(0);
+        }
+        const format = values.format === 'json' ? 'json' : 'table';
+        // Ad-hoc SQL without touching the config -- for one-off questions;
+        // save a query into sense.config.json only when it'll be reused.
+        if (first === 'query') {
+            const [sql, ...params] = rest;
+            if (!sql) {
+                console.error(`usage: ${name} query "<sql>" [params...]`);
+                process.exit(2);
+            }
+            runSql(resolveConfig(), sql, params, format, 'ad-hoc query');
+            return;
+        }
+        const [name_, ...params] = [
+            first,
+            ...rest
+        ];
+        if (!name_) {
+            console.error(usage(name));
+            process.exit(2);
+        }
+        const cfg = resolveConfig();
+        const sql = cfg.queries[name_];
+        if (!sql) {
+            console.error(`unknown query: "${name_}"`);
+            console.error(`valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);
+            process.exit(2);
+        }
+        runSql(cfg, sql, params, format, `query "${name_}"`);
+    } catch (err) {
+        // SQLite's own error message, a bad config, an unsupported config
+        // version, or an already-active watcher — printed verbatim.
+        console.error(err.message);
+        process.exit(1);
+    }
+}

package/dist/esm/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli.ts"],"sourcesContent":["import { parseArgs } from 'node:util';\nimport type { ResolvedConfig } from './config.ts';\nimport { initConfig, loadConfig } from './config.ts';\nimport { docCount, getMeta, open, rebuild } from './db.ts';\nimport type { Row } from './output.ts';\nimport { printRows } from './output.ts';\nimport type { WatchEvent } from './watch.ts';\nimport { runWatch } from './watch.ts';\n\nfunction usage(name: string): string {\n  return `usage: ${name} <name> [params...] [--format table|json] [--config path]\\n` + `       ${name} query \"<sql>\" [params...]\\n` + `       ${name} --list\\n` + `       ${name} init\\n` + `       ${name} watch [--force]\\n` + `       ${name} status\\n` + `       ${name} rebuild`;\n}\n\nfunction parseCliArgs(argv: string[], name: string) {\n  try {\n    return parseArgs({\n      args: argv,\n      options: {\n        format: { type: 'string', default: 'table' },\n        config: { type: 'string' },\n        list: { type: 'boolean', default: false },\n        force: { type: 'boolean', default: false },\n        help: { type: 'boolean', default: false, short: 'h' },\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\nfunction printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\n// Shared tail of both the named-query and ad-hoc `query` paths. An unbound\n// `?` silently binds NULL and returns misleading empty results — fail\n// loudly instead. (Naive count; queries putting '?' in string literals\n// would miscount, which none of ours do.)\nfunction 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  const rows = db.prepare(sql).all(...params) as Row[];\n  printRows(rows, format);\n  db.close();\n}\n\nfunction logWatchEvent(event: WatchEvent): void {\n  if (event.type === 'started') {\n    console.log(`sense watch: watching ${event.baseDir}`);\n    console.log(`sense watch: db ${event.dbPath}`);\n    return;\n  }\n  if (event.type === 'reconciled') {\n    printWarnings(event.warnings);\n    if (event.parsed > 0) {\n      console.log(`sense watch: reconciled, ${event.parsed} file(s) reparsed (${event.total} total)`);\n    }\n    return;\n  }\n  console.error(`sense watch: reconcile error: ${event.message}`);\n}\n\n// Everything below that can throw (bad JSON, a config `version` newer than\n// this build supports, another watcher's fresh heartbeat, a SQLite error)\n// is caught by the top-level handler below and reported as exit 1 with the\n// error's message verbatim. Usage errors (missing/unknown query name, wrong\n// parameter count) exit(2) directly instead of throwing.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n  const { values, positionals } = parseCliArgs(argv, name);\n\n  if (values.help) {\n    console.log(usage(name));\n    process.exit(0);\n  }\n\n  // cli.ts's only config knowledge is the --config flag; discovery, parsing,\n  // and version-gating all live in config.ts.\n  const resolveConfig = () => loadConfig(values.config);\n\n  try {\n    const [first, ...rest] = positionals;\n\n    if (first === 'init') {\n      const configPath = initConfig(process.cwd());\n      console.log(`created ${configPath}`);\n      console.log('edit the queries to fit your tree, then: sense --list');\n      process.exit(0);\n    }\n\n    if (first === 'watch') {\n      const cfg = resolveConfig();\n      await runWatch(cfg, { force: values.force, onEvent: logWatchEvent });\n      process.exit(0);\n    }\n\n    if (first === 'status') {\n      const cfg = resolveConfig();\n      const { db, dbPath, warnings } = open(cfg);\n      printWarnings(warnings);\n      console.log(`db: ${dbPath}`);\n      console.log(`docs: ${docCount(db)}`);\n      const heartbeat = getMeta(db, 'watch_heartbeat');\n      if (heartbeat) {\n        const ageSec = Math.round((Date.now() - Date.parse(heartbeat)) / 1000);\n        console.log(`watcher: last heartbeat ${ageSec}s ago`);\n      } else {\n        console.log('watcher: no watcher');\n      }\n      db.close();\n      process.exit(0);\n    }\n\n    if (first === 'rebuild') {\n      const cfg = resolveConfig();\n      const result = rebuild(cfg);\n      printWarnings(result.warnings);\n      console.log(`rebuilt: ${docCount(result.db)} docs`);\n      result.db.close();\n      process.exit(0);\n    }\n\n    if (values.list) {\n      const cfg = resolveConfig();\n      for (const queryName of Object.keys(cfg.queries).sort()) console.log(queryName);\n      process.exit(0);\n    }\n\n    const format = values.format === 'json' ? 'json' : 'table';\n\n    // Ad-hoc SQL without touching the config -- for one-off questions;\n    // save a query into sense.config.json only when it'll be reused.\n    if (first === 'query') {\n      const [sql, ...params] = rest;\n      if (!sql) {\n        console.error(`usage: ${name} query \"<sql>\" [params...]`);\n        process.exit(2);\n      }\n      runSql(resolveConfig(), sql, params, format, 'ad-hoc query');\n      return;\n    }\n\n    const [name_, ...params] = [first, ...rest];\n\n    if (!name_) {\n      console.error(usage(name));\n      process.exit(2);\n    }\n\n    const cfg = resolveConfig();\n\n    const sql = cfg.queries[name_];\n    if (!sql) {\n      console.error(`unknown query: \"${name_}\"`);\n      console.error(`valid queries: ${Object.keys(cfg.queries).sort().join(', ')}`);\n      process.exit(2);\n    }\n\n    runSql(cfg, sql, params, format, `query \"${name_}\"`);\n  } catch (err) {\n    // SQLite's own error message, a bad config, an unsupported config\n    // version, or an already-active watcher — printed verbatim.\n    console.error((err as Error).message);\n    process.exit(1);\n  }\n}\n"],"names":["parseArgs","initConfig","loadConfig","docCount","getMeta","open","rebuild","printRows","runWatch","usage","name","parseCliArgs","argv","args","options","format","type","default","config","list","force","help","short","allowPositionals","err","console","error","message","process","exit","printWarnings","warnings","w","warn","runSql","cfg","sql","params","label","placeholderCount","match","length","db","rows","prepare","all","close","logWatchEvent","event","log","baseDir","dbPath","parsed","total","cli","values","positionals","resolveConfig","first","rest","configPath","cwd","onEvent","heartbeat","ageSec","Math","round","Date","now","parse","result","queryName","Object","keys","queries","sort","name_","join"],"mappings":"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"}

package/dist/esm/config.d.ts

@@ -0,0 +1,18 @@
+export declare const CONFIG_FILENAME = "sense.config.json";
+export declare const STATE_DIR = ".sense";
+export declare const SUPPORTED_CONFIG_VERSION = 1;
+export interface Config {
+    $schema?: string;
+    version?: number;
+    scan: {
+        include: string[];
+    };
+    queries: Record<string, string>;
+}
+export interface ResolvedConfig extends Config {
+    baseDir: string;
+    configPath: string | null;
+}
+export declare function initConfig(dir: string): string;
+export declare function findConfigPath(startDir: string): string | null;
+export declare function loadConfig(explicitPath?: string): ResolvedConfig;

package/dist/esm/config.js

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { SenseError } from './errors.js';
+// All config concerns live here: the file name, discovery, parsing, and
+// version gating. db.ts consumes only the result -- it does no discovery
+// and no version logic of its own.
+export const CONFIG_FILENAME = 'sense.config.json';
+export const STATE_DIR = '.sense';
+// The highest `sense.config.json` `version` this build understands. Bumped
+// only when the config *format* changes in a breaking way -- unrelated to
+// the package's own semver.
+export const SUPPORTED_CONFIG_VERSION = 1;
+// `sense init`: write a starter config into `dir` — the example doubles as
+// the documentation of the format. Refuses to overwrite an existing one.
+export function initConfig(dir) {
+    const configPath = join(dir, CONFIG_FILENAME);
+    if (existsSync(configPath)) {
+        throw new SenseError('CONFIG_EXISTS', `${CONFIG_FILENAME} already exists in ${dir}`);
+    }
+    const starter = {
+        $schema: 'https://unpkg.com/sensemaking/schema.json',
+        version: 1,
+        scan: {
+            include: [
+                '**/*.md'
+            ]
+        },
+        queries: {
+            all: 'SELECT path, title FROM docs ORDER BY path',
+            'by-tag': 'SELECT path, title FROM docs WHERE has(tags, ?) ORDER BY path'
+        }
+    };
+    writeFileSync(configPath, `${JSON.stringify(starter, null, 2)}\n`);
+    return configPath;
+}
+// Find sense.config.json by walking up from startDir, git-style.
+export function findConfigPath(startDir) {
+    let dir = resolve(startDir);
+    for(;;){
+        const candidate = join(dir, CONFIG_FILENAME);
+        if (existsSync(candidate)) return candidate;
+        const parent = dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+// Resolve + load sense.config.json: `explicitPath` bypasses walk-up
+// discovery (as `--config` does on the CLI); otherwise discovery starts at
+// process cwd. Throws on a missing config, invalid JSON, or a `version`
+// newer than this build supports -- callers surface the message and exit 1.
+export function loadConfig(explicitPath) {
+    var _cfg_version;
+    let configPath;
+    if (explicitPath) {
+        configPath = resolve(process.cwd(), explicitPath);
+        if (!existsSync(configPath)) throw new SenseError('CONFIG_NOT_FOUND', `config not found: ${configPath}`);
+    } else {
+        const found = findConfigPath(process.cwd());
+        if (!found) {
+            throw new SenseError('CONFIG_NOT_FOUND', `could not find ${CONFIG_FILENAME} in ${process.cwd()} or any parent directory`);
+        }
+        configPath = found;
+    }
+    const raw = readFileSync(configPath, 'utf8');
+    const cfg = JSON.parse(raw);
+    // Missing `version` is treated as 1. A version newer than this build
+    // supports is a hard error -- misinterpreting a future config format
+    // silently would be worse than refusing to run.
+    const version = (_cfg_version = cfg.version) !== null && _cfg_version !== void 0 ? _cfg_version : 1;
+    if (version > SUPPORTED_CONFIG_VERSION) {
+        throw new SenseError('CONFIG_VERSION_UNSUPPORTED', `config version ${version} requires a newer sense`);
+    }
+    return {
+        ...cfg,
+        baseDir: dirname(configPath),
+        configPath
+    };
+}

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/config.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { dirname, join, resolve } from 'node:path';\nimport { SenseError } from './errors.ts';\n\n// All config concerns live here: the file name, discovery, parsing, and\n// version gating. db.ts consumes only the result -- it does no discovery\n// and no version logic of its own.\n\nexport const CONFIG_FILENAME = 'sense.config.json';\nexport const STATE_DIR = '.sense';\n\n// The highest `sense.config.json` `version` this build understands. Bumped\n// only when the config *format* changes in a breaking way -- unrelated to\n// the package's own semver.\nexport const SUPPORTED_CONFIG_VERSION = 1;\n\n// sense.config.json's on-disk shape.\nexport interface Config {\n  // Editor-only pointer to schema.json; never read by sense.\n  $schema?: string;\n  // Config format version. Omitted = 1.\n  version?: number;\n  scan: { include: string[] };\n  queries: Record<string, string>;\n}\n\n// A Config resolved to where it lives on disk (or, for tests, a baseDir\n// supplied directly with no backing file). `scan.include` globs and the\n// `.sense/` state dir both resolve relative to `baseDir`, never process cwd.\nexport interface ResolvedConfig extends Config {\n  baseDir: string;\n  configPath: string | null;\n}\n\n// `sense init`: write a starter config into `dir` — the example doubles as\n// the documentation of the format. Refuses to overwrite an existing one.\nexport function initConfig(dir: string): string {\n  const configPath = join(dir, CONFIG_FILENAME);\n  if (existsSync(configPath)) {\n    throw new SenseError('CONFIG_EXISTS', `${CONFIG_FILENAME} already exists in ${dir}`);\n  }\n  const starter: Config = {\n    $schema: 'https://unpkg.com/sensemaking/schema.json',\n    version: 1,\n    scan: { include: ['**/*.md'] },\n    queries: {\n      all: 'SELECT path, title FROM docs ORDER BY path',\n      'by-tag': 'SELECT path, title FROM docs WHERE has(tags, ?) ORDER BY path',\n    },\n  };\n  writeFileSync(configPath, `${JSON.stringify(starter, null, 2)}\\n`);\n  return configPath;\n}\n\n// Find sense.config.json by walking up from startDir, git-style.\nexport function findConfigPath(startDir: string): string | null {\n  let dir = resolve(startDir);\n  for (;;) {\n    const candidate = join(dir, CONFIG_FILENAME);\n    if (existsSync(candidate)) return candidate;\n    const parent = dirname(dir);\n    if (parent === dir) return null;\n    dir = parent;\n  }\n}\n\n// Resolve + load sense.config.json: `explicitPath` bypasses walk-up\n// discovery (as `--config` does on the CLI); otherwise discovery starts at\n// process cwd. Throws on a missing config, invalid JSON, or a `version`\n// newer than this build supports -- callers surface the message and exit 1.\nexport function loadConfig(explicitPath?: string): ResolvedConfig {\n  let configPath: string;\n  if (explicitPath) {\n    configPath = resolve(process.cwd(), explicitPath);\n    if (!existsSync(configPath)) throw new SenseError('CONFIG_NOT_FOUND', `config not found: ${configPath}`);\n  } else {\n    const found = findConfigPath(process.cwd());\n    if (!found) {\n      throw new SenseError('CONFIG_NOT_FOUND', `could not find ${CONFIG_FILENAME} in ${process.cwd()} or any parent directory`);\n    }\n    configPath = found;\n  }\n\n  const raw = readFileSync(configPath, 'utf8');\n  const cfg = JSON.parse(raw) as Config;\n\n  // Missing `version` is treated as 1. A version newer than this build\n  // supports is a hard error -- misinterpreting a future config format\n  // silently would be worse than refusing to run.\n  const version = cfg.version ?? 1;\n  if (version > SUPPORTED_CONFIG_VERSION) {\n    throw new SenseError('CONFIG_VERSION_UNSUPPORTED', `config version ${version} requires a newer sense`);\n  }\n\n  return { ...cfg, baseDir: dirname(configPath), configPath };\n}\n"],"names":["existsSync","readFileSync","writeFileSync","dirname","join","resolve","SenseError","CONFIG_FILENAME","STATE_DIR","SUPPORTED_CONFIG_VERSION","initConfig","dir","configPath","starter","$schema","version","scan","include","queries","all","JSON","stringify","findConfigPath","startDir","candidate","parent","loadConfig","explicitPath","cfg","process","cwd","found","raw","parse","baseDir"],"mappings":"AAAA,SAASA,UAAU,EAAEC,YAAY,EAAEC,aAAa,QAAQ,UAAU;AAClE,SAASC,OAAO,EAAEC,IAAI,EAAEC,OAAO,QAAQ,YAAY;AACnD,SAASC,UAAU,QAAQ,cAAc;AAEzC,wEAAwE;AACxE,yEAAyE;AACzE,mCAAmC;AAEnC,OAAO,MAAMC,kBAAkB,oBAAoB;AACnD,OAAO,MAAMC,YAAY,SAAS;AAElC,2EAA2E;AAC3E,0EAA0E;AAC1E,4BAA4B;AAC5B,OAAO,MAAMC,2BAA2B,EAAE;AAoB1C,2EAA2E;AAC3E,yEAAyE;AACzE,OAAO,SAASC,WAAWC,GAAW;IACpC,MAAMC,aAAaR,KAAKO,KAAKJ;IAC7B,IAAIP,WAAWY,aAAa;QAC1B,MAAM,IAAIN,WAAW,iBAAiB,GAAGC,gBAAgB,mBAAmB,EAAEI,KAAK;IACrF;IACA,MAAME,UAAkB;QACtBC,SAAS;QACTC,SAAS;QACTC,MAAM;YAAEC,SAAS;gBAAC;aAAU;QAAC;QAC7BC,SAAS;YACPC,KAAK;YACL,UAAU;QACZ;IACF;IACAjB,cAAcU,YAAY,GAAGQ,KAAKC,SAAS,CAACR,SAAS,MAAM,GAAG,EAAE,CAAC;IACjE,OAAOD;AACT;AAEA,iEAAiE;AACjE,OAAO,SAASU,eAAeC,QAAgB;IAC7C,IAAIZ,MAAMN,QAAQkB;IAClB,OAAS;QACP,MAAMC,YAAYpB,KAAKO,KAAKJ;QAC5B,IAAIP,WAAWwB,YAAY,OAAOA;QAClC,MAAMC,SAAStB,QAAQQ;QACvB,IAAIc,WAAWd,KAAK,OAAO;QAC3BA,MAAMc;IACR;AACF;AAEA,oEAAoE;AACpE,2EAA2E;AAC3E,wEAAwE;AACxE,4EAA4E;AAC5E,OAAO,SAASC,WAAWC,YAAqB;QAmB9BC;IAlBhB,IAAIhB;IACJ,IAAIe,cAAc;QAChBf,aAAaP,QAAQwB,QAAQC,GAAG,IAAIH;QACpC,IAAI,CAAC3B,WAAWY,aAAa,MAAM,IAAIN,WAAW,oBAAoB,CAAC,kBAAkB,EAAEM,YAAY;IACzG,OAAO;QACL,MAAMmB,QAAQT,eAAeO,QAAQC,GAAG;QACxC,IAAI,CAACC,OAAO;YACV,MAAM,IAAIzB,WAAW,oBAAoB,CAAC,eAAe,EAAEC,gBAAgB,IAAI,EAAEsB,QAAQC,GAAG,GAAG,wBAAwB,CAAC;QAC1H;QACAlB,aAAamB;IACf;IAEA,MAAMC,MAAM/B,aAAaW,YAAY;IACrC,MAAMgB,MAAMR,KAAKa,KAAK,CAACD;IAEvB,qEAAqE;IACrE,qEAAqE;IACrE,gDAAgD;IAChD,MAAMjB,WAAUa,eAAAA,IAAIb,OAAO,cAAXa,0BAAAA,eAAe;IAC/B,IAAIb,UAAUN,0BAA0B;QACtC,MAAM,IAAIH,WAAW,8BAA8B,CAAC,eAAe,EAAES,QAAQ,uBAAuB,CAAC;IACvG;IAEA,OAAO;QAAE,GAAGa,GAAG;QAAEM,SAAS/B,QAAQS;QAAaA;IAAW;AAC5D"}

package/dist/esm/db.d.ts

@@ -0,0 +1,20 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { Config, ResolvedConfig } from './config.js';
+export declare const DB_FILENAME = "cache.db";
+export declare const SCHEMA_VERSION = "1";
+export interface OpenResult {
+    db: DatabaseSync;
+    cfg: ResolvedConfig;
+    dbPath: string;
+    parsed: number;
+    warnings: string[];
+}
+export declare function getMeta(db: DatabaseSync, key: string): string | null;
+export declare function setMeta(db: DatabaseSync, key: string, value: string | null): void;
+export declare function docCount(db: DatabaseSync): number;
+export declare function reconcile(db: DatabaseSync, cfg: Config, baseDir: string): {
+    parsed: number;
+    warnings: string[];
+};
+export declare function open(cfg: ResolvedConfig): OpenResult;
+export declare function rebuild(cfg: ResolvedConfig): OpenResult;