npm - @kaddo/cli - Versions diffs - 3.73.0 → 3.74.1 - Mend

@kaddo/cli 3.73.0 → 3.74.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/admin-dist/assets/{index-CiJRX9Ps.js → index-AAaxSvT4.js} +20 -20
package/dist/admin-dist/index.html +1 -1
package/dist/admin-server/index.js +344 -2
package/dist/core.js +357 -6
package/package.json +1 -1

package/dist/admin-dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>admin</title>
-    <script type="module" crossorigin src="/assets/index-CiJRX9Ps.js"></script>
+    <script type="module" crossorigin src="/assets/index-AAaxSvT4.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BPt-9--k.css">
   </head>
   <body>

package/dist/admin-server/index.js CHANGED Viewed

@@ -66,6 +66,7 @@ import {
   getWorkItemForEdit as coreGetWorkItemForEdit,
   validateWorkItem as coreValidateWorkItem,
   transitionWorkItem as coreTransitionWorkItem,
+  getWorkItemCaptureDefinition as coreGetCaptureDefinition,
   WorkItemWriteError,
   exists,
   join,
@@ -129,9 +130,12 @@ function mapWriteError(err) {
   if (err instanceof WorkItemWriteError) throw new CoreError(err.code, err.message);
   throw err;
 }
+function getCaptureDefinition() {
+  return coreGetCaptureDefinition();
+}
 function createWorkItemAdmin(dir, body) {
   try {
-    const res = coreCreateWorkItem(dir, { intent: body.intent, type: body.type });
+    const res = coreCreateWorkItem(dir, { intent: body.intent, type: body.type, answers: body.answers });
     return { id: res.id, path: res.path, revision: res.revision, status: "draft" };
   } catch (err) {
     mapWriteError(err);
@@ -553,6 +557,19 @@ var WorkItemWriteResultSchema = z.object({
   revision: z.string(),
   status: z.string().optional()
 });
+var WorkItemCreateWithAnswersSchema = z.object({
+  intent: z.string().min(1),
+  type: z.string().min(1),
+  answers: z.record(z.string(), z.string()).optional()
+});
+var RefinementFeedbackSchema = z.object({
+  refinementId: z.string().min(1),
+  feedback: z.string().min(1)
+});
+var RefinementApplySchema = z.object({
+  refinementId: z.string().min(1),
+  expectedRevision: z.string().min(1)
+});
 var ErrorResponseSchema = z.object({
   error: z.object({
     code: z.string(),
@@ -560,11 +577,303 @@ var ErrorResponseSchema = z.object({
   })
 });
+// src/refinement/service.ts
+import crypto from "crypto";
+import {
+  assembleRefinementContext,
+  getWorkItemAgentAssets,
+  normalizeAndValidateProposal,
+  applyRefinement,
+  WorkItemWriteError as WorkItemWriteError2
+} from "@kaddo/cli/core";
+// src/refinement/provider.ts
+var RefinementProviderError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RefinementProviderError";
+    this.code = code;
+  }
+};
+// src/refinement/service.ts
+var MAX_REPAIR_ATTEMPTS = 2;
+var DEFAULT_TIMEOUT_MS = 6e4;
+var RefinementService = class {
+  constructor(provider, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+  provider;
+  timeoutMs;
+  sessions = /* @__PURE__ */ new Map();
+  view(s) {
+    return { ...s };
+  }
+  async run(dir, workItemId, feedback, previous) {
+    const context = assembleRefinementContext(dir, workItemId);
+    if (context.workItem.status !== "draft") {
+      throw new RefinementProviderError("WORK_ITEM_NOT_EDITABLE", `A ${context.workItem.status} Work Item cannot be refined. Reopen it as Draft first.`);
+    }
+    const assets = getWorkItemAgentAssets();
+    const request = { context, assets, intent: context.workItem.intent, previousProposal: previous, feedback };
+    let lastErr;
+    for (let attempt = 0; attempt <= MAX_REPAIR_ATTEMPTS; attempt++) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+      try {
+        const result = await this.provider.refine(request, ac.signal);
+        const { validation } = normalizeAndValidateProposal(dir, workItemId, result.proposal);
+        const contextUsed = context.knowledge.map((k) => ({ id: k.id, title: k.title, layer: k.layer }));
+        return { context, proposal: result.proposal, validation, contextUsed, meta: { ...result.meta, repairAttempts: attempt } };
+      } catch (err) {
+        lastErr = err;
+        if (!(err instanceof RefinementProviderError && err.code === "INVALID_RESPONSE")) break;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new RefinementProviderError("PROVIDER_ERROR", "Refinement failed.");
+  }
+  async start(dir, workItemId) {
+    const { context, proposal, validation, contextUsed, meta } = await this.run(dir, workItemId);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const session = {
+      refinementId: `ref_${crypto.randomBytes(8).toString("hex")}`,
+      workItemId,
+      sourceRevision: context.revision,
+      status: "ready-for-review",
+      intent: context.workItem.intent,
+      proposal,
+      validation,
+      contextUsed,
+      meta,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessions.set(session.refinementId, session);
+    return this.view(session);
+  }
+  async feedback(dir, workItemId, refinementId, feedback) {
+    const session = this.get(refinementId, workItemId);
+    const { context, proposal, validation, contextUsed, meta } = await this.run(dir, workItemId, feedback, session.proposal);
+    session.sourceRevision = context.revision;
+    session.status = "ready-for-review";
+    session.proposal = proposal;
+    session.validation = validation;
+    session.contextUsed = contextUsed;
+    session.meta = meta;
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return this.view(session);
+  }
+  apply(dir, workItemId, refinementId, expectedRevision) {
+    const session = this.get(refinementId, workItemId);
+    const current = assembleRefinementContext(dir, workItemId);
+    if (current.revision !== session.sourceRevision || expectedRevision !== session.sourceRevision) {
+      session.status = "stale";
+      throw new RefinementProviderError("WORK_ITEM_CONFLICT", "This Work Item changed while the refinement was running. The proposal has not been applied.");
+    }
+    let res;
+    try {
+      res = applyRefinement(dir, workItemId, session.proposal, session.sourceRevision);
+    } catch (err) {
+      if (err instanceof WorkItemWriteError2) throw new RefinementProviderError(err.code, err.message);
+      throw err;
+    }
+    session.status = "applied";
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return { id: workItemId, path: res.path, revision: res.revision, status: "draft" };
+  }
+  get(refinementId, workItemId) {
+    const s = this.sessions.get(refinementId);
+    if (!s || s.workItemId !== workItemId) throw new RefinementProviderError("REFINEMENT_NOT_FOUND", "Refinement session not found.");
+    return s;
+  }
+};
+// src/refinement/heuristic-provider.ts
+function firstSentence(s) {
+  const m = s.trim().match(/^(.*?[.!?])(\s|$)/);
+  return (m ? m[1] : s.trim()).trim();
+}
+function mentionsNegation(feedback, module) {
+  const re = new RegExp(`(not|no)\\b[^.]*\\b${module}\\b|\\b${module}\\b[^.]*(not affected|no afecta|reviewed)`, "i");
+  return re.test(feedback);
+}
+var HeuristicRefinementProvider = class {
+  name = "heuristic";
+  async refine(request) {
+    const start = Date.now();
+    const { context, intent, previousProposal, feedback } = request;
+    const modules = context.modules;
+    const affected = new Set(previousProposal?.affectedModules ?? ["core"]);
+    if (feedback) {
+      for (const m of modules) {
+        if (new RegExp(`\\b${m}\\b`, "i").test(feedback)) {
+          if (mentionsNegation(feedback, m)) affected.delete(m);
+          else affected.add(m);
+        }
+      }
+    }
+    const affectedModules = modules.filter((m) => affected.has(m));
+    const moduleCoverage = modules.map(
+      (m) => affected.has(m) ? { id: m, status: "affected", reason: m === "core" ? "Backend behavior changes." : "User-facing change identified." } : { id: m, status: "unknown" }
+    );
+    const frontendAffected = affected.has("frontend");
+    const impactAnalysis = [
+      { surface: "backend", status: "affected" },
+      { surface: "frontend", status: frontendAffected ? "affected" : "unknown", ...frontendAffected ? {} : { question: "Is a user-facing surface involved?" } },
+      { surface: "database", status: "reviewed-not-affected" },
+      { surface: "feature-flags", status: "unknown", question: "Is this behavior controlled by a feature flag?" }
+    ];
+    const summary = firstSentence(intent);
+    const proposal = {
+      outcome: {
+        actor: "User",
+        observableOutcome: summary,
+        currentBehavior: `Today: ${summary.toLowerCase()} is not yet supported as described.`,
+        targetBehavior: summary
+      },
+      journey: {
+        entryPoints: [frontendAffected ? "Public entry point" : "Application entry point"],
+        flow: ["Entry point", "Application logic", "Persistence", "Result"]
+      },
+      affectedModules,
+      moduleCoverage,
+      impactAnalysis,
+      scopeConfidence: {
+        level: "medium",
+        reasons: ["Primary behavior identified from the intent.", "Feature flag ownership not yet confirmed."]
+      },
+      scopeUnknowns: ["Is this behavior controlled by a feature flag?"],
+      acceptanceCriteria: [
+        `${summary}`,
+        "The change is covered by the affected modules above."
+      ],
+      linkedDecisions: [],
+      relatedKnowledge: []
+    };
+    return { proposal, meta: { provider: this.name, durationMs: Date.now() - start, repairAttempts: 0 } };
+  }
+};
+// src/refinement/anthropic-provider.ts
+var API_URL = "https://api.anthropic.com/v1/messages";
+var SCHEMA_HINT = `Return ONLY a JSON object (no prose, no code fences) with this shape \u2014 omit fields you cannot determine:
+{
+  "title"?: string,
+  "outcome"?: { "actor"?: string, "observableOutcome"?: string, "currentBehavior"?: string, "targetBehavior"?: string },
+  "journey"?: { "entryPoints"?: string[], "flow"?: string[] },
+  "affectedModules"?: string[],
+  "moduleCoverage"?: [{ "id": string, "status": "affected"|"reviewed-not-affected"|"unknown"|"not-applicable", "reason"?: string }],
+  "impactAnalysis"?: [{ "surface": string, "status": "affected"|"reviewed-not-affected"|"unknown"|"not-applicable", "reason"?: string, "question"?: string }],
+  "scopeConfidence"?: { "level": "high"|"medium"|"low", "reasons"?: string[] },
+  "scopeUnknowns"?: string[],
+  "acceptanceCriteria"?: string[],
+  "linkedDecisions"?: string[],
+  "relatedKnowledge"?: string[]
+}
+Only reference module ids, decision ids and knowledge ids that appear in the provided context. Prefer "unknown" over inventing facts.`;
+function extractJson(text) {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new RefinementProviderError("INVALID_RESPONSE", "The model did not return a JSON proposal.");
+  try {
+    return JSON.parse(text.slice(start, end + 1));
+  } catch {
+    throw new RefinementProviderError("INVALID_RESPONSE", "The model returned a proposal that could not be parsed.");
+  }
+}
+var AnthropicRefinementProvider = class {
+  name = "anthropic";
+  apiKey;
+  model;
+  constructor(apiKey, model) {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+  async refine(request, signal) {
+    const start = Date.now();
+    const { context, assets, intent, previousProposal, feedback } = request;
+    const system = [
+      assets.agentPrompt,
+      assets.skill ?? "",
+      "# Output format",
+      SCHEMA_HINT
+    ].filter(Boolean).join("\n\n");
+    const userParts = [
+      `# Work Item intent
+${intent}`,
+      `# Project
+${JSON.stringify(context.project)}`,
+      `# Registered modules
+${context.modules.join(", ")}`,
+      `# Known decisions
+${context.decisions.map((d) => `${d.id} \u2014 ${d.title}`).join("\n") || "(none)"}`,
+      `# Knowledge
+${context.knowledge.map((k) => `${k.id} \u2014 ${k.title} (${k.layer})`).join("\n") || "(none)"}`,
+      `# Current Work Item model
+${JSON.stringify(context.workItem.current)}`
+    ];
+    if (previousProposal) userParts.push(`# Previous proposal
+${JSON.stringify(previousProposal)}`);
+    if (feedback) userParts.push(`# Human feedback (augments the original intent, does not replace it)
+${feedback}`);
+    let res;
+    try {
+      res = await fetch(API_URL, {
+        method: "POST",
+        signal,
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: 2048,
+          system,
+          messages: [{ role: "user", content: userParts.join("\n\n") }]
+        })
+      });
+    } catch (err) {
+      if (err.name === "AbortError") throw new RefinementProviderError("TIMEOUT", "The refinement timed out.");
+      throw new RefinementProviderError("PROVIDER_ERROR", "The refinement provider could not be reached.");
+    }
+    if (!res.ok) {
+      throw new RefinementProviderError("PROVIDER_ERROR", `The refinement provider returned an error (${res.status}).`);
+    }
+    const body = await res.json();
+    const text = (body.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("");
+    const proposal = extractJson(text);
+    return {
+      proposal,
+      meta: {
+        provider: this.name,
+        model: this.model,
+        durationMs: Date.now() - start,
+        inputTokens: body.usage?.input_tokens,
+        outputTokens: body.usage?.output_tokens
+      }
+    };
+  }
+};
+// src/refinement/index.ts
+function createRefinementService() {
+  const key = process.env.ANTHROPIC_API_KEY;
+  const model = process.env.KADDO_REFINEMENT_MODEL || "claude-3-5-sonnet-latest";
+  const provider = key ? new AnthropicRefinementProvider(key, model) : new HeuristicRefinementProvider();
+  return new RefinementService(provider);
+}
 // src/server.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function statusForCode(code) {
   switch (code) {
     case "WORK_ITEM_NOT_FOUND":
+    case "REFINEMENT_NOT_FOUND":
       return 404;
     case "WORK_ITEM_CONFLICT":
     case "WORK_ITEM_NOT_EDITABLE":
@@ -573,6 +882,11 @@ function statusForCode(code) {
     case "INVALID_WORK_ITEM_ID":
     case "INVALID_TRANSITION":
       return 400;
+    case "TIMEOUT":
+      return 504;
+    case "PROVIDER_ERROR":
+    case "INVALID_RESPONSE":
+      return 502;
     default:
       return 500;
   }
@@ -581,6 +895,7 @@ async function createAdminServer(opts) {
   const { projectDir, storage, staticDir, host = "127.0.0.1", port = 4173 } = opts;
   const app = Fastify({ logger: false });
   const sessionManager = new SessionManager(storage);
+  const refinement = createRefinementService();
   await app.register(fastifyCookie);
   await app.register(fastifyCors, {
     origin: `http://${host}:${port}`,
@@ -661,8 +976,9 @@ async function createAdminServer(opts) {
       throw err;
     }
   };
+  app.get("/api/v1/admin/work-items-capture", coreRoute(() => getCaptureDefinition()));
   app.post("/api/v1/admin/work-items", async (request, reply) => {
-    const parsed = WorkItemCreateSchema.safeParse(request.body);
+    const parsed = WorkItemCreateWithAnswersSchema.safeParse(request.body);
     if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "Intent and type are required." } });
     return writeHandler(reply, () => createWorkItemAdmin(projectDir, parsed.data));
   });
@@ -687,6 +1003,29 @@ async function createAdminServer(opts) {
     if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "expectedRevision is required." } });
     return writeHandler(reply, () => transitionWorkItemAdmin(projectDir, request.params.workItemId, "draft", parsed.data.expectedRevision));
   });
+  const refineHandler = async (reply, fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof RefinementProviderError || err instanceof CoreError) {
+        return reply.code(statusForCode(err.code)).send({ error: { code: err.code, message: err.message } });
+      }
+      throw err;
+    }
+  };
+  app.post("/api/v1/admin/work-items/:workItemId/refinement", async (request, reply) => {
+    return refineHandler(reply, () => refinement.start(projectDir, request.params.workItemId));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/refinement/feedback", async (request, reply) => {
+    const parsed = RefinementFeedbackSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "refinementId and feedback are required." } });
+    return refineHandler(reply, () => refinement.feedback(projectDir, request.params.workItemId, parsed.data.refinementId, parsed.data.feedback));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/refinement/apply", async (request, reply) => {
+    const parsed = RefinementApplySchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "refinementId and expectedRevision are required." } });
+    return refineHandler(reply, () => refinement.apply(projectDir, request.params.workItemId, parsed.data.refinementId, parsed.data.expectedRevision));
+  });
   app.get("/api/v1/admin/work-items/:workItemId", async (request, reply) => {
     try {
       return getWorkItemDetail(projectDir, request.params.workItemId);
@@ -853,11 +1192,14 @@ export {
   ProjectReadinessSchema,
   ProjectRouteSchema,
   ProjectSummarySchema,
+  RefinementApplySchema,
+  RefinementFeedbackSchema,
   RouteStepSchema,
   SQLiteAdminStorage,
   SessionManager,
   ValidationResultSchema,
   WorkItemCreateSchema,
+  WorkItemCreateWithAnswersSchema,
   WorkItemDetailSchema,
   WorkItemEditModelSchema,
   WorkItemInputSchema,