@ashlr/hub 2.2.0

package/dist/core/integrations/vercel.js

@@ -0,0 +1,192 @@
+/**
+ * core/integrations/vercel.ts — Read-only Vercel project status via the
+ * `vercel` CLI.
+ *
+ * RULES:
+ *  - READ-ONLY. Deploying stays in `ashlr ship` (already --confirm gated).
+ *  - NEVER throws. Every exported function degrades gracefully on any
+ *    failure (CLI absent, not authed, not linked, malformed output).
+ *  - Uses the installed `vercel` CLI — no raw tokens are read, stored,
+ *    logged, or printed.
+ *  - spawnSync only (no shell prevents shell injection).
+ *  - Bounded timeouts so a slow/hung CLI never blocks the caller.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+const VERCEL_BIN = 'vercel';
+const TIMEOUT_MS = 8_000; // ms — vercel ls can be slow on first run
+const MAX_DEPLOYS = 10;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run a vercel sub-command synchronously inside `cwd`.
+ * Returns trimmed stdout or null on any failure. Never throws.
+ */
+function runVercel(args, cwd) {
+    try {
+        const res = spawnSync(VERCEL_BIN, args, {
+            cwd,
+            timeout: TIMEOUT_MS,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                // Suppress interactive prompts and update checks so the CLI
+                // is usable in a non-TTY context.
+                CI: '1',
+                FORCE_COLOR: '0',
+            },
+        });
+        // spawn error (e.g. ENOENT — vercel not on PATH) or non-zero exit → null.
+        if (res.error)
+            return null;
+        if (res.status !== 0)
+            return null;
+        return typeof res.stdout === 'string' ? res.stdout.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true when a `.vercel/project.json` file exists in `cwd`, which
+ * indicates the directory has been linked to a Vercel project.
+ */
+function hasProjectJson(cwd) {
+    return existsSync(join(cwd, '.vercel', 'project.json'));
+}
+// ---------------------------------------------------------------------------
+// JSON parsing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse the JSON emitted by `vercel ls --format json`.
+ *
+ * The modern CLI emits `{ deployments: [...] }`; older shapes emit a bare
+ * array of deployment objects. Each relevant
+ * field is extracted defensively; unknown shapes produce an empty array.
+ */
+function parseDeployList(raw) {
+    const trimmed = raw.trim();
+    // vercel ls --format json wraps the array under a top-level key (or, on
+    // older CLI versions, emits a bare array).
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    // Accept a bare array OR { deployments: [...] } / { data: [...] } wrappers.
+    let items = null;
+    if (Array.isArray(parsed)) {
+        items = parsed;
+    }
+    else if (parsed !== null && typeof parsed === 'object') {
+        const obj = parsed;
+        for (const key of ['deployments', 'data', 'items']) {
+            if (Array.isArray(obj[key])) {
+                items = obj[key];
+                break;
+            }
+        }
+    }
+    if (items === null)
+        return [];
+    const results = [];
+    for (const item of items) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const d = item;
+        // URL — vercel uses "url" or "alias" (first element).
+        let url = '';
+        if (typeof d['url'] === 'string' && d['url'].length > 0) {
+            url = d['url'];
+        }
+        else if (Array.isArray(d['alias']) && typeof d['alias'][0] === 'string') {
+            url = d['alias'][0];
+        }
+        if (!url)
+            continue; // skip entries without a URL
+        // State — various field names depending on vercel CLI version.
+        let state = 'UNKNOWN';
+        for (const key of ['state', 'readyState', 'status']) {
+            if (typeof d[key] === 'string' && d[key].length > 0) {
+                state = d[key].toUpperCase();
+                break;
+            }
+        }
+        // Created timestamp.
+        let createdAt = null;
+        for (const key of ['createdAt', 'created', 'createdTime']) {
+            const val = d[key];
+            if (typeof val === 'string' && val.length > 0) {
+                createdAt = val;
+                break;
+            }
+            if (typeof val === 'number') {
+                createdAt = new Date(val).toISOString();
+                break;
+            }
+        }
+        // Target — "production" | "preview" | null.
+        let target = null;
+        for (const key of ['target', 'meta.githubCommitRef']) {
+            if (typeof d[key] === 'string' && d[key].length > 0) {
+                target = d[key];
+                break;
+            }
+        }
+        results.push({ url, state, createdAt, target });
+        if (results.length >= MAX_DEPLOYS)
+            break;
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read-only linked-project snapshot via the `vercel` CLI.
+ * NEVER throws — degrades to `{ linked: false, latestState: null, url: null }`
+ * on any failure (CLI absent, not authed, not linked, scope prompt, timeout).
+ */
+export function vercelStatus(cwd) {
+    const unlinked = { linked: false, latestState: null, url: null };
+    // Fast-path: check for .vercel/project.json before spawning the CLI.
+    if (!hasProjectJson(cwd))
+        return unlinked;
+    // Attempt `vercel ls --format json` for a live deployment list — take the
+    // first (most recent) entry as the latest status. The modern Vercel CLI uses
+    // `-F, --format json`; the legacy `--json` flag errors with "unknown option".
+    const raw = runVercel(['ls', '--format', 'json'], cwd);
+    if (raw === null)
+        return unlinked;
+    const deploys = parseDeployList(raw);
+    if (deploys.length > 0) {
+        const latest = deploys[0];
+        return {
+            linked: true,
+            latestState: latest.state,
+            url: latest.url,
+        };
+    }
+    // `vercel ls` returned parseable JSON but no deployments — still linked.
+    return { linked: true, latestState: null, url: null };
+}
+/**
+ * List recent deployments for the Vercel project linked to `cwd`.
+ * NEVER throws — returns [] on any failure (CLI absent, not authed, not
+ * linked, malformed output, timeout).
+ */
+export function listDeploys(cwd) {
+    const raw = runVercel(['ls', '--format', 'json'], cwd);
+    if (raw === null)
+        return [];
+    return parseDeployList(raw);
+}
+//# sourceMappingURL=vercel.js.map

package/dist/core/integrations/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.js","sourceRoot":"","sources":["../../../src/core/integrations/vercel.ts"],"names":[],"mappings":"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"}

package/dist/core/knowledge/ask.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ask.ts — Portfolio RAG: retrieve + synthesize answers from the knowledge index.
+ *
+ * INVARIANTS (non-negotiable):
+ *  1. LOCAL-ONLY BY DEFAULT — code/chunks are NEVER sent to a cloud model unless
+ *     opts.allowCloud === true AND a cloud key exists. Any code-to-cloud on the
+ *     default path is a contract violation.
+ *  2. READ-ONLY — this module never modifies any enrolled repo or any file
+ *     outside knowledgeDir().
+ *  3. ENROLLMENT-SCOPED — retrieval is limited to loadChunks() output, which
+ *     itself is scoped to the persisted index (enrolled repos only).
+ *  4. BOUNDED — top-K retrieval is capped; chunk text in the prompt is capped.
+ *  5. NO SECRETS — chunks stored in the index are already scrubbed; we do not
+ *     re-expose them beyond the local synthesis prompt.
+ *  6. NEVER THROWS — degrades gracefully; returns a useful message on any failure.
+ */
+import type { AskResult } from '../types.js';
+/**
+ * Answer `question` using a local RAG pipeline over the persisted knowledge index.
+ *
+ * Retrieval: embedding cosine similarity (local Ollama) when vectors are present,
+ * else keyword/TF-IDF. Synthesis: LOCAL model via getActiveClient (Ollama/LM Studio).
+ *
+ * PRIVACY GUARDRAIL: code chunks are only sent to the local synthesis model by
+ * default. They are sent to a cloud model ONLY when opts.allowCloud === true AND
+ * a cloud key exists (enforced by getActiveClient — it throws otherwise).
+ *
+ * Never throws. Degrades to an informational message when nothing is indexed
+ * or the local model is unreachable.
+ */
+export declare function ask(question: string, opts: {
+    repo?: string;
+    allowCloud: boolean;
+}): Promise<AskResult>;

package/dist/core/knowledge/ask.js

@@ -0,0 +1,325 @@
+/**
+ * ask.ts — Portfolio RAG: retrieve + synthesize answers from the knowledge index.
+ *
+ * INVARIANTS (non-negotiable):
+ *  1. LOCAL-ONLY BY DEFAULT — code/chunks are NEVER sent to a cloud model unless
+ *     opts.allowCloud === true AND a cloud key exists. Any code-to-cloud on the
+ *     default path is a contract violation.
+ *  2. READ-ONLY — this module never modifies any enrolled repo or any file
+ *     outside knowledgeDir().
+ *  3. ENROLLMENT-SCOPED — retrieval is limited to loadChunks() output, which
+ *     itself is scoped to the persisted index (enrolled repos only).
+ *  4. BOUNDED — top-K retrieval is capped; chunk text in the prompt is capped.
+ *  5. NO SECRETS — chunks stored in the index are already scrubbed; we do not
+ *     re-expose them beyond the local synthesis prompt.
+ *  6. NEVER THROWS — degrades gracefully; returns a useful message on any failure.
+ */
+import { loadChunks } from './index.js';
+import { getActiveClient } from '../run/provider-client.js';
+import { loadConfig } from '../config.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Number of top chunks to retrieve for synthesis. */
+const TOP_K = 8;
+/** Max characters of a single chunk to include in the synthesis prompt. */
+const CHUNK_TEXT_CAP = 600;
+/** Max total characters of all chunk context in the synthesis prompt. */
+const CONTEXT_TOTAL_CAP = 6000;
+/** Timeout (ms) for the local Ollama /api/embeddings request. */
+const EMBED_TIMEOUT_MS = 8000;
+// ---------------------------------------------------------------------------
+// Tokenisation (shared pattern with recall.ts — no import to avoid coupling)
+// ---------------------------------------------------------------------------
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1); // drop single-char tokens
+}
+// ---------------------------------------------------------------------------
+// Cosine similarity
+// ---------------------------------------------------------------------------
+function cosine(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ---------------------------------------------------------------------------
+// Keyword / TF-IDF scoring for a chunk
+// ---------------------------------------------------------------------------
+function keywordScoreChunk(query, chunk) {
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0)
+        return 0;
+    // Weight file path tokens slightly (they indicate structural relevance)
+    const fileTokens = tokenize(chunk.file);
+    const textTokens = tokenize(chunk.text);
+    const weightedFreq = new Map();
+    for (const t of fileTokens) {
+        weightedFreq.set(t, (weightedFreq.get(t) ?? 0) + 2);
+    }
+    for (const t of textTokens) {
+        weightedFreq.set(t, (weightedFreq.get(t) ?? 0) + 1);
+    }
+    if (weightedFreq.size === 0)
+        return 0;
+    let hits = 0;
+    for (const term of queryTerms) {
+        hits += weightedFreq.get(term) ?? 0;
+    }
+    return hits === 0 ? 0 : hits / queryTerms.size;
+}
+// ---------------------------------------------------------------------------
+// Local Ollama embedding helpers (best-effort; never throw)
+// ---------------------------------------------------------------------------
+async function detectEmbeddingModel(ollamaBase) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    try {
+        const res = await fetch(`${ollamaBase.replace(/\/+$/, '')}/api/tags`, {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        if (!res.ok)
+            return { available: false };
+        const body = (await res.json());
+        if (typeof body !== 'object' ||
+            body === null ||
+            !Array.isArray(body['models'])) {
+            return { available: false };
+        }
+        const models = body.models;
+        const EMBED_HINTS = ['bge', 'nomic-embed', 'mxbai-embed', 'all-minilm', 'embed'];
+        for (const hint of EMBED_HINTS) {
+            const found = models.find((m) => m.name.toLowerCase().includes(hint));
+            if (found)
+                return { available: true, model: found.name };
+        }
+        return { available: false };
+    }
+    catch {
+        return { available: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function fetchEmbedding(ollamaBase, model, text) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EMBED_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${ollamaBase.replace(/\/+$/, '')}/api/embeddings`, {
+            method: 'POST',
+            signal: controller.signal,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model, prompt: text.slice(0, 2000) }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (typeof body !== 'object' ||
+            body === null ||
+            !Array.isArray(body['embedding'])) {
+            return null;
+        }
+        const embedding = body.embedding;
+        if (!embedding.every((v) => typeof v === 'number'))
+            return null;
+        return embedding;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Retrieve the top-K most relevant chunks from the index for `question`.
+ * Tries embedding cosine similarity first (local Ollama); falls back to
+ * keyword/TF-IDF. Never throws; returns [] on any failure.
+ */
+async function retrieve(question, chunks, ollamaBase) {
+    if (chunks.length === 0)
+        return { hits: [], method: 'keyword' };
+    // --- Attempt embedding retrieval if any chunks have vectors ---
+    const chunksWithVectors = chunks.filter((c) => c.vector && c.vector.length > 0);
+    if (chunksWithVectors.length > 0) {
+        // Try to get a query embedding from local Ollama
+        try {
+            const modelProbe = await detectEmbeddingModel(ollamaBase);
+            if (modelProbe.available) {
+                const queryVec = await fetchEmbedding(ollamaBase, modelProbe.model, question);
+                if (queryVec !== null) {
+                    // Score all chunks that have vectors by cosine; keyword score for the rest
+                    const hits = chunks.map((chunk) => {
+                        if (chunk.vector && chunk.vector.length > 0) {
+                            return {
+                                chunk,
+                                score: cosine(queryVec, chunk.vector),
+                                method: 'embedding',
+                            };
+                        }
+                        return {
+                            chunk,
+                            score: keywordScoreChunk(question, chunk),
+                            method: 'keyword',
+                        };
+                    });
+                    hits.sort((a, b) => b.score - a.score);
+                    return { hits: hits.slice(0, TOP_K), method: 'embedding' };
+                }
+            }
+        }
+        catch {
+            // Fall through to keyword
+        }
+    }
+    // --- Keyword / TF-IDF fallback ---
+    const hits = chunks.map((chunk) => ({
+        chunk,
+        score: keywordScoreChunk(question, chunk),
+        method: 'keyword',
+    }));
+    hits.sort((a, b) => b.score - a.score);
+    return { hits: hits.slice(0, TOP_K), method: 'keyword' };
+}
+// ---------------------------------------------------------------------------
+// Prompt construction
+// ---------------------------------------------------------------------------
+function buildPrompt(question, hits) {
+    if (hits.length === 0) {
+        return `Answer the following question as best you can. No source context is available.\n\nQuestion: ${question}`;
+    }
+    const contextParts = [];
+    let totalChars = 0;
+    for (const hit of hits) {
+        const { chunk } = hit;
+        const header = `[${chunk.repo}] ${chunk.file}:${chunk.startLine}-${chunk.endLine}`;
+        const body = chunk.text.slice(0, CHUNK_TEXT_CAP);
+        const entry = `${header}\n${body}`;
+        if (totalChars + entry.length > CONTEXT_TOTAL_CAP)
+            break;
+        contextParts.push(entry);
+        totalChars += entry.length;
+    }
+    return [
+        'You are a software assistant with access to source code excerpts from an enrolled code portfolio.',
+        'Answer the question using only the provided context. Cite the source (repo, file, line) for each claim.',
+        'If the context does not contain enough information, say so clearly.',
+        '',
+        '--- SOURCE CONTEXT ---',
+        contextParts.join('\n\n---\n'),
+        '--- END CONTEXT ---',
+        '',
+        `Question: ${question}`,
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Answer `question` using a local RAG pipeline over the persisted knowledge index.
+ *
+ * Retrieval: embedding cosine similarity (local Ollama) when vectors are present,
+ * else keyword/TF-IDF. Synthesis: LOCAL model via getActiveClient (Ollama/LM Studio).
+ *
+ * PRIVACY GUARDRAIL: code chunks are only sent to the local synthesis model by
+ * default. They are sent to a cloud model ONLY when opts.allowCloud === true AND
+ * a cloud key exists (enforced by getActiveClient — it throws otherwise).
+ *
+ * Never throws. Degrades to an informational message when nothing is indexed
+ * or the local model is unreachable.
+ */
+export async function ask(question, opts) {
+    const noKnowledge = (reason) => ({
+        question,
+        answer: reason,
+        sources: [],
+        method: 'keyword',
+        local: true,
+    });
+    // --- Load chunks from the persisted index ---
+    let chunks;
+    try {
+        chunks = loadChunks(opts.repo);
+    }
+    catch {
+        return noKnowledge('No knowledge indexed — run `ashlr knowledge build` to index enrolled repos.');
+    }
+    if (chunks.length === 0) {
+        const scope = opts.repo ? ` for repo ${opts.repo}` : '';
+        return noKnowledge(`No knowledge indexed${scope} — run \`ashlr knowledge build\` to index enrolled repos.`);
+    }
+    // --- Load config (synchronous) for Ollama base URL and provider client ---
+    let cfg;
+    try {
+        cfg = loadConfig();
+    }
+    catch {
+        return noKnowledge('Could not load ashlr config — run `ashlr` once to initialize.');
+    }
+    const ollamaBase = (cfg.models?.ollama ?? 'http://localhost:11434').replace(/\/+$/, '');
+    // --- Retrieve top-K relevant chunks ---
+    let hits;
+    let method;
+    try {
+        ({ hits, method } = await retrieve(question, chunks, ollamaBase));
+    }
+    catch {
+        hits = [];
+        method = 'keyword';
+    }
+    // --- Build cited sources from retrieved hits ---
+    const sources = hits.map((h) => ({
+        repo: h.chunk.repo,
+        file: h.chunk.file,
+        line: h.chunk.startLine,
+    }));
+    // --- Synthesize answer via local model ---
+    // PRIVACY: getActiveClient enforces LOCAL-ONLY by default.
+    // allowCloud is forwarded verbatim — the client will throw if cloud is
+    // selected without --allow-cloud, providing a clear error message.
+    const prompt = buildPrompt(question, hits);
+    let answer;
+    let isLocal = true;
+    try {
+        const client = await getActiveClient(cfg, { allowCloud: opts.allowCloud });
+        // ALLOWLIST (not denylist): treat ONLY the known local providers as local.
+        // Any unknown/new provider id (e.g. a future 'bedrock'/'vertex') defaults to
+        // local:false (cloud) so it correctly triggers the cloud warning rather than
+        // being silently mislabeled as local.
+        isLocal = client.id === 'ollama' || client.id === 'lmstudio';
+        const result = await client.chat([
+            { role: 'user', content: prompt },
+        ]);
+        answer = result.content.trim();
+        if (!answer) {
+            answer = 'The local model returned an empty response. Ensure Ollama is running with a chat model loaded.';
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Surface the local-first refusal clearly so the user knows what to do
+        answer = `Could not synthesize an answer: ${msg}`;
+        // If the error is a local-first refusal (no cloud without --allow-cloud),
+        // treat it as a local attempt (the synthesis just failed)
+        isLocal = true;
+    }
+    return {
+        question,
+        answer,
+        sources,
+        method,
+        local: isLocal,
+    };
+}
+//# sourceMappingURL=ask.js.map

package/dist/core/knowledge/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../../src/core/knowledge/ask.ts"],"names":[],"mappings":"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"}

package/dist/core/knowledge/graph.d.ts

@@ -0,0 +1,51 @@
+/**
+ * graph.ts — Knowledge Graph + Impact analysis for enrolled repos.
+ *
+ * INVARIANTS (docs/contracts/CONTRACT-M25.md):
+ *  1. READ-ONLY: never modifies any enrolled repo; analysis only.
+ *  2. ENROLLMENT-SCOPED: default repos = listEnrolled() (DEFAULT EMPTY => empty graph).
+ *  3. BOUNDED: caps file walk depth, file count, and skips node_modules/.git/dist/binaries.
+ *  4. NEVER THROWS: all functions catch internally; callers get empty structures on error.
+ *  5. LOCAL-ONLY: no network calls; pure filesystem analysis.
+ *  6. NO SECRETS: skips .env/key files; does not emit secret-shaped content.
+ *
+ * buildGraph(repos?): construct KnowledgeGraph from persisted index + package.json manifests
+ *   + import/require statements. Nodes: repos, key modules, shared deps.
+ *   Edges: imports/depends/shared-dep. CrossRepo: same dep across repos, duplicated modules.
+ *
+ * impact(target, repos?): find all references to a file path or symbol across enrolled repos
+ *   via the persisted index + grep-style scan. Returns ImpactResult with references + dependents.
+ */
+import type { KnowledgeGraph, ImpactResult } from '../types.js';
+/**
+ * Build a KnowledgeGraph from enrolled repos (or the provided list).
+ *
+ * Nodes:
+ *   - kind:'repo'    — each enrolled repo
+ *   - kind:'module'  — key source files within a repo (those that import packages)
+ *   - kind:'dep'     — external dependencies (package names)
+ *
+ * Edges:
+ *   - kind:'depends'   — repo -> dep (from package.json)
+ *   - kind:'imports'   — module -> dep (from import statements)
+ *   - kind:'shared-dep' — dep -> dep node (already in graph; used for cross-repo detection)
+ *
+ * CrossRepo:
+ *   - kind:'shared-dep' when a dep appears in 2+ repos
+ *   - kind:'duplicate-module' when the same relative module path exists in 2+ repos
+ *
+ * BOUNDED, READ-ONLY, NEVER THROWS.
+ */
+export declare function buildGraph(repos?: string[]): KnowledgeGraph;
+/**
+ * Find all references to a file path or symbol across enrolled repos.
+ *
+ * For a file target: searches for import/require of that file (by basename and
+ * relative paths) and any text occurrence of the path.
+ * For a symbol target (no path separators, no extension): searches for usage
+ * occurrences in source files via text scan.
+ *
+ * Returns references (repo/file:line) and a list of dependent module names.
+ * BOUNDED (MAX_REFERENCES cap). READ-ONLY. NEVER THROWS.
+ */
+export declare function impact(target: string, repos?: string[]): ImpactResult;