kodingo-cli 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# kodingo-cli
+
+## Purpose
+
+This repository contains the Kodingo command-line interface.
+
+The CLI acts as a local adapter between a developer’s environment and the Kodingo core engine.
+
+It is responsible for observing, normalizing, and forwarding signals —
+not interpreting them.
+
+---
+
+## What This Repo Owns
+
+- CLI commands and UX
+- Local project initialization
+- Project scoping and isolation
+- Authentication and authorization flow
+- Event emission to kodingo-core
+- Local configuration and credentials
+
+---
+
+## What This Repo Does NOT Do
+
+- No decision inference
+- No memory interpretation
+- No confidence calculation
+- No domain logic
+
+---
+
+## Design Constraints
+
+- The CLI must be safe to run locally
+- It must never leak data across projects
+- It must respect paid vs unpaid project boundaries
+- All intelligence lives elsewhere
+
+---
+
+## Dependencies
+
+- Depends on `kodingo-core`
+- Depends on `kodingo-schema`
+
+---
+
+## Security Model
+
+- Projects are explicitly initialized
+- Access is opt-in per project
+- Local identity is scoped per project directory
+
+---
+
+## Status
+
+Interface design phase.
+
+---
+
+## Local DB Setup
+
+### 1) Run Postgres locally
+
+Use Docker:
+
+```bash
+docker run --name kodingo-postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=kodingo -p 5432:5432 -d postgres:16
+```
+
+Ensure `psql` is available in your PATH (it ships with Postgres client tools).
+
+### 2) Configure environment
+
+Create a `.env` file (or export in shell):
+
+```bash
+export DATABASE_URL=postgres://postgres:postgres@localhost:5432/kodingo
+```
+
+### 3) Build and run the CLI
+
+```bash
+npm ci
+npm run build
+node src/cli.js capture --type decision --title "Chosen DB" --content "We chose Postgres for persistence." --tags "architecture,db"
+node src/cli.js query-memory "Postgres" --limit 5
+```

package/dist/adapters/agent-adapter/agent-connector.js

@@ -0,0 +1 @@
+"use strict";

package/dist/adapters/ai/inference.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferDecisionSummary = inferDecisionSummary;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+async function inferDecisionSummary(input) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        return buildFallback(input);
+    }
+    try {
+        const client = new sdk_1.default({ apiKey });
+        const prompt = [
+            "You are a senior software engineer reviewing a code change.",
+            "Your job is to interpret what this change represents as a decision or evolution in the codebase.",
+            "",
+            "Write 2 to 4 sentences of plain prose. No markdown, no bullet points, no headers.",
+            "Focus on intent and reasoning, not on describing the diff mechanically.",
+            "Treat the commit message as a low-trust hint only, not as truth.",
+            "Use the symbol and file paths to understand what part of the system changed.",
+            "If intent cannot be confidently inferred, say so honestly in plain English.",
+            "",
+            `Repository: ${input.repoName}`,
+            `Symbol: ${input.symbol}`,
+            `Changed files: ${input.changedFiles.join(", ")}`,
+            `Commit message (low-trust hint): ${input.commitMessage}`,
+            "",
+            "Diff:",
+            input.diff.slice(0, 8000),
+        ].join("\n");
+        const response = await client.messages.create({
+            model: "claude-opus-4-5",
+            max_tokens: 300,
+            messages: [{ role: "user", content: prompt }],
+        });
+        const textBlock = response.content.find((b) => b.type === "text");
+        if (textBlock && textBlock.type === "text") {
+            return textBlock.text.trim();
+        }
+        return buildFallback(input);
+    }
+    catch {
+        return buildFallback(input);
+    }
+}
+function buildFallback(input) {
+    const shortHash = extractShortHash(input.diff);
+    return `Changes to ${input.symbol} across ${input.changedFiles.length} file(s)${shortHash ? ` in commit ${shortHash}` : ""}. Commit message: ${input.commitMessage}.`;
+}
+function extractShortHash(diff) {
+    const match = diff.match(/^commit ([a-f0-9]{7,})/m);
+    return match ? match[1].slice(0, 8) : "";
+}

package/dist/adapters/cloud-adapter/cloud-persistence.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Cloud persistence adapter for kodingo-cli.
+ * Drop-in replacement for memory-persistence.ts — same function signatures,
+ * same return types, but talks to kodingo-api over HTTP instead of psql.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initDb = initDb;
+exports.checkDatabaseConnection = checkDatabaseConnection;
+exports.saveMemory = saveMemory;
+exports.getMemoryById = getMemoryById;
+exports.updateMemoryLifecycle = updateMemoryLifecycle;
+exports.updateMemoryConfidence = updateMemoryConfidence;
+exports.applySignalToMemory = applySignalToMemory;
+exports.suppressProposedSiblings = suppressProposedSiblings;
+exports.getMemoryByExternalId = getMemoryByExternalId;
+exports.getProposedOrIgnoredRecordBySymbol = getProposedOrIgnoredRecordBySymbol;
+exports.deleteMemoryById = deleteMemoryById;
+exports.queryMemory = queryMemory;
+exports.queryMemoryBySymbol = queryMemoryBySymbol;
+function getConfig() {
+    const apiUrl = process.env.KODINGO_API_URL;
+    const token = process.env.KODINGO_API_TOKEN;
+    if (!apiUrl)
+        throw new Error("KODINGO_API_URL is not set");
+    if (!token)
+        throw new Error("KODINGO_API_TOKEN is not set");
+    return { apiUrl: apiUrl.replace(/\/$/, ""), token };
+}
+// ── HTTP client ───────────────────────────────────────────────────────────────
+async function apiFetch(path, options = {}) {
+    const { apiUrl, token } = getConfig();
+    const res = await fetch(`${apiUrl}${path}`, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            "X-Kodingo-Token": token,
+            ...(options.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`kodingo-api error ${res.status}: ${body}`);
+    }
+    // 204 No Content
+    if (res.status === 204)
+        return undefined;
+    return res.json();
+}
+// ── Response → AdapterMemoryRecord mapper ─────────────────────────────────────
+// The API returns camelCase JSON. Dates arrive as strings and are converted.
+// Adapter-layer fields (externalId, correctsId, correctedById) are passed
+// through so commands can display them without reaching back to the API.
+function mapApiRecord(r) {
+    const record = {
+        id: r.id,
+        projectId: r.projectId,
+        repo: r.repo ?? "",
+        type: r.type,
+        content: r.content,
+        tags: r.tags ?? [],
+        status: r.status,
+        confidence: r.confidence,
+        evidence: {
+            strongCodeChangeCount: r.evidence?.strongCodeChangeCount ?? 0,
+            structuralCount: r.evidence?.structuralCount ?? 0,
+            metadataCount: r.evidence?.metadataCount ?? 0,
+            evidenceGain: r.evidence?.evidenceGain ?? 0,
+        },
+        createdAt: new Date(r.createdAt),
+        updatedAt: new Date(r.updatedAt),
+        // Adapter-layer fields — not on core MemoryRecord but present in API responses
+        externalId: r.externalId ?? null,
+        correctsId: r.correctsId ?? null,
+        correctedById: r.correctedById ?? null,
+    };
+    // Optional core fields — only set if present (exactOptionalPropertyTypes)
+    if (r.title)
+        record.title = r.title;
+    if (r.symbol)
+        record.symbol = r.symbol;
+    if (r.fingerprint)
+        record.fingerprint = r.fingerprint;
+    if (r.deniedAt)
+        record.deniedAt = new Date(r.deniedAt);
+    return record;
+}
+// ── Public API (mirrors memory-persistence.ts) ────────────────────────────────
+/**
+ * No-op for cloud mode — schema is managed by kodingo-api.
+ */
+async function initDb() {
+    // Cloud: schema is managed server-side, nothing to do locally.
+}
+/**
+ * Ping the API health endpoint to verify connectivity.
+ */
+async function checkDatabaseConnection() {
+    const { apiUrl } = getConfig();
+    const res = await fetch(`${apiUrl}/health`);
+    if (!res.ok)
+        throw new Error(`kodingo-api health check failed: ${res.status}`);
+}
+/**
+ * Save a new memory record.
+ */
+async function saveMemory(input) {
+    const body = {
+        type: input.type,
+        content: input.content,
+        status: input.status ?? "proposed",
+        confidence: input.confidence ?? 0.3,
+        tags: input.tags ?? [],
+    };
+    if (input.title)
+        body.title = input.title;
+    if (input.repoPath)
+        body.repo = input.repoPath;
+    if (input.symbol)
+        body.symbol = input.symbol;
+    if (input.externalId)
+        body.externalId = input.externalId;
+    if (input.correctsId)
+        body.correctsId = input.correctsId;
+    if (input.correctedById)
+        body.correctedById = input.correctedById;
+    const record = await apiFetch("/memory", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return mapApiRecord(record);
+}
+/**
+ * Get a memory record by ID.
+ */
+async function getMemoryById(id) {
+    try {
+        const record = await apiFetch(`/memory/${id}`);
+        return mapApiRecord(record);
+    }
+    catch (err) {
+        if (err.message?.includes("404"))
+            return null;
+        throw err;
+    }
+}
+/**
+ * Update lifecycle fields (status, confidence, correctedById).
+ */
+async function updateMemoryLifecycle(params) {
+    const body = {
+        status: params.status,
+        confidence: params.confidence,
+    };
+    if (params.correctedById)
+        body.correctedById = params.correctedById;
+    const record = await apiFetch(`/memory/${params.id}`, {
+        method: "PATCH",
+        body: JSON.stringify(body),
+    });
+    return mapApiRecord(record);
+}
+/**
+ * Update only the confidence of a memory record (signal accumulation).
+ */
+async function updateMemoryConfidence(params) {
+    const record = await apiFetch(`/memory/${params.id}/confidence`, {
+        method: "PATCH",
+        body: JSON.stringify({ confidence: params.confidence }),
+    });
+    return mapApiRecord(record);
+}
+/**
+ * Apply a signal weight class to a memory record (uses applySignal domain rules server-side).
+ */
+async function applySignalToMemory(params) {
+    const record = await apiFetch(`/memory/${params.id}/evidence`, {
+        method: "PATCH",
+        body: JSON.stringify({ weightClass: params.weightClass }),
+    });
+    return mapApiRecord(record);
+}
+/**
+ * Suppress stale proposed siblings for a symbol after affirmation.
+ */
+async function suppressProposedSiblings(params) {
+    const body = {
+        symbol: params.symbol,
+        excludeId: params.excludeId,
+    };
+    if (params.repoPath)
+        body.repo = params.repoPath;
+    const res = await apiFetch("/memory/suppress-siblings", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return res.suppressed;
+}
+/**
+ * Look up a memory record by externalId, scoped to a repo.
+ */
+async function getMemoryByExternalId(externalId, repoPath) {
+    const params = new URLSearchParams({ externalId, repo: repoPath });
+    const res = await apiFetch(`/memory?${params.toString()}`);
+    const record = res.data?.[0];
+    if (!record)
+        return null;
+    return mapApiRecord(record);
+}
+/**
+ * Find the best proposed or ignored record for a symbol in a repo.
+ */
+async function getProposedOrIgnoredRecordBySymbol(params) {
+    const qs = new URLSearchParams({
+        symbol: params.symbol,
+        repo: params.repoPath,
+    });
+    const [proposed, ignored] = await Promise.all([
+        apiFetch(`/memory?${qs}&status=proposed&limit=1`),
+        apiFetch(`/memory?${qs}&status=ignored&limit=1`),
+    ]);
+    const candidates = [...(proposed.data ?? []), ...(ignored.data ?? [])].map(mapApiRecord);
+    if (candidates.length === 0)
+        return null;
+    return candidates.sort((a, b) => {
+        if (a.status === "proposed" && b.status !== "proposed")
+            return -1;
+        if (b.status === "proposed" && a.status !== "proposed")
+            return 1;
+        return b.confidence - a.confidence;
+    })[0];
+}
+/**
+ * Delete a memory record by ID.
+ */
+async function deleteMemoryById(id) {
+    await apiFetch(`/memory/${id}`, { method: "DELETE" });
+}
+/**
+ * Text query — full-text search via the API.
+ */
+async function queryMemory(text, limit = 10, repoPath, opts = {}) {
+    const qs = new URLSearchParams({ limit: String(limit) });
+    if (repoPath)
+        qs.set("repo", repoPath);
+    if (!opts.includeNonCanonical)
+        qs.set("status", "proposed");
+    // Use server-side FTS when text is provided
+    const term = text.trim();
+    if (term)
+        qs.set("q", term);
+    const res = await apiFetch(`/memory?${qs.toString()}`);
+    let records = (res.data ?? []).map(mapApiRecord);
+    if (opts.dedupeBySymbol) {
+        const seen = new Set();
+        records = records.filter((r) => {
+            const key = r.symbol ?? r.id;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+    return records.slice(0, limit);
+}
+/**
+ * Symbol query with canonical preference.
+ */
+async function queryMemoryBySymbol(params) {
+    const qs = new URLSearchParams({
+        symbol: params.symbol,
+        limit: String(params.limit ?? 10),
+    });
+    if (params.repoPath)
+        qs.set("repo", params.repoPath);
+    if (params.onlyCanonical)
+        qs.set("status", "affirmed");
+    const res = await apiFetch(`/memory?${qs.toString()}`);
+    let records = (res.data ?? []).map(mapApiRecord);
+    if (!params.includeDenied && !params.onlyCanonical) {
+        records = records.filter((r) => r.status !== "denied");
+    }
+    return records.sort((a, b) => {
+        if (a.status === "affirmed" && b.status !== "affirmed")
+            return -1;
+        if (b.status === "affirmed" && a.status !== "affirmed")
+            return 1;
+        return b.confidence - a.confidence;
+    });
+}