memonaut 0.2.0 → 0.4.0

package/src/cli-main.ts

@@ -13,7 +13,7 @@ import {
 	tildify,
 	type Style,
 } from './format.js';
-import {index} from './indexer.js';
+import {freshness, index} from './indexer.js';
 import {TIERS, type ChunkKind, type SearchHit, type Tier} from './model.js';
 import {readRawEntry} from './pi-source.js';
 import {
@@ -22,6 +22,13 @@ import {
 	regexSearch,
 } from './regex.js';
 import {indexStats, readThread, resolveThread, search} from './search.js';
+import {
+	availableSkills,
+	destinationFor,
+	installSkills,
+	isInstalled,
+	type Scope,
+} from './skills.js';
 
 const USAGE = `memonaut — search your agent conversation transcripts
 
@@ -33,9 +40,12 @@ COMMANDS
   search <query...>      Search transcripts, grouped by fork lineage
   search --regex <pat>   Exact regex search over the original transcripts
   show <ref>             Print a thread (file id, session uuid prefix, name or path)
+                         (show and sql sync first too; --no-sync skips it)
   sql <query>            Run a read-only SQL query against the index
   stats                  Summarise what is indexed
+  status                 How fresh the index is, and how much is pending
   config                 Show config paths, or write a starter config
+  skills [install]       List or install the agent skill (into ~/.agents/skills)
 
 SEARCH OPTIONS
   --cwd <glob>           Filter by working directory (repeatable, globs, ~ ok)
@@ -80,6 +90,9 @@ QUERY SYNTAX
   match in order, OR / NOT / NEAR(a b, 5) work, and trailing * is a prefix.
   If that fails to parse, the query is retried as quoted literal tokens.
 
+SKILLS OPTIONS
+  --project              Install into ./.agents/skills instead of ~/.agents/skills
+
 EXAMPLES
   recall search steering queue --project wherever --since 30d
   recall search '"fork point" OR parentSession' --threads all
@@ -149,15 +162,28 @@ function withTier(config: Config, tier: string | undefined): Config {
 	return {...config, tier: tier as Tier};
 }
 
-/** Cheap incremental catch-up so a query is never answered from a stale index. */
+/**
+ * Cheap incremental catch-up so a query is never answered from a stale index.
+ *
+ * A missing index builds itself here rather than failing. Telling somebody who
+ * just typed a search to go and type a different command first is a worse
+ * answer than taking ~35 s once and saying so.
+ */
 function sync(config: Config, quiet: boolean): void {
-	if (!fs.existsSync(config.dbPath)) {
-		fail(`no index at ${tildify(config.dbPath)}. Run \`recall index\` first.`);
+	// "Cold" is about whether a build has ever FINISHED, not whether a file is
+	// there: an interrupted first build leaves a file behind, and judging by
+	// existence alone would swallow the banner and hand the user a silent
+	// 35-second hang the second time too.
+	const cold = lastIndexedAt(config) === null;
+	if (cold && !quiet) {
+		process.stderr.write(
+			`recall: no index at ${tildify(config.dbPath)} yet, building it once (well under a minute)…\n`,
+		);
 	}
 	const stats = index({config, onProgress: () => {}});
 	if (!quiet && stats.filesIndexed > 0) {
 		process.stderr.write(
-			`recall: synced ${stats.filesIndexed} transcript(s) in ${stats.durationMs}ms\n`,
+			`recall: ${cold ? 'indexed' : 'synced'} ${stats.filesIndexed} transcript(s) in ${stats.durationMs}ms\n`,
 		);
 	}
 }
@@ -400,6 +426,7 @@ function cmdShow(argv: string[]): void {
 			limit: {type: 'string', default: '40'},
 			full: {type: 'boolean', default: false},
 			json: {type: 'boolean', default: false},
+			'no-sync': {type: 'boolean', default: false},
 		},
 		allowPositionals: true,
 	});
@@ -410,6 +437,10 @@ function cmdShow(argv: string[]): void {
 		);
 
 	const config = loadConfig();
+	// A thread can have grown since the search that found it, so this syncs too:
+	// "every query syncs before it answers" has to be true of all of them, or the
+	// sentence is not worth writing down.
+	if (!values['no-sync']) sync(config, Boolean(values.json));
 	const db = openDb(config.dbPath, {readOnly: true});
 	const thread = resolveThread(db, ref);
 	if (!thread) fail(`no thread matching "${ref}"`);
@@ -478,12 +509,14 @@ function cmdSql(argv: string[]): void {
 		options: {
 			json: {type: 'boolean', default: false},
 			limit: {type: 'string', default: '200'},
+			'no-sync': {type: 'boolean', default: false},
 		},
 		allowPositionals: true,
 	});
 	const sql = positionals.join(' ').trim();
 	if (!sql) fail('no SQL given');
 	const config = loadConfig();
+	if (!values['no-sync']) sync(config, Boolean(values.json));
 	const db = openDb(config.dbPath, {readOnly: true});
 	let rows: Array<Record<string, unknown>>;
 	try {
@@ -544,6 +577,85 @@ function cmdStats(argv: string[]): void {
 	db.close();
 }
 
+/** Epoch ms of the last COMPLETED catch-up, or null if one never finished. */
+function lastIndexedAt(config: Config): number | null {
+	if (!fs.existsSync(config.dbPath)) return null;
+	try {
+		const db = openDb(config.dbPath, {readOnly: true});
+		try {
+			const value = Number(getMeta(db, 'indexed_at') ?? NaN);
+			return Number.isFinite(value) ? value : null;
+		} finally {
+			db.close();
+		}
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * `recall status`: how far behind the index is, without touching it.
+ *
+ * Every read path syncs before it answers, so this is not what keeps results
+ * correct. It exists so a human (or a scheduler asking whether it is earning
+ * its keep) can see the lag, and tell "nothing to do" apart from "the next
+ * query pays for a month of catch-up".
+ */
+function cmdStatus(argv: string[]): void {
+	const {values} = parseArgs({
+		args: argv,
+		options: {json: {type: 'boolean', default: false}},
+		allowPositionals: false,
+	});
+	const config = loadConfig();
+	const report = freshness(config);
+	const pending = report.changed + report.unseen + report.vanished;
+	if (values.json) {
+		process.stdout.write(
+			JSON.stringify(
+				{
+					...report,
+					pending,
+					indexedAt: report.indexedAt
+						? new Date(report.indexedAt).toISOString()
+						: null,
+				},
+				null,
+				2,
+			) + '\n',
+		);
+		return;
+	}
+	const style = makeStyle(colorsEnabled());
+	if (!report.exists) {
+		process.stdout.write(
+			[
+				`${style.bold('no index yet')} at ${tildify(report.dbPath)}`,
+				`${report.transcriptsOnDisk} transcript(s) on disk waiting to be indexed`,
+				style.dim('Run `recall index`, or just search: any query builds it.'),
+			].join('\n') + '\n',
+		);
+		return;
+	}
+	const verdict =
+		pending === 0
+			? style.bold('up to date')
+			: style.bold(`${pending} transcript(s) pending`);
+	process.stdout.write(
+		[
+			`${verdict} · last indexed ${relativeTime(report.indexedAt ? new Date(report.indexedAt).toISOString() : null)}`,
+			`${report.transcriptsIndexed} indexed · ${report.changed} changed · ${report.unseen} never seen · ${report.vanished} gone · ${report.transcriptsOnDisk} on disk`,
+			`tier ${report.tier ?? '?'} · db ${(report.dbBytes / 1e6).toFixed(1)} MB`,
+			style.dim(tildify(report.dbPath)),
+			style.dim(
+				pending === 0
+					? 'Every search syncs first, so this is informational.'
+					: `Every search syncs first, so those ${pending} will be folded in by the next query.`,
+			),
+		].join('\n') + '\n',
+	);
+}
+
 function cmdConfig(argv: string[]): void {
 	const {values} = parseArgs({
 		args: argv,
@@ -575,6 +687,50 @@ function cmdConfig(argv: string[]): void {
 	);
 }
 
+/**
+ * `recall skills [list|install]`.
+ *
+ * Kept flag-light on purpose: the only real decision is user versus project scope.
+ */
+function cmdSkills(argv: string[]): void {
+	const scope: Scope = argv.includes('--project') ? 'project' : 'user';
+	const verb = argv.find((argument) => !argument.startsWith('-')) ?? 'list';
+	if (verb !== 'list' && verb !== 'install')
+		fail(`unknown skills command "${verb}". Try \`list\` or \`install\``);
+
+	const available = availableSkills();
+	if (available.length === 0) {
+		fail(
+			'no skills found beside this package. A published install carries them; a checkout keeps them at the repo root',
+		);
+	}
+
+	const style = makeStyle(colorsEnabled());
+	if (verb === 'list') {
+		process.stdout.write(tildify(destinationFor(scope)) + '\n\n');
+		for (const skill of available) {
+			const mark = isInstalled(skill, scope) ? 'installed' : 'not installed';
+			process.stdout.write(
+				`  ${style.bold(skill.name)}  ${style.dim(`(${mark})`)}\n    ${skill.description}\n\n`,
+			);
+		}
+		process.stdout.write('Run `recall skills install` to copy them in.\n');
+		return;
+	}
+
+	const installed = installSkills(scope);
+	for (const entry of installed) {
+		process.stdout.write(
+			`  ${entry.replaced ? 'replaced' : 'installed'}  ${tildify(entry.to)}\n`,
+		);
+	}
+	process.stdout.write(
+		style.dim(
+			`\n${installed.length} skill${installed.length === 1 ? '' : 's'} copied. They are copies, so re-run this after upgrading memonaut.\n`,
+		),
+	);
+}
+
 async function main(): Promise<void> {
 	const argv = process.argv.slice(2);
 	const command = argv[0];
@@ -591,8 +747,12 @@ async function main(): Promise<void> {
 			return cmdSql(rest);
 		case 'stats':
 			return cmdStats(rest);
+		case 'status':
+			return cmdStatus(rest);
 		case 'config':
 			return cmdConfig(rest);
+		case 'skills':
+			return cmdSkills(rest);
 		case '--version':
 		case '-v':
 			process.stdout.write(version() + '\n');

package/src/db.ts

@@ -12,6 +12,19 @@ export const SCHEMA_VERSION = 1;
 
 export type DB = DatabaseSync;
 
+/**
+ * How long a connection waits for a writer to finish before giving up.
+ *
+ * Several processes share this index by design: the human's CLI, a pi
+ * extension flushing on shutdown, and any number of concurrent agents, each of
+ * which syncs before it queries. Without a busy timeout SQLite returns
+ * SQLITE_BUSY on the FIRST contended write, which surfaces to an agent as a
+ * failed recall. A warm catch-up takes ~120 ms and a cold build ~35 s, so 5 s
+ * covers every realistic overlap except a first-ever build, which is exactly
+ * the case where failing fast and reporting it is the honest answer.
+ */
+const BUSY_TIMEOUT_MS = 5_000;
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS meta(
   key TEXT PRIMARY KEY,
@@ -107,6 +120,15 @@ export interface OpenOptions {
 	readOnly?: boolean;
 	/** Throw instead of rebuilding when the schema version differs. */
 	noRebuild?: boolean;
+	/**
+	 * Leave `query_only` off on a read-only connection, so TEMP objects can be
+	 * created. The index file itself is still unwritable, because that comes
+	 * from opening it read-only, not from the pragma.
+	 *
+	 * This exists for one caller: the SQL tool shadows the real tables with temp
+	 * views so arbitrary queries cannot reach private transcripts.
+	 */
+	writableTemp?: boolean;
 }
 
 export function getMeta(db: DB, key: string): string | undefined {
@@ -133,13 +155,17 @@ export function openDb(dbPath: string, opts: OpenOptions = {}): DB {
 			throw new Error(`no index at ${dbPath}. Run \`recall index\` first.`);
 		}
 		const db = new DatabaseSync(dbPath, {readOnly: true});
-		db.exec('PRAGMA query_only = 1');
+		if (!opts.writableTemp) db.exec('PRAGMA query_only = 1');
+		// Readers do not block on writers under WAL, but they do contend with
+		// checkpointing, so the timeout matters here too.
+		db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
 		return db;
 	}
 
 	fs.mkdirSync(path.dirname(dbPath), {recursive: true});
 	const fresh = !fs.existsSync(dbPath);
 	const db = new DatabaseSync(dbPath);
+	db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
 	db.exec('PRAGMA journal_mode = WAL');
 	db.exec('PRAGMA synchronous = NORMAL');
 	db.exec('PRAGMA foreign_keys = OFF');

package/src/index.ts

@@ -16,4 +16,5 @@ export {
 	ripgrepBinary,
 } from './ripgrep.js';
 export * from './format.js';
+export * from './skills.js';
 export {silenceSqliteWarning} from './quiet.js';

package/src/indexer.ts

@@ -20,6 +20,21 @@ export interface IndexOptions {
 	full?: boolean;
 	db?: DB;
 	onProgress?: (progress: IndexProgress) => void;
+	/**
+	 * Stop ingesting once this many ms have passed, leaving the rest for the
+	 * next run. Checked BETWEEN lineages, never inside one, so the per-lineage
+	 * transaction and the watermark-written-last rule both still hold.
+	 *
+	 * For callers that must not hang: a session shutting down after a long gap
+	 * could otherwise sit through a multi-second catch-up on the way out.
+	 *
+	 * It bounds the INGEST LOOP, not the whole run: the scan and the identity
+	 * pass ahead of it are ~120 ms on a 4,831-file corpus and always run. A full
+	 * rebuild is refused outright rather than truncated, see below.
+	 */
+	budgetMs?: number;
+	/** Clock seam, so the budget can be tested without racing a real one. */
+	now?: () => number;
 }
 
 export interface IndexProgress {
@@ -45,6 +60,8 @@ export interface IndexStats {
 	bytesRead: number;
 	durationMs: number;
 	fullRebuild: boolean;
+	/** True when `budgetMs` cut the run short and work is still outstanding. */
+	budgetExhausted: boolean;
 }
 
 interface FileRow {
@@ -78,7 +95,8 @@ function probe(file: string): {
 }
 
 export function index(opts: IndexOptions): IndexStats {
-	const started = Date.now();
+	const clock = opts.now ?? Date.now;
+	const started = clock();
 	const {config} = opts;
 	const db = opts.db ?? openDb(config.dbPath);
 	const report = opts.onProgress ?? (() => {});
@@ -99,6 +117,7 @@ export function index(opts: IndexOptions): IndexStats {
 		bytesRead: 0,
 		durationMs: 0,
 		fullRebuild: false,
+		budgetExhausted: false,
 	};
 
 	// A tier change alters what text exists at all, so it forces a rebuild.
@@ -107,6 +126,18 @@ export function index(opts: IndexOptions): IndexStats {
 	if (storedTier !== undefined && storedTier !== config.tier) full = true;
 	stats.fullRebuild = full;
 
+	// A rebuild is all-or-nothing: it DELETEs every chunk, entry and membership
+	// before reading a byte, so truncating one would leave an index that later
+	// queries would answer from as though it were complete. A budget means the
+	// caller cannot afford to finish, so the honest move is not to start.
+	// Reachable without `opts.full`: a tier change forces one (line above).
+	if (full && opts.budgetMs !== undefined) {
+		stats.budgetExhausted = true;
+		stats.durationMs = clock() - started;
+		if (!opts.db) db.close();
+		return stats;
+	}
+
 	const isIgnored = matcher(config.ignore);
 	const isPrivate = matcher(config.private);
 
@@ -397,6 +428,12 @@ export function index(opts: IndexOptions): IndexStats {
 
 	let done = 0;
 	for (const unit of work) {
+		// `>=` so that a budget of 0 means "do nothing", even on a machine fast
+		// enough to reach this in the same millisecond it started.
+		if (opts.budgetMs !== undefined && clock() - started >= opts.budgetMs) {
+			stats.budgetExhausted = true;
+			break;
+		}
 		db.exec('BEGIN');
 		try {
 			const lineageId = idOf.get(unit.lineageRoot);
@@ -493,10 +530,13 @@ export function index(opts: IndexOptions): IndexStats {
 	}
 
 	setMeta(db, 'tier', config.tier);
-	setMeta(db, 'indexed_at', String(Date.now()));
+	// Only claim to be caught up when we actually are. `indexed_at` is what the
+	// sync TTL reads, so advancing it after a budget-truncated run would let the
+	// next query skip the catch-up and answer from an index we KNOW is behind.
+	if (!stats.budgetExhausted) setMeta(db, 'indexed_at', String(Date.now()));
 	setMeta(db, 'roots', JSON.stringify(config.sources.map((s) => s.root)));
 
-	stats.durationMs = Date.now() - started;
+	stats.durationMs = clock() - started;
 	if (!opts.db) db.close();
 	return stats;
 }
@@ -512,6 +552,22 @@ export interface SyncResult {
 	stats?: IndexStats;
 }
 
+/**
+ * There is no index yet, as opposed to there being one that could not be read.
+ *
+ * The distinction is the whole point of the type. "No index" is fixed by
+ * building one; "index is locked" or "index is corrupt" is not, and a caller
+ * that collapses the two tells the user to run a command that will not help.
+ */
+export class MissingIndexError extends Error {
+	readonly dbPath: string;
+	constructor(dbPath: string) {
+		super(`no index at ${dbPath}`);
+		this.name = 'MissingIndexError';
+		this.dbPath = dbPath;
+	}
+}
+
 /**
  * Catch the index up, unless it was already synced within `ttlMs`.
  *
@@ -520,15 +576,137 @@ export interface SyncResult {
  * turn. The TTL is what makes "always fresh" affordable for callers that query
  * in a burst.
  */
-export function syncIfStale(config: Config, ttlMs = 15_000): SyncResult {
-	if (!fs.existsSync(config.dbPath))
-		throw new Error(`no index at ${config.dbPath}`);
+export function syncIfStale(
+	config: Config,
+	ttlMs = 15_000,
+	budgetMs?: number,
+): SyncResult {
+	if (!fs.existsSync(config.dbPath)) throw new MissingIndexError(config.dbPath);
 	const db = openDb(config.dbPath);
 	try {
 		const last = Number(getMeta(db, 'indexed_at') ?? 0);
 		if (Number.isFinite(last) && Date.now() - last < ttlMs) return {ran: false};
-		return {ran: true, stats: index({config, db})};
+		return {ran: true, stats: index({config, db, budgetMs})};
 	} finally {
 		db.close();
 	}
 }
+
+export interface Freshness {
+	dbPath: string;
+	exists: boolean;
+	dbBytes: number;
+	tier: string | null;
+	/** When the last catch-up finished, epoch ms. */
+	indexedAt: number | null;
+	ageMs: number | null;
+	/** Transcripts on disk, before ignore rules. */
+	transcriptsOnDisk: number;
+	/** Transcripts the index knows about. */
+	transcriptsIndexed: number;
+	/** Known transcripts that have grown or changed since their watermark. */
+	changed: number;
+	/**
+	 * Transcripts whose CONTENT is not in the index: never discovered, or
+	 * discovered but not yet ingested (a run cut short by its time budget
+	 * registers the file before reading it). Ignore rules applied.
+	 */
+	unseen: number;
+	/** Indexed transcripts no longer on disk, which the next sync will delete. */
+	vanished: number;
+	sources: string[];
+}
+
+/**
+ * How far behind the index is, without changing it.
+ *
+ * This is a `stat` pass over the corpus plus a header read for the few files
+ * the index has never seen, because whether a new file is ignored can only be
+ * decided from its header `cwd`, never from its mangled directory name.
+ * Measured at ~70 ms over 4,831 transcripts.
+ *
+ * Every read path already syncs before it answers, so this is not how anything
+ * stays correct: it is how a human or an agent can SEE the lag, and how they
+ * can tell "nothing to do" apart from "about to pay for a month of catch-up".
+ */
+export function freshness(config: Config): Freshness {
+	const report: Freshness = {
+		dbPath: config.dbPath,
+		exists: fs.existsSync(config.dbPath),
+		dbBytes: 0,
+		tier: null,
+		indexedAt: null,
+		ageMs: null,
+		transcriptsOnDisk: 0,
+		transcriptsIndexed: 0,
+		changed: 0,
+		unseen: 0,
+		vanished: 0,
+		sources: config.sources.map((s) => s.root),
+	};
+
+	// Null size/mtime means "row exists, content never ingested", which is a
+	// different thing from "ingested and since changed", so the nulls are kept.
+	const known = new Map<string, {size: number | null; mtime: number | null}>();
+	if (report.exists) {
+		report.dbBytes = fs.statSync(config.dbPath).size;
+		const db = openDb(config.dbPath, {readOnly: true});
+		try {
+			report.tier = getMeta(db, 'tier') ?? null;
+			const at = Number(getMeta(db, 'indexed_at') ?? NaN);
+			if (Number.isFinite(at)) {
+				report.indexedAt = at;
+				report.ageMs = Date.now() - at;
+			}
+			for (const row of db
+				.prepare('SELECT path, size, mtime FROM file')
+				.all() as unknown as Array<{
+				path: string;
+				size: number | null;
+				mtime: number | null;
+			}>) {
+				known.set(row.path, {
+					size: row.size === null ? null : num(row.size),
+					mtime: row.mtime === null ? null : num(row.mtime),
+				});
+			}
+		} finally {
+			db.close();
+		}
+	}
+	report.transcriptsIndexed = known.size;
+
+	const isIgnored = matcher(config.ignore);
+	// Tracked so a deletion counts as pending work too: reporting "up to date"
+	// while the next sync still has N `deleteFile` calls to make would undercut
+	// the only thing this command is for.
+	const seen = new Set<string>();
+	for (const source of config.sources) {
+		if (!fs.existsSync(source.root)) continue;
+		for (const file of listTranscripts(source.root)) {
+			report.transcriptsOnDisk++;
+			let st: fs.Stats;
+			try {
+				st = fs.statSync(file);
+			} catch {
+				continue;
+			}
+			seen.add(file);
+			const row = known.get(file);
+			if (!row) {
+				// Only a file the index has never heard of has to be opened, and only
+				// because the ignore rules match the header cwd, never the mangled
+				// directory name.
+				const header = readHeader(file);
+				if (header && !isIgnored(header.cwd ?? file)) report.unseen++;
+				continue;
+			}
+			if (row.size === null || row.mtime === null) report.unseen++;
+			else if (row.size !== st.size || row.mtime !== Math.floor(st.mtimeMs))
+				report.changed++;
+		}
+	}
+	for (const knownPath of known.keys())
+		if (!seen.has(knownPath)) report.vanished++;
+	return report;
+}

package/src/resources.ts

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+
+/**
+ * Finding files that ship beside the package rather than inside `dist`.
+ *
+ * A published install carries `skills/` next to `dist/`, staged there at build time. A checkout
+ * keeps the same directory at the repo root, three levels above `packages/memonaut/dist`. Both are
+ * searched instead of one being made canonical, so `recall skills` behaves the same whether it is
+ * run from a global install, from the workspace, or through `tsx src/cli.ts`.
+ */
+const ROOTS = ['../', '../../../'];
+
+export function resolvePackageResource(relative: string): string | undefined {
+	for (const root of ROOTS) {
+		try {
+			const candidate = fileURLToPath(
+				new URL(`${root}${relative}`, import.meta.url),
+			);
+			if (fs.existsSync(candidate)) return candidate;
+		} catch {
+			continue;
+		}
+	}
+	return undefined;
+}

package/src/skills.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {resolvePackageResource} from './resources.js';
+
+/**
+ * Installing the agent skill that ships with this package.
+ *
+ * pi loads the skill itself from `memonaut-pi` (its `pi.skills` entry), so this command exists for
+ * every other agent: the skill is the same file, and `~/.agents/skills/<name>` is where agents that
+ * are not pi look for it. One directory, no fan-out to twenty agent-specific locations, and the
+ * report names every path written.
+ */
+
+export interface Skill {
+	name: string;
+	description: string;
+	from: string;
+}
+
+export type Scope = 'user' | 'project';
+
+/** Where skills live, by convention. `project` keeps them beside the code that needs them. */
+export function destinationFor(scope: Scope, cwd = process.cwd()): string {
+	return scope === 'user'
+		? path.join(os.homedir(), '.agents', 'skills')
+		: path.join(cwd, '.agents', 'skills');
+}
+
+export function skillsSource(): string | undefined {
+	return resolvePackageResource('skills/');
+}
+
+/** Name and description come from the SKILL.md front matter, so there is one source of truth. */
+export function availableSkills(): Skill[] {
+	const root = skillsSource();
+	if (!root) return [];
+	const skills: Skill[] = [];
+	for (const entry of fs.readdirSync(root, {withFileTypes: true})) {
+		if (!entry.isDirectory()) continue;
+		const manifest = path.join(root, entry.name, 'SKILL.md');
+		if (!fs.existsSync(manifest)) continue;
+		const text = fs.readFileSync(manifest, 'utf8');
+		skills.push({
+			name: /^name:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? entry.name,
+			description: /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? '',
+			from: path.join(root, entry.name),
+		});
+	}
+	return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export interface Installed {
+	name: string;
+	to: string;
+	replaced: boolean;
+}
+
+/**
+ * Copies rather than symlinks, so an installed skill survives `node_modules` being deleted.
+ *
+ * The cost is that upgrading the package does not upgrade the installed skill, which is why the
+ * report says `replaced` versus `installed`: a skill that is quietly stale is worse than one you
+ * know you have to refresh.
+ */
+export function installSkills(scope: Scope, cwd = process.cwd()): Installed[] {
+	const destination = destinationFor(scope, cwd);
+	const installed: Installed[] = [];
+	for (const skill of availableSkills()) {
+		const to = path.join(destination, skill.name);
+		const replaced = fs.existsSync(to);
+		if (replaced) fs.rmSync(to, {recursive: true, force: true});
+		fs.mkdirSync(destination, {recursive: true});
+		fs.cpSync(skill.from, to, {recursive: true});
+		installed.push({name: skill.name, to, replaced});
+	}
+	return installed;
+}
+
+export function isInstalled(
+	skill: Skill,
+	scope: Scope,
+	cwd = process.cwd(),
+): boolean {
+	return fs.existsSync(path.join(destinationFor(scope, cwd), skill.name));
+}

package/dist/silence-sqlite-warning.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=silence-sqlite-warning.d.ts.map