codemem 0.44.0-alpha.1 → 0.44.0-beta.1

package/README.md

@@ -7,24 +7,27 @@ This is the published npm package for the `codemem` CLI.
 
 ## Install
 
-**Prerequisites:** Node.js 24.15+ and npm (or pnpm). Native database support
+**Prerequisites:** Node.js 24.15+ and npm. Native database support
 covers macOS x64/arm64, Linux x64/arm64 (glibc 2.34+ or musl), and Windows x64.
 32-bit targets, including Linux armv7, are not supported.
 
 On Linux, skip the unused ONNX Runtime GPU provider download:
 
 ```bash
-env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem @codemem/embeddings
+env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem
 ```
 
 On Apple silicon macOS and Windows:
 
 ```bash
-npm install -g codemem @codemem/embeddings
+npm install -g codemem
 ```
 
-The embedding package enables semantic retrieval. Installing only `codemem` keeps
-the CLI functional with FTS5 keyword retrieval.
+The CLI installs its matching embedding runtime by default. For a smaller
+keyword-only install, use `npm install -g codemem --omit=optional` and set
+`CODEMEM_EMBEDDING_DISABLED=1` in every Codemem process. The flag is required
+because npm also omits sqlite-vec's optional platform package; the CLI then
+remains functional with FTS5.
 
 Intel x64 Macs have no ONNX Runtime 1.24.3 artifact and remain on FTS5 retrieval.
 

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, DeviceIdentityError, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, PROMPT_TRANSPORT_PROTOCOL_RANGE, REF_BACKFILL_JOB, RawEventIngestValidationError, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, TRUSTED_HOOK_MAPPER_OPTIONS, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, arePromptTransportProtocolRangesCompatible, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildBaseUrl, buildDirectPeerAuthHeaders, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, buildViewerIdentityTarget, classifyPromptTransportFailure, clonePromptPackAttempt, collectOperationalStatus, compareMemoryRoleReports, connect, connectReadOnly, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, detectInstallKind, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getAttributionDiagnostics, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getUpdateStatus, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, ingestRawEvents, initDatabase, isEmbeddingDisabled, isStableReleaseVersion, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, normalizePromptTransportProtocolRange, planReplicationOpsAgePrune, probeCodememViewerLiveness, probeCodememViewerLiveness as probeCodememViewerLiveness$1, projectMatchesFilter, promptPackArtifactFingerprint, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, recordPromptPackArtifacts, recordPromptPackTerminal, recordRetrievalSurface, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, resolveRetrievalSession, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripTrailingCommas, syncPassPreflight, tryUpdateRetrievalDelivery, updatePeerAddresses, vacuumDatabase, viewerUrl, writeCodememConfigFile } from "@codemem/core";
+import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, DeviceIdentityError, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, PROMPT_TRANSPORT_PROTOCOL_RANGE, REF_BACKFILL_JOB, RawEventIngestValidationError, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, TRUSTED_HOOK_MAPPER_OPTIONS, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, arePromptTransportProtocolRangesCompatible, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildBaseUrl, buildDirectPeerAuthHeaders, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, buildViewerIdentityTarget, classifyPromptTransportFailure, clonePromptPackAttempt, collectOperationalStatus, compareMemoryRoleReports, connect, connectReadOnly, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, detectInstallKind, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getAttributionDiagnostics, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getUpdateStatus, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, ingestRawEvents, initDatabase, isEmbeddingDisabled, isReleaseVersionForChannel, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, normalizePromptTransportProtocolRange, planReplicationOpsAgePrune, probeCodememViewerLiveness, probeCodememViewerLiveness as probeCodememViewerLiveness$1, probeRequiredNativeRuntime, projectMatchesFilter, promptPackArtifactFingerprint, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, recordPromptPackArtifacts, recordPromptPackTerminal, recordRetrievalSurface, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, resolveRetrievalSession, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripTrailingCommas, syncPassPreflight, tryUpdateRetrievalDelivery, updatePeerAddresses, vacuumDatabase, viewerUrl, writeCodememConfigFile } from "@codemem/core";
 import { Command, Option } from "commander";
 import omelette from "omelette";
 import { randomInt, randomUUID } from "node:crypto";
@@ -4397,7 +4397,7 @@ function startMaintenanceWorkerRuntime(options = {}) {
 		dbPath,
 		signal: options.signal,
 		batchSize: 10,
-		idleIntervalMs: 5e3
+		idleIntervalMs: 6e4
 	}));
 	runners.push(createSequentialBackfillCoordinator(store, [
 		{
@@ -6460,6 +6460,51 @@ function sqliteVecFailureDiagnostics(error, dbPath) {
 		`error=${message}`
 	];
 }
+function requiredNativeRuntimeFailureDiagnostics(error, context = {
+	version: VERSION,
+	nodeVersion: process.version,
+	platform: process.platform,
+	arch: process.arch
+}) {
+	const detail = error instanceof Error ? error.message : String(error);
+	return [
+		"Required SQLite native binding is unavailable.",
+		`Runtime: Node ${context.nodeVersion} on ${context.platform}/${context.arch}.`,
+		`Details: ${detail}`,
+		`Reinstall this exact codemem version: npm install -g codemem@${context.version}`,
+		"Use Node 24.15+ on a supported 64-bit macOS, Linux, or Windows target; see the native install matrix for current platform coverage.",
+		"This required better-sqlite3 failure is separate from optional sqlite-vec loading, which can fall back to lexical search."
+	];
+}
+async function preflightServeNativeRuntime(invocation, dependencies = {
+	isPortOpen,
+	probe: probeRequiredNativeRuntime
+}) {
+	if (invocation.mode === "start" && await dependencies.isPortOpen(invocation.host, invocation.port)) return { state: "already_running" };
+	try {
+		dependencies.probe();
+		return { state: "ready" };
+	} catch (error) {
+		return {
+			state: "unavailable",
+			diagnostics: requiredNativeRuntimeFailureDiagnostics(error)
+		};
+	}
+}
+async function nativeRuntimeAllowsServeStart(invocation) {
+	if (invocation.mode !== "start" && invocation.mode !== "restart") return true;
+	const preflight = await preflightServeNativeRuntime(invocation);
+	if (preflight.state === "already_running") {
+		p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
+		if (!invocation.background) process.exitCode = 1;
+		return false;
+	}
+	if (preflight.state === "ready") return true;
+	p.intro("codemem viewer");
+	for (const line of preflight.diagnostics) p.log.error(line);
+	process.exitCode = 1;
+	return false;
+}
 async function runServeCoordinatorMaintenance(store, dependencies) {
 	const projectShares = await dependencies.advancePendingProjectShares(store, { limit: 3 });
 	const coordinatorEnrollment = await dependencies.reconcileConfiguredCoordinatorEnrollment(store);
@@ -6518,11 +6563,11 @@ async function startForegroundViewer(invocation) {
 	if (invocation.dbPath) process.env.CODEMEM_DB = invocation.dbPath;
 	if (invocation.configPath) process.env.CODEMEM_CONFIG = invocation.configPath;
 	warnIfViewerExposed(invocation.host, invocation.port);
-	if (await isPortOpen(invocation.host, invocation.port)) {
-		p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
-		process.exitCode = 1;
-		return;
-	}
+	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
+	if (!await terminateTrustedMaintenanceWorker(dbPath, {
+		gracefulMs: 1e3,
+		forceMs: 5e3
+	})) p.log.warn("Existing maintenance worker is not trusted or did not stop; starting viewer anyway");
 	const preparedDb = prepareViewerDatabase(invocation.dbPath);
 	const observer = new ObserverClient();
 	let store;
@@ -6543,11 +6588,6 @@ async function startForegroundViewer(invocation) {
 	const config = invocation.configPath ? readCodememConfigFileAtPath(invocation.configPath) : readCodememConfigFile();
 	const syncConfig = readCoordinatorSyncConfig(config);
 	const syncEnabled = syncConfig.syncEnabled;
-	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
-	if (!await terminateTrustedMaintenanceWorker(dbPath, {
-		gracefulMs: 1e3,
-		forceMs: 5e3
-	})) p.log.warn("Existing maintenance worker is not trusted or did not stop; starting viewer anyway");
 	const syncRuntimeStatus = {
 		phase: syncEnabled ? "starting" : "disabled",
 		detail: syncEnabled ? "Waiting for viewer startup to finish" : "Sync is disabled"
@@ -6683,7 +6723,10 @@ async function startForegroundViewer(invocation) {
 		shutdown();
 	});
 }
-async function runServeInvocation(invocation) {
+async function runServeInvocation(invocation, dependencies = {
+	nativeRuntimeAllowsServeStart,
+	stopExistingViewer
+}) {
 	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
 	const runtimeConflict = await findRuntimeViewerConflict(dbPath, {
 		host: invocation.host,
@@ -6696,8 +6739,9 @@ async function runServeInvocation(invocation) {
 		process.exitCode = 1;
 		return;
 	}
+	if (!await dependencies.nativeRuntimeAllowsServeStart(invocation)) return;
 	if (invocation.mode === "stop" || invocation.mode === "restart") {
-		const result = await stopExistingViewer(dbPath, {
+		const result = await dependencies.stopExistingViewer(dbPath, {
 			host: invocation.host,
 			port: invocation.port
 		});
@@ -7337,7 +7381,7 @@ function installCodex(force) {
 	}
 	if (codememOnPath(true)) p.log.info("Codex hooks will call `codemem` directly (found on PATH).");
 	else {
-		const globalInstallCommand = process.platform === "linux" ? "env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem @codemem/embeddings" : "npm install -g codemem @codemem/embeddings";
+		const globalInstallCommand = process.platform === "linux" ? "env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem" : "npm install -g codemem";
 		p.log.info(`\`codemem\` is not on PATH, so Codex hooks will run via \`npx -y --package codemem --package @codemem/embeddings codemem\` (works without a global install). For lower hook latency: ${globalInstallCommand}`);
 	}
 	let ok = true;
@@ -8970,10 +9014,10 @@ function renderStatusWarning(error) {
 function renderHumanStatus(status) {
 	const warning = renderStatusWarning(status.error);
 	if (status.update_available) return `Update available${cacheQualifier(status.stale)}: ${status.current_version} → ${status.latest_version}. ${status.recommended_action}${warning}`;
-	if (!isStableReleaseVersion(status.current_version)) return `Unable to compare current version ${status.current_version} with ${status.latest_version}. ${status.recommended_action}${warning}`;
+	if (!status.channel || !isReleaseVersionForChannel(status.current_version, status.channel)) return `Unable to compare current version ${status.current_version} with ${status.latest_version}. ${status.recommended_action}${warning}`;
 	return `${status.current_version} is up to date${cacheQualifier(status.stale)}.${warning}`;
 }
-var checkCommand = addJsonOption(new Command("check").description("Check for a newer stable codemem release")).addOption(new Option("-r, --refresh", "bypass the six-hour release cache")).configureHelp(helpStyle).action(async (options) => {
+var checkCommand = addJsonOption(new Command("check").description("Check for a newer codemem release on the installed channel")).addOption(new Option("-r, --refresh", "bypass the six-hour release cache")).configureHelp(helpStyle).action(async (options) => {
 	try {
 		const installKind = detectInstallKind({
 			entryPath: process.argv[1] ?? "",
@@ -9037,8 +9081,8 @@ async function installUpdate(options) {
 			return;
 		}
 		const targetVersion = status.latest_version;
-		if (!isStableReleaseVersion(targetVersion)) {
-			failInstall(options, "update_install_refused", "release version is not a stable semantic version");
+		if (!status.channel || !isReleaseVersionForChannel(targetVersion, status.channel)) {
+			failInstall(options, "update_install_refused", "release version does not match the installed channel");
 			return;
 		}
 		releaseInstallLock = await acquireInstallLock();
@@ -9076,7 +9120,7 @@ async function installUpdate(options) {
 		await releaseInstallLock?.();
 	}
 }
-var installCommand = addJsonOption(new Command("install").description("Install an eligible stable codemem update")).configureHelp(helpStyle).action(installUpdate);
+var installCommand = addJsonOption(new Command("install").description("Install an eligible codemem update on the installed channel")).configureHelp(helpStyle).action(installUpdate);
 var updateCommand = new Command("update").description("Inspect and manage codemem updates").enablePositionalOptions().configureHelp(helpStyle).addCommand(checkCommand).addCommand(installCommand);
 //#endregion
 //#region src/commands/version.ts