@kontextmind/kxm 0.7.0 → 0.7.10

package/plugins/kxm/src/cli/tasks.ts

@@ -0,0 +1,364 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { probeHarnessesAsync } from "../vnext-harness.ts";
+import { suggestWorkflowAndRoles } from "../suggest.ts";
+import {
+  createGoal,
+  createTask,
+  listGoals,
+  listTasks,
+  getTask,
+  updateTaskStatus,
+  syncTaskWithTracker,
+  type TaskStatus,
+  type TrackerType,
+} from "../task-manager.ts";
+import { discoverVnextProjectRoot } from "../vnext-config.ts";
+import { compileVnextWorkflow } from "../vnext-engine-compile.ts";
+import {
+  createStudioServer,
+  DEFAULT_STUDIO_PORT,
+  generateStudioLayout,
+} from "../studio-layout.ts";
+import { readSessionTokenFromDisk } from "../commands.ts";
+import { print, type Runtime } from "./types.ts";
+import { cmdVnextRun } from "./vnext.ts";
+
+export async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
+  try {
+    const prompt = promptParts.join(" ").trim();
+    if (!prompt) {
+      runtime.io.stderr("prompt must be non-empty\n");
+      return 2;
+    }
+    const inventory = await probeHarnessesAsync({ env: runtime.env });
+    const availableHarnesses = inventory.harnesses.map((h) => ({
+      harness: h.id,
+      auth: h.authenticated === true ? "authenticated" : "unauthenticated",
+    }));
+    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses });
+
+    const text = [
+      `Suggested Workflow: ${suggestion.workflowId} (${suggestion.area})`,
+      `Confidence: ${(suggestion.confidence * 100).toFixed(0)}%`,
+      `Reasons: ${suggestion.reasons.join("; ")}`,
+      `Suggested Skills: ${suggestion.suggestedSkills.join(", ") || "none"}`,
+      `Roles:`,
+      `  Planner:     ${suggestion.roles.planner.harness} (${suggestion.roles.planner.model})`,
+      `  Writer:      ${suggestion.roles.writer.harness} (${suggestion.roles.writer.model})`,
+      `  Critics:     ${suggestion.roles.critics.map((c) => `${c.harness}:${c.model}`).join(", ")}`,
+      `  Verifier:    ${suggestion.roles.verifier.command}`,
+      ``,
+      `Execute with:`,
+      `  ${suggestion.suggestedCommand}`,
+    ].join("\n");
+
+    print(runtime.io, runtime.json, { ok: true, command: "suggest", prompt, ...suggestion }, text);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`suggest failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdGoalCreate(
+  runtime: Runtime,
+  title: string,
+  options: { area?: string | undefined; metric?: string[] | undefined; targetDate?: string | undefined },
+): Promise<number> {
+  try {
+    const goal = createGoal(runtime.cwd, {
+      title,
+      area: options.area,
+      successMetrics: options.metric,
+      targetDate: options.targetDate,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "goal create", goal },
+      `Created goal ${goal.id}: ${goal.title}`,
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`goal create failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdGoalList(runtime: Runtime): Promise<number> {
+  try {
+    const goals = listGoals(runtime.cwd);
+    const text = goals.length === 0
+      ? "No goals recorded in .kxm/goals/"
+      : goals.map((g) => `[${g.status}] ${g.id}: ${g.title} (${g.area})`).join("\n");
+    print(runtime.io, runtime.json, { ok: true, command: "goal list", count: goals.length, goals }, text);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`goal list failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdTaskCreate(
+  runtime: Runtime,
+  title: string,
+  options: { goal?: string | undefined; objective?: string | undefined; workflow?: string | undefined; tracker?: string | undefined; issue?: string | undefined },
+): Promise<number> {
+  try {
+    const task = createTask(runtime.cwd, {
+      title,
+      goalId: options.goal,
+      objective: options.objective ?? title,
+      assignedWorkflow: options.workflow,
+      trackerSync: options.tracker && options.issue
+        ? { tracker: options.tracker as TrackerType, issueKey: options.issue }
+        : undefined,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "task create", task },
+      `Created task ${task.id}: ${task.title} [${task.status}]`,
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`task create failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdTaskList(
+  runtime: Runtime,
+  options: { goal?: string | undefined; status?: string | undefined },
+): Promise<number> {
+  try {
+    const tasks = listTasks(runtime.cwd, {
+      goalId: options.goal,
+      status: options.status as TaskStatus | undefined,
+    });
+    const text = tasks.length === 0
+      ? "No tasks recorded in .kxm/tasks/"
+      : tasks.map((t) => `[${t.status}] ${t.id}: ${t.title}${t.assignedWorkflow ? ` -> ${t.assignedWorkflow}` : ""}`).join("\n");
+    print(runtime.io, runtime.json, { ok: true, command: "task list", count: tasks.length, tasks }, text);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`task list failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdTaskGet(runtime: Runtime, taskId: string): Promise<number> {
+  try {
+    const task = getTask(runtime.cwd, taskId);
+    if (!task) {
+      runtime.io.stderr(`Task ${taskId} not found\n`);
+      return 1;
+    }
+    const text = [
+      `Task: ${task.id}`,
+      `Title: ${task.title}`,
+      `Status: ${task.status}`,
+      `Objective: ${task.objective}`,
+      task.assignedWorkflow ? `Workflow: ${task.assignedWorkflow}` : "",
+      task.workflowRunId ? `Active Run: ${task.workflowRunId}` : "",
+      task.trackerSync ? `Tracker: ${task.trackerSync.tracker} (#${task.trackerSync.issueKey}) [${task.trackerSync.syncStatus}]` : "",
+    ].filter(Boolean).join("\n");
+    print(runtime.io, runtime.json, { ok: true, command: "task get", task }, text);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`task get failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<number> {
+  try {
+    const task = getTask(runtime.cwd, taskId);
+    if (!task) {
+      runtime.io.stderr(`Task ${taskId} not found\n`);
+      return 1;
+    }
+    const workflow = task.assignedWorkflow ?? "default";
+    const exitCode = await cmdVnextRun(runtime, workflow, [task.objective]);
+    if (exitCode === 0) {
+      updateTaskStatus(runtime.cwd, taskId, "in_progress");
+    }
+    return exitCode;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`task run failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdTaskSync(runtime: Runtime, taskId: string): Promise<number> {
+  try {
+    const synced = syncTaskWithTracker(runtime.cwd, taskId);
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "task sync", task: synced },
+      `Synced task ${taskId} with ${synced.trackerSync?.tracker} #${synced.trackerSync?.issueKey}`,
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`task sync failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdStudioLayout(runtime: Runtime, workflowPath?: string | undefined): Promise<number> {
+  try {
+    const projectRoot = discoverVnextProjectRoot(runtime.cwd) ?? runtime.cwd;
+    let filePath = workflowPath;
+    if (!filePath) {
+      filePath = resolve(projectRoot, ".kxm", "workflows", "default.yaml");
+    }
+    let yamlContent: string;
+    let workflowId = "default";
+    if (existsSync(filePath)) {
+      yamlContent = readFileSync(filePath, "utf8");
+    } else {
+      yamlContent = `schema: kxm.workflow.v1
+description: Feature implementation workflow
+coordinator: coordinator
+limits:
+  maxTransitions: 12
+steps:
+  - id: plan
+    kind: agent
+    agent: planner
+    maxAttempts: 2
+    on:
+      passed: implement
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: implement
+    kind: agent
+    agent: writer
+    maxAttempts: 3
+    on:
+      passed: verify
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: verify
+    kind: gate
+    gate: verify-gate
+    expect: pass
+    maxAttempts: 2
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: implement
+        maxTransitions: 2
+`;
+    }
+    const parsedYaml = parseYaml(yamlContent) as any;
+    const plan = compileVnextWorkflow({ id: workflowId, value: parsedYaml });
+    const layout = generateStudioLayout(plan);
+    print(runtime.io, runtime.json, { ok: true, command: "studio layout", layout }, JSON.stringify(layout, null, 2));
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`studio layout failed: ${message}\n`);
+    return 1;
+  }
+}
+
+export async function cmdStudioServe(
+  runtime: Runtime,
+  options: { port?: string | undefined; host?: string | undefined; token?: string | undefined },
+): Promise<number> {
+  const port = options.port ? parseInt(options.port, 10) : DEFAULT_STUDIO_PORT;
+  const host = options.host ?? "127.0.0.1";
+  const sessionToken = options.token
+    ?? runtime.env.KXM_SESSION_TOKEN
+    ?? readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR })?.token;
+
+  if (runtime.dryRun) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "studio serve", dryRun: true, port, host },
+      `would start studio server on http://${host}:${port}`,
+    );
+    return 0;
+  }
+
+  try {
+    const serverHandle = createStudioServer({
+      port,
+      host,
+      projectRoot: runtime.cwd,
+      sessionToken,
+      planProvider: () => {
+        try {
+          const wfDir = join(runtime.cwd, ".kxm", "workflows");
+          const defaultPath = join(wfDir, "default.yaml");
+          let targetPath = existsSync(defaultPath) ? defaultPath : undefined;
+          if (!targetPath && existsSync(wfDir)) {
+            const yml = readdirSync(wfDir).find((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+            if (yml) targetPath = join(wfDir, yml);
+          }
+          if (targetPath && existsSync(targetPath)) {
+            const raw = readFileSync(targetPath, "utf8");
+            const parsed = parseYaml(raw) as any;
+            const wfId = basename(targetPath).replace(/\.(yaml|yml)$/, "");
+            return compileVnextWorkflow({ id: wfId, value: parsed });
+          }
+        } catch {
+          // fallback
+        }
+        return undefined;
+      },
+    });
+    const actualPort = await serverHandle.listen();
+    const info = {
+      ok: true,
+      command: "studio serve",
+      port: actualPort,
+      host,
+      url: `http://${host}:${actualPort}`,
+    };
+    print(
+      runtime.io,
+      runtime.json,
+      info,
+      `KXM Web Studio listening on http://${host}:${actualPort} (Decision Q8 & D14)\nPress Ctrl+C to stop.\n`,
+    );
+
+    if (runtime.env.KXM_STUDIO_ONCE) {
+      await serverHandle.close();
+      return 0;
+    }
+
+    await new Promise<void>((resolveClose) => {
+      const shutdown = async () => {
+        process.off("SIGINT", shutdown);
+        process.off("SIGTERM", shutdown);
+        await serverHandle.close();
+        resolveClose();
+      };
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
+    });
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`studio serve failed: ${message}\n`);
+    return 1;
+  }
+}

package/plugins/kxm/src/cli/types.ts

@@ -0,0 +1,270 @@
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Command } from "commander";
+import { redactSecrets } from "../redact.ts";
+import { appendTelemetry, inferImprovementTarget, makeTelemetryEvent, telemetryPath } from "../telemetry.ts";
+import { gateWorker, workerResult, type Worker, type WorkerOutcome } from "../envelope.ts";
+import { canonicalWorkflowEvidenceKey, type WorkflowEvidenceInput } from "../workflow.ts";
+import {
+  HubBindingError,
+  hubBindingFile,
+  readHubBinding,
+} from "../hub-binding.ts";
+import type { InstallProbe } from "../kxm-install-kind.ts";
+
+export interface CliSpawnResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
+
+export interface CliIo {
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  spawnHub?: (extraEnv: NodeJS.ProcessEnv) => number | Promise<number>;
+  spawnWorker?: (extraEnv: NodeJS.ProcessEnv) => number | Promise<number>;
+  installProbe?: Partial<InstallProbe>;
+  spawnSync?: (command: string, args: readonly string[]) => CliSpawnResult;
+}
+
+export interface CliContext {
+  env: NodeJS.ProcessEnv;
+  io: CliIo;
+  cwd: string;
+}
+
+export interface GlobalOpts {
+  json?: boolean;
+  dryRun?: boolean;
+  workspace?: string;
+}
+
+export interface WorkspaceDirs {
+  workdir: string;
+  workspace: string;
+  config: string;
+  logs: string;
+  assets: string;
+  state: string;
+}
+
+export interface Runtime extends CliContext, Required<Pick<GlobalOpts, "json" | "dryRun">> {
+  workspaceFlag?: string;
+  dirs: WorkspaceDirs;
+  serverUrl: string;
+  boundHubUrl?: string;
+  fetchImpl: typeof fetch;
+}
+
+const repoRoot = resolve(fileURLToPath(new URL("../../../../", import.meta.url)));
+
+export function spawnScript(scriptName: string, extraEnv: NodeJS.ProcessEnv = {}): Promise<number> {
+  return new Promise((resolveExit) => {
+    const child = spawn(process.execPath, [join(repoRoot, "scripts", scriptName)], {
+      stdio: "inherit",
+      env: { ...process.env, ...extraEnv },
+    });
+    child.once("error", () => resolveExit(1));
+    child.once("exit", (code) => resolveExit(code ?? 1));
+  });
+}
+
+export function parseEvidencePairs(values: string[]): WorkflowEvidenceInput {
+  const evidence = new Map<string, string>();
+  for (const value of values) {
+    const separator = value.indexOf("=");
+    if (separator <= 0 || separator === value.length - 1) {
+      throw new Error("evidence must use <required-key>=<evidence> syntax");
+    }
+    const requirement = canonicalWorkflowEvidenceKey(value.slice(0, separator));
+    const proof = value.slice(separator + 1).trim();
+    if (!requirement || !proof) throw new Error("evidence must use <required-key>=<evidence> syntax");
+    if (evidence.has(requirement)) throw new Error(`duplicate normalized evidence key: ${requirement}`);
+    evidence.set(requirement, proof);
+  }
+  return Object.fromEntries(evidence);
+}
+
+export const CLI_RESULT_SCHEMA = "kxm.cli-result.v1";
+
+/** Every CLI payload carries a schema tag; payloads that already declare one
+ * (worker envelopes) keep theirs. `ok:false` goes to stderr in both modes so
+ * agents can split results from errors without parsing. */
+export function print(io: CliIo, jsonMode: boolean, payload: object, text: string): void {
+  const tagged = { schema: CLI_RESULT_SCHEMA, ...payload } as Record<string, unknown>;
+  const safePayload = JSON.stringify(redactCliValue(tagged));
+  const line = jsonMode ? `${safePayload}\n` : `${redactSecrets(text)}\n`;
+  if (tagged.ok === false) io.stderr(line);
+  else io.stdout(line);
+}
+
+export function printWorker(
+  runtime: Runtime,
+  worker: Worker,
+  payload: Record<string, unknown> & { command: string; ok: boolean },
+  text: string,
+  outcome?: WorkerOutcome,
+): void {
+  const sessionId = runtime.env.KXM_SESSION_ID?.trim();
+  const envelope = workerResult(worker, {
+    ...payload,
+    summary: text,
+    ...(outcome ? { outcome } : {}),
+    ...(sessionId ? { sessionId } : {}),
+  });
+  if (!runtime.dryRun) {
+    try {
+      const safeEnvelope = redactCliValue(envelope) as typeof envelope;
+      appendTelemetry(telemetryPath(runtime.dirs.logs), makeTelemetryEvent({
+        envelope: safeEnvelope,
+        ...(sessionId ? { sessionId } : {}),
+        host: hostMode(runtime),
+        target: inferImprovementTarget({
+          ...(worker.project ? { project: worker.project } : {}),
+          env: runtime.env,
+        }),
+      }));
+    } catch {
+      // Telemetry must never fail the operator command.
+    }
+  }
+  print(runtime.io, runtime.json, envelope, text);
+}
+
+export function hostMode(runtime: Runtime): "local" | "hub" {
+  try {
+    const hostname = new URL(runtime.serverUrl).hostname;
+    if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1") return "local";
+  } catch {
+    // Default local when the hub URL is not a URL.
+  }
+  return "hub";
+}
+
+export function gateOf(runtime: Runtime, name: string): ReturnType<typeof gateWorker> {
+  const project = runtime.env.KXM_PROJECT?.trim();
+  return gateWorker({ name, ...(project ? { project } : {}) });
+}
+
+export function redactCliValue(value: unknown, field = ""): unknown {
+  if (typeof value === "string") {
+    // These fields are public audit digests, not credentials. Preserve
+    // them only by exact field name and shape; every other 64-hex value keeps
+    // the conservative generic redaction behavior.
+    if (
+      (field === "requestSha256"
+        || field === "replySha256"
+        || field === "behavioralSha256"
+        || field === "workflowDefinitionSha256"
+        || field === "verifierConfigSha256"
+        || field === "rolePromptSha256"
+        || field === "contentSha256"
+        || field === "configRevision"
+        || field === "baseSha256"
+        || field === "localSha256"
+        || field === "targetSha256"
+        || field === "sourceTemplateRevision"
+        || field === "targetTemplateRevision"
+        || field === "sourceDigest"
+        || field === "decisionDigest"
+        || field === "receiptSha256"
+        || field === "sha256"
+        || field === "valueSha256"
+        || field === "baseRevision"
+        || field === "candidateRevision"
+        || field === "baseValueSha256"
+        || field === "candidateValueSha256")
+      && /^(?:sha256:)?[a-f0-9]{64}$/.test(value)
+    ) return value;
+    return redactSecrets(value);
+  }
+  if (Array.isArray(value)) return value.map((candidate) => redactCliValue(candidate));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .map(([key, candidate]) => [key, redactCliValue(candidate, key)]),
+    );
+  }
+  return value;
+}
+
+export function workspaceDirs(cwd: string, workspaceFlag: string | undefined, env: NodeJS.ProcessEnv): WorkspaceDirs {
+  const workdir = resolve(env.KXM_WORKDIR?.trim() || cwd);
+  const workspace = resolve(workdir, workspaceFlag || env.KXM_WORKSPACE_DIR?.trim() || ".kxm");
+  const derive = workspaceFlag !== undefined;
+  return {
+    workdir,
+    workspace,
+    config: derive ? join(workspace, "config") : resolve(workdir, env.KXM_CONFIG_DIR?.trim() || join(workspace, "config")),
+    logs: derive ? join(workspace, "logs") : resolve(workdir, env.KXM_LOGS_DIR?.trim() || join(workspace, "logs")),
+    assets: derive ? join(workspace, "assets") : resolve(workdir, env.KXM_ASSETS_DIR?.trim() || join(workspace, "assets")),
+    state: derive ? join(workspace, "state") : resolve(workdir, env.KXM_STATE_DIR?.trim() || join(workspace, "state")),
+  };
+}
+
+export function maskEnvName(name: string): boolean {
+  return /TOKEN|SECRET|KEY|PASSWORD/i.test(name);
+}
+
+export function redactConfiguredValues(text: string, env: NodeJS.ProcessEnv): string {
+  let safe = text;
+  for (const [name, value] of Object.entries(env)) {
+    if (!maskEnvName(name) || !value || value.length < 4) continue;
+    safe = safe.replaceAll(value, "[redacted]");
+  }
+  const trailingNewline = safe.endsWith("\n") ? "\n" : "";
+  try {
+    const parsed = JSON.parse(safe) as unknown;
+    return `${JSON.stringify(redactCliValue(parsed))}${trailingNewline}`;
+  } catch {
+    // Human-readable output and diagnostics keep conservative generic
+    // redaction, including opaque 64-hex values.
+  }
+  return redactSecrets(safe);
+}
+
+export function processExists(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
+}
+
+export function runtimeFrom(ctx: CliContext, command: Command): Runtime {
+  const opts = command.optsWithGlobals() as GlobalOpts;
+  const envServerUrl = ctx.env.KXM_SERVER_URL?.trim();
+  let boundHubUrl: string | undefined;
+  try {
+    boundHubUrl = readHubBinding(ctx.env)?.url;
+  } catch (error) {
+    if (error instanceof HubBindingError) {
+      ctx.io.stderr(`kxm: ignoring malformed hub binding at ${hubBindingFile(ctx.env)}; run kxm hub bind <url> again\n`);
+    } else {
+      throw error;
+    }
+  }
+  return {
+    ...ctx,
+    json: Boolean(opts.json),
+    dryRun: Boolean(opts.dryRun),
+    ...(opts.workspace === undefined ? {} : { workspaceFlag: opts.workspace }),
+    dirs: workspaceDirs(ctx.cwd, opts.workspace, ctx.env),
+    serverUrl: envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
+    ...(boundHubUrl ? { boundHubUrl } : {}),
+    fetchImpl: ctx.io.fetchImpl ?? fetch,
+  };
+}
+
+export function workspaceEnv(runtime: Runtime): NodeJS.ProcessEnv {
+  return {
+    KXM_WORKDIR: runtime.dirs.workdir,
+    KXM_WORKSPACE_DIR: runtime.dirs.workspace,
+    KXM_CONFIG_DIR: runtime.dirs.config,
+    KXM_LOGS_DIR: runtime.dirs.logs,
+    KXM_ASSETS_DIR: runtime.dirs.assets,
+    KXM_STATE_DIR: runtime.dirs.state,
+    KXM_SERVER_URL: runtime.serverUrl,
+  };
+}