@dotdotgod/cli 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -29,7 +29,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@huggingface/transformers": "^4.2.0",
     "leiden-ts": "^0.1.0"
   },
   "homepage": "https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli#readme",

package/src/cli/usage.mjs

@@ -36,6 +36,14 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod query <root> <query> [--limit n] [--json]
 
 Search shared project documentation with the resolved local or remote embedding provider.`;
+    case 'embedding':
+      return `Usage:
+  dotdotgod embedding status [<root>] [--json]
+  dotdotgod embedding install [<root>] --confirm [--json]`;
+    case 'embedding status':
+      return `Usage:\n  dotdotgod embedding status [<root>] [--json]\n\nInspect the optional persistent local embedding runtime without network access.`;
+    case 'embedding install':
+      return `Usage:\n  dotdotgod embedding install [<root>] --confirm [--json]\n\nAfter user approval, install the fixed optional runtime persistently. Uses network access and dependency install scripts; the model may download on first query.`;
     case 'map':
       return `Usage:
   dotdotgod map <root> [--depth <positive-integer>] [--json]
@@ -78,6 +86,7 @@ Commands:
   init                  Initialize project memory files.
   config                Inspect or initialize project configuration.
   query                 Search project documentation.
+  embedding             Inspect or install the optional local embedding runtime.
   map                   Render the project documentation map.
   resolve               Resolve a project reference.
   expand                Expand references in a prompt.
@@ -137,6 +146,7 @@ export function helpCommandFromArgs(args) {
   if (nonHelp[0] === 'graph' && nonHelp[1]) return `graph ${nonHelp[1]}`;
   if (nonHelp[0] === 'traceability' && nonHelp[1]) return `traceability ${nonHelp[1]}`;
   if (nonHelp[0] === 'config' && nonHelp[1] === 'init') return 'config init';
+  if (nonHelp[0] === 'embedding' && nonHelp[1]) return `embedding ${nonHelp[1]}`;
   return nonHelp[0] ?? 'root';
 }
 

package/src/commands/embedding.mjs

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { usage } from '../cli/usage.mjs';
+import { resolveEmbeddingProfile } from '../query/embedding-config.mjs';
+import { embeddingRuntimeStatus, installEmbeddingRuntime } from '../query/embedding-runtime.mjs';
+
+function parse(argv) {
+  const [action = 'status', ...rest] = argv;
+  let root = '.'; let json = false; let confirm = false;
+  for (const arg of rest) {
+    if (arg === '--json') json = true;
+    else if (arg === '--confirm') confirm = true;
+    else if (!arg.startsWith('-') && root === '.') root = arg;
+    else usage(`Unknown embedding option: ${arg}`, `embedding ${action}`);
+  }
+  return { action, root: resolve(root), json, confirm };
+}
+
+export function runEmbedding(argv, options = {}) {
+  const parsed = parse(argv);
+  if (!['status', 'install'].includes(parsed.action)) usage(`Unknown embedding command: ${parsed.action}`, 'embedding');
+  const resolved = resolveEmbeddingProfile(parsed.root, options);
+  if (resolved.profile.provider !== 'local') {
+    const result = { ok: true, command: `embedding ${parsed.action}`, provider: resolved.profile.provider, required: false, installed: false, installAvailable: false };
+    console.log(parsed.json ? JSON.stringify(result, null, 2) : 'Local embedding runtime is not required for the configured remote provider.');
+    return result;
+  }
+  if (parsed.action === 'install' && !parsed.confirm) usage('embedding install requires --confirm after user approval.', 'embedding install');
+  const runtimeOptions = { home: options.home };
+  const result = parsed.action === 'status' ? embeddingRuntimeStatus(runtimeOptions) : installEmbeddingRuntime({ ...runtimeOptions, confirm: true, spawnImpl: options.spawnImpl, npmCommand: options.npmCommand });
+  const payload = { ...result, command: `embedding ${parsed.action}`, provider: 'local', required: true, ...(parsed.action === 'install' ? { disclosure: 'Installation uses network access and dependency install scripts; the configured model may download on first query.' } : {}) };
+  console.log(parsed.json ? JSON.stringify(payload, null, 2) : payload.installed ? `Embedding runtime installed (${payload.packageVersion}).` : 'Embedding runtime is not installed.');
+  return payload;
+}

package/src/core.mjs

@@ -4,6 +4,7 @@ import { runValidate } from './validate/run.mjs';
 import { runIndex, runStatus } from './index/cache.mjs';
 import { runConfig } from './commands/config.mjs';
 import { runQuery } from './commands/query.mjs';
+import { runEmbedding } from './commands/embedding.mjs';
 import { runMap } from './commands/map.mjs';
 import { runResolve, runExpand } from './reference/resolve.mjs';
 import { runTraceability } from './commands/traceability.mjs';
@@ -33,6 +34,8 @@ export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOu
 export { runConfig } from './commands/config.mjs';
 export { runMap } from './commands/map.mjs';
 export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, rankVectorFiles, runQuery } from './commands/query.mjs';
+export { runEmbedding } from './commands/embedding.mjs';
+export { EmbeddingRuntimeMissingError, embeddingRuntimeRoot, embeddingRuntimeStatus, installEmbeddingRuntime, resolvePersistentTransformers } from './query/embedding-runtime.mjs';
 export { chunkMarkdown, collectDocumentationChunks, collectDocumentationMarkdown, textFingerprint } from './query/chunks.mjs';
 export { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, VECTOR_SCHEMA_VERSION, profileFingerprint, vectorCachePaths, writeVectorCache } from './query/store.mjs';
 export { DEFAULT_EMBEDDING_PROFILE, EMBEDDING_PROVIDERS, embeddingProfileIdentity, resolveEmbeddingProfile, sanitizeEmbeddingProfile, validateEmbeddingProfile } from './query/embedding-config.mjs';
@@ -54,6 +57,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'config') runConfig(args);
   else if (command === 'status') runStatus(args);
   else if (command === 'query') await runQuery(args);
+  else if (command === 'embedding') runEmbedding(args);
   else if (command === 'map') runMap(args);
   else if (command === 'resolve') runResolve(args);
   else if (command === 'expand') runExpand(args);

package/src/query/embedder.mjs

@@ -1,4 +1,5 @@
 import { embeddingProfileIdentity, resolveEmbeddingProfile } from './embedding-config.mjs';
+import { importTransformers } from './embedding-runtime.mjs';
 
 const localPipelines = new Map();
 
@@ -11,7 +12,7 @@ function normalize(row) {
 
 async function localEmbedder(profile) {
   if (!localPipelines.has(profile.model)) {
-    localPipelines.set(profile.model, import('@huggingface/transformers').then(async ({ env, pipeline }) => {
+    localPipelines.set(profile.model, importTransformers().then(async ({ env, pipeline }) => {
       env.allowLocalModels = true;
       return pipeline('feature-extraction', profile.model);
     }));

package/src/query/embedding-runtime.mjs

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const EMBEDDING_RUNTIME_PACKAGE = '@huggingface/transformers';
+export const EMBEDDING_RUNTIME_VERSION = '4.2.0';
+
+export class EmbeddingRuntimeMissingError extends Error {
+  constructor() { super('Optional local embedding runtime is not installed.'); this.name = 'EmbeddingRuntimeMissingError'; this.code = 'EMBEDDING_RUNTIME_MISSING'; }
+}
+
+export function embeddingRuntimeRoot(options = {}) { return join(options.home ?? homedir(), '.dotdotgod', 'runtime', 'embedding'); }
+
+export function resolvePersistentTransformers(options = {}) {
+  const root = embeddingRuntimeRoot(options);
+  try {
+    const require = createRequire(join(root, 'package.json'));
+    return require.resolve(EMBEDDING_RUNTIME_PACKAGE);
+  } catch { throw new EmbeddingRuntimeMissingError(); }
+}
+
+export function embeddingRuntimeStatus(options = {}) {
+  const root = embeddingRuntimeRoot(options);
+  try {
+    const require = createRequire(join(root, 'package.json'));
+    const packagePath = require.resolve(`${EMBEDDING_RUNTIME_PACKAGE}/package.json`);
+    const version = JSON.parse(readFileSync(packagePath, 'utf8')).version;
+    return { ok: true, installed: true, installAvailable: true, package: EMBEDDING_RUNTIME_PACKAGE, requiredVersion: EMBEDDING_RUNTIME_VERSION, packageVersion: version, location: root };
+  } catch {
+    return { ok: true, installed: false, installAvailable: true, package: EMBEDDING_RUNTIME_PACKAGE, requiredVersion: EMBEDDING_RUNTIME_VERSION, packageVersion: null, location: root };
+  }
+}
+
+export function installEmbeddingRuntime(options = {}) {
+  if (options.confirm !== true) throw new Error('Embedding runtime installation requires explicit confirmation.');
+  const root = embeddingRuntimeRoot(options);
+  const lock = join(root, '.installing');
+  if (existsSync(lock)) throw new Error('Embedding runtime installation is already in progress.');
+  mkdirSync(root, { recursive: true });
+  writeFileSync(lock, `${process.pid}\n`, { flag: 'wx' });
+  try {
+    const spawn = options.spawnImpl ?? spawnSync;
+    const result = spawn(options.npmCommand ?? 'npm', ['install', '--prefix', root, '--save-exact', '--omit=dev', '--no-audit', '--no-fund', `${EMBEDDING_RUNTIME_PACKAGE}@${EMBEDDING_RUNTIME_VERSION}`], { encoding: 'utf8', timeout: options.timeoutMs ?? 300_000, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (result.error || result.status !== 0) throw new Error(result.error?.code === 'ENOENT' ? 'npm is unavailable.' : 'Embedding runtime installation failed.');
+    const status = embeddingRuntimeStatus({ home: options.home });
+    if (!status.installed) throw new Error('Embedding runtime installation could not be verified.');
+    return { ...status, command: 'embedding install', modelDownloadPending: true };
+  } finally { rmSync(lock, { force: true }); }
+}
+
+export async function importTransformers(options = {}) {
+  try { return await import(EMBEDDING_RUNTIME_PACKAGE); }
+  catch (error) {
+    if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+    const path = resolvePersistentTransformers(options);
+    return import(pathToFileURL(path).href);
+  }
+}