sensemaking 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Malakoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# sensemaking
+
+Query a knowledge base you build with an agent: filter notes by frontmatter, then search inside them.
+
+## The problem
+
+When you work with an AI agent on anything substantial, you end up with a pile of small notes —
+findings, decisions, sources, summaries. The pile is the point: it's how knowledge accumulates
+instead of being re-derived every session.
+
+But accumulation only pays off if it's findable. Past a couple dozen notes, an agent can't tell
+which fifteen of two hundred bear on its task, so it greps blindly, swallows the whole folder into
+context, or quietly rebuilds knowledge that already exists three files away.
+
+The classification an agent adds while writing — `status`, `type`, `tags`, `source` — is what keeps
+the pile navigable. `sensemaking` is the layer that acts on it, without an app running, a build
+step, or you re-explaining anything.
+
+## How it works
+
+Every file becomes a row; every frontmatter key becomes a column. You write named SQL queries once
+and run them by name.
+
+```markdown
+---
+title: Ship the Q3 report
+status: active
+tags: [urgent, reports]
+---
+
+Notes about the report…
+```
+
+Two properties make it trustworthy:
+
+- **Never stale.** Every query re-checks the filesystem first, re-reading only what changed. The
+  SQLite cache under `.sense/` is disposable — delete it any time, the next query rebuilds it. An
+  agent can trust a result without knowing when anything was last indexed.
+- **Headless.** Files on disk are the only source of truth. Nothing needs to be open — not
+  Obsidian, not a server, not a daemon.
+
+## Use it
+
+```bash
+npm install -g sensemaking
+cd your-notes && sense init        # writes a starter sense.config.json
+```
+
+Edit the queries to match your own frontmatter (the `$schema` line gives your editor autocomplete
+and validation):
+
+```json
+{
+  "$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"
+  }
+}
+```
+
+```
+sense all                          # run a named query
+sense by-tag urgent                # positional args bind to ? placeholders (count-checked)
+sense query "SELECT … FROM docs"   # ad-hoc SQL for one-off questions, no config edit
+sense --list                       # what queries exist
+sense <name> --format json         # structured output (the default is a table)
+sense status | rebuild             # cache info / delete .sense/ and re-crawl
+```
+
+Discovery walks up from your cwd git-style, so you can run `sense` from anywhere in the tree
+(`--config <path>` overrides). Exit codes: `0` ok, `1` real error (SQLite's message verbatim),
+`2` usage error.
+
+The one custom SQL function is `has(field, value)`: array membership on a JSON-array field (like
+`tags`), substring match on a string, always false on a missing key. Reserved columns: `path`,
+`_mtime`, `_size`.
+
+### For AI agents
+
+```bash
+npm install -g sensemaking             # the CLI
+npx skills add kmalakoff/sensemaking   # the agent skill (add -g for global, -a claude-code to target)
+```
+
+The skill teaches an agent the essentials: discovery, `--list`, `--format json`, `has()`, when to
+use ad-hoc `query` versus saving a named one, and when to `rebuild`.
+
+### Optional: a background pre-warmer
+
+`sense watch` runs the same reconcile ahead of time whenever the filesystem changes, so queries
+open on an already-warm cache. It's purely an optimization — queries reconcile on open anyway, so
+a missed event can never make a result wrong — and under ~1000 files you likely won't notice a
+difference. It runs in the foreground and never daemonizes; process supervision belongs to the OS.
+launchd and systemd examples: [WATCH.md](WATCH.md).
+
+## Why not …
+
+- **Obsidian (Bases/Dataview):** filters this well — but only inside the running Electron app,
+  through its own view formats. There's no headless mode for queries (only Sync), so scripts and
+  agents must keep the app open. `sensemaking` needs no app and speaks plain SQL. Your vault works
+  unmodified either way; Obsidian stays a fine viewer for the same files.
+- **RAG / semantic search:** retrieves by similarity and hopes relevance follows. That can't
+  express "only active notes from this project" as a hard constraint — a `WHERE` clause can. The
+  two compose rather than compete: filter first, rank later.
+- **Index-on-build tools (MarkdownDB and similar):** you run an explicit index step and query the
+  snapshot, which is stale the moment a file changes. `sensemaking` reconciles on every query, so
+  there's no stale window by construction.
+- **Note CLIs (zk and similar):** good at their own model — tags, links, full text — but they
+  can't filter on arbitrary frontmatter fields, which is the whole point here.
+- **grep / one-off scripts:** fine until you want named, reusable, parameterized queries with real
+  AND/OR/ORDER BY — at which point you've started writing a worse query engine.
+
+`sensemaking` is deliberately thin glue: [gray-matter](https://github.com/jonschlinkert/gray-matter)
+parses, [fast-glob](https://github.com/mrmlnc/fast-glob) walks, and Node's built-in SQLite
+(`node:sqlite`) does all the querying. Two dependencies, no native builds, no background services
+required.
+
+## Roadmap
+
+Content search is the next stage: BM25 relevance over note bodies, scoped to a frontmatter filter,
+so you can ask "the active within-tech notes, ranked by how well they discuss compensation" in one
+query. The filter shrinks the haystack; the search finds the needle.
+
+Beyond that, the corpus model isn't tied to markdown — anything carrying structured metadata
+(document properties, sidecar JSON) can join it without changing the query surface.
+
+## License
+
+MIT © Kevin Malakoff

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// biome-ignore lint/security/noGlobalEval: dual esm and cjs
+if (typeof require === 'undefined') eval("import('../dist/esm/cli.js').then((cli) => cli.default(process.argv.slice(2), 'sense')).catch((err) => { console.error(err); process.exit(-1); });");
+else require('../dist/cjs/cli.js')(process.argv.slice(2), 'sense');

package/dist/cjs/cli.d.cts

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

package/dist/cjs/cli.d.ts

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

package/dist/cjs/cli.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, // 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.
+"default", {
+    enumerable: true,
+    get: function() {
+        return cli;
+    }
+});
+var _nodeutil = require("node:util");
+var _configts = require("./config.js");
+var _dbts = require("./db.js");
+var _outputts = require("./output.js");
+var _watchts = require("./watch.js");
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+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 _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_array(arr) {
+    return _array_with_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_rest();
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+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
+        };
+    }
+}
+function usage(name) {
+    return "usage: ".concat(name, " <name> [params...] [--format table|json] [--config path]\n") + "       ".concat(name, ' query "<sql>" [params...]\n') + "       ".concat(name, " --list\n") + "       ".concat(name, " init\n") + "       ".concat(name, " watch [--force]\n") + "       ".concat(name, " status\n") + "       ".concat(name, " rebuild");
+}
+function parseCliArgs(argv, name) {
+    try {
+        return (0, _nodeutil.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) {
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = warnings[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var w = _step.value;
+            console.warn(w);
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+// 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 _db_prepare;
+    var _sql_match;
+    var placeholderCount = ((_sql_match = sql.match(/\?/g)) !== null && _sql_match !== void 0 ? _sql_match : []).length;
+    if (params.length !== placeholderCount) {
+        console.error("".concat(label, " expects ").concat(placeholderCount, " parameter(s), got ").concat(params.length));
+        process.exit(2);
+    }
+    var _open = (0, _dbts.open)(cfg), db = _open.db, warnings = _open.warnings;
+    printWarnings(warnings);
+    var rows = (_db_prepare = db.prepare(sql)).all.apply(_db_prepare, _to_consumable_array(params));
+    (0, _outputts.printRows)(rows, format);
+    db.close();
+}
+function logWatchEvent(event) {
+    if (event.type === 'started') {
+        console.log("sense watch: watching ".concat(event.baseDir));
+        console.log("sense watch: db ".concat(event.dbPath));
+        return;
+    }
+    if (event.type === 'reconciled') {
+        printWarnings(event.warnings);
+        if (event.parsed > 0) {
+            console.log("sense watch: reconciled, ".concat(event.parsed, " file(s) reparsed (").concat(event.total, " total)"));
+        }
+        return;
+    }
+    console.error("sense watch: reconcile error: ".concat(event.message));
+}
+function cli(argv, name) {
+    return _async_to_generator(function() {
+        var _parseCliArgs, values, positionals, resolveConfig, _positionals, first, rest, configPath, cfg, cfg1, _open, db, dbPath, warnings, heartbeat, ageSec, cfg2, result, cfg3, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, queryName, format, _rest, sql, params, _concat, name_, params1, cfg4, sql1, err1;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _parseCliArgs = parseCliArgs(argv, name), values = _parseCliArgs.values, positionals = _parseCliArgs.positionals;
+                    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.
+                    resolveConfig = function resolveConfig() {
+                        return (0, _configts.loadConfig)(values.config);
+                    };
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        4,
+                        ,
+                        5
+                    ]);
+                    _positionals = _to_array(positionals), first = _positionals[0], rest = _positionals.slice(1);
+                    if (first === 'init') {
+                        configPath = (0, _configts.initConfig)(process.cwd());
+                        console.log("created ".concat(configPath));
+                        console.log('edit the queries to fit your tree, then: sense --list');
+                        process.exit(0);
+                    }
+                    if (!(first === 'watch')) return [
+                        3,
+                        3
+                    ];
+                    cfg = resolveConfig();
+                    return [
+                        4,
+                        (0, _watchts.runWatch)(cfg, {
+                            force: values.force,
+                            onEvent: logWatchEvent
+                        })
+                    ];
+                case 2:
+                    _state.sent();
+                    process.exit(0);
+                    _state.label = 3;
+                case 3:
+                    if (first === 'status') {
+                        cfg1 = resolveConfig();
+                        _open = (0, _dbts.open)(cfg1), db = _open.db, dbPath = _open.dbPath, warnings = _open.warnings;
+                        printWarnings(warnings);
+                        console.log("db: ".concat(dbPath));
+                        console.log("docs: ".concat((0, _dbts.docCount)(db)));
+                        heartbeat = (0, _dbts.getMeta)(db, 'watch_heartbeat');
+                        if (heartbeat) {
+                            ageSec = Math.round((Date.now() - Date.parse(heartbeat)) / 1000);
+                            console.log("watcher: last heartbeat ".concat(ageSec, "s ago"));
+                        } else {
+                            console.log('watcher: no watcher');
+                        }
+                        db.close();
+                        process.exit(0);
+                    }
+                    if (first === 'rebuild') {
+                        cfg2 = resolveConfig();
+                        result = (0, _dbts.rebuild)(cfg2);
+                        printWarnings(result.warnings);
+                        console.log("rebuilt: ".concat((0, _dbts.docCount)(result.db), " docs"));
+                        result.db.close();
+                        process.exit(0);
+                    }
+                    if (values.list) {
+                        cfg3 = resolveConfig();
+                        _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                        try {
+                            for(_iterator = Object.keys(cfg3.queries).sort()[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                                queryName = _step.value;
+                                console.log(queryName);
+                            }
+                        } catch (err) {
+                            _didIteratorError = true;
+                            _iteratorError = err;
+                        } finally{
+                            try {
+                                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                    _iterator.return();
+                                }
+                            } finally{
+                                if (_didIteratorError) {
+                                    throw _iteratorError;
+                                }
+                            }
+                        }
+                        process.exit(0);
+                    }
+                    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') {
+                        _rest = _to_array(rest), sql = _rest[0], params = _rest.slice(1);
+                        if (!sql) {
+                            console.error("usage: ".concat(name, ' query "<sql>" [params...]'));
+                            process.exit(2);
+                        }
+                        runSql(resolveConfig(), sql, params, format, 'ad-hoc query');
+                        return [
+                            2
+                        ];
+                    }
+                    _concat = _to_array([
+                        first
+                    ].concat(_to_consumable_array(rest))), name_ = _concat[0], params1 = _concat.slice(1);
+                    if (!name_) {
+                        console.error(usage(name));
+                        process.exit(2);
+                    }
+                    cfg4 = resolveConfig();
+                    sql1 = cfg4.queries[name_];
+                    if (!sql1) {
+                        console.error('unknown query: "'.concat(name_, '"'));
+                        console.error("valid queries: ".concat(Object.keys(cfg4.queries).sort().join(', ')));
+                        process.exit(2);
+                    }
+                    runSql(cfg4, sql1, params1, format, 'query "'.concat(name_, '"'));
+                    return [
+                        3,
+                        5
+                    ];
+                case 4:
+                    err1 = _state.sent();
+                    // SQLite's own error message, a bad config, an unsupported config
+                    // version, or an already-active watcher — printed verbatim.
+                    console.error(err1.message);
+                    process.exit(1);
+                    return [
+                        3,
+                        5
+                    ];
+                case 5:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+/* 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/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":["cli","usage","name","parseCliArgs","argv","parseArgs","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","db","placeholderCount","match","length","open","rows","prepare","all","printRows","close","logWatchEvent","event","log","baseDir","dbPath","parsed","total","values","positionals","resolveConfig","first","rest","configPath","heartbeat","ageSec","result","queryName","name_","loadConfig","initConfig","cwd","runWatch","onEvent","docCount","getMeta","Math","round","Date","now","parse","rebuild","Object","keys","queries","sort","join"],"mappings":"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"}

package/dist/cjs/config.d.cts

@@ -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/cjs/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;