dsh-deeptutor 0.1.5 → 0.1.7

package/skills/html-doc/scripts/md-to-html.js

@@ -9,7 +9,7 @@
  *
  * Features: headings, fenced code blocks, inline code/bold/italic/links, lists,
  * task lists, blockquotes, pipe tables, hr, quiz answer collapsing (<details>),
- * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 22).
+ * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 20.11 — uses import.meta.dirname).
  */
 "use strict";
 
@@ -29,22 +29,41 @@ function parseArgs(argv) {
     collapse: true,
   };
   const positional = [];
+  const valueFlags = new Set(["--out", "--title", "--theme", "--lang"]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--out") opts.out = argv[++i];
-    else if (a === "--title") opts.title = argv[++i];
-    else if (a === "--theme") opts.theme = argv[++i] === "dark" ? "dark" : "light";
-    else if (a === "--toc") opts.toc = true;
-    else if (a === "--lang") opts.lang = argv[++i];
+    if (a === "--toc") opts.toc = true;
     else if (a === "--no-collapse") opts.collapse = false;
     else if (a === "--help" || a === "-h") {
       printHelp();
       process.exit(0);
+    } else if (valueFlags.has(a)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        fail(`Missing value for ${a} (e.g. --out out.html)`);
+      }
+      i++;
+      if (a === "--out") opts.out = value;
+      else if (a === "--title") opts.title = value;
+      else if (a === "--theme") {
+        if (value !== "dark" && value !== "light") {
+          fail(`Invalid --theme value "${value}": expected dark or light`);
+        }
+        opts.theme = value;
+      } else if (a === "--lang") opts.lang = value;
+    } else if (a.startsWith("--")) {
+      fail(`Unknown option: ${a} (run with --help for usage)`);
     } else positional.push(a);
   }
   return { opts, positional };
 }
 
+/** Print an error to stderr and exit non-zero (CLI contract: never silently swallow bad flags). */
+function fail(message) {
+  console.error(`[html-doc] ${message}`);
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`md-to-html.js — Markdown → self-contained HTML
 
@@ -330,7 +349,16 @@ function main() {
       : "";
 
   const generated = new Date().toISOString().slice(0, 10);
-  const templatePath = path.join(import.meta.dirname, "..", "assets", "template.html");
+  // The same converter ships in two locations (skills/html-doc/scripts/ and a
+  // package-root scripts/ copy); resolve the template wherever we are.
+  const templateCandidates = [
+    path.join(import.meta.dirname, "..", "assets", "template.html"),
+    path.join(import.meta.dirname, "..", "skills", "html-doc", "assets", "template.html"),
+  ];
+  const templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  if (!templatePath) {
+    fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
+  }
   let template = fs.readFileSync(templatePath, "utf8");
   template = template
     .replace(/\{\{TITLE\}\}/g, esc(title))

package/src/config.ts

@@ -52,6 +52,7 @@ export function configGuide(): string {
     '   export DEEPTUTOR_REMOTE_HOME="remote-DEEPTUTOR_HOME-workspace"\n' +
     "   Verify serve is running on the server (ssh to it: curl http://127.0.0.1:8001/api/v1/system/status)\n" +
     "   Verify passwordless SSH login works (ssh alias + BatchMode)\n" +
+    'PowerShell users: use $env:VAR="value" instead of export VAR=value.\n' +
     "Restart the agent after configuring.\n"
   );
 }

package/src/http-api.ts

@@ -31,6 +31,7 @@ export async function apiProbe(timeoutMs = 1500): Promise<boolean> {
 export async function ensureApi(): Promise<boolean> {
   if (await apiProbe(1200)) return true;
   if (!SSH_HOST) return false; // Local deployment: fall back to local CLI when serve is down, no tunnel needed
+  let tunnelDead = false;
   if (!tunnelProc || tunnelProc.exitCode !== null) {
     tunnelProc = spawn(
       "ssh",
@@ -52,9 +53,16 @@ export async function ensureApi(): Promise<boolean> {
       ],
       { stdio: "ignore", windowsHide: true },
     );
+    // Fast-fail: a tunnel that exits immediately (bad alias, port in use,
+    // refused connection) is not going to recover — stop waiting for it.
+    tunnelProc.once("exit", () => {
+      tunnelDead = true;
+      tunnelProc = null;
+    });
     tunnelProc.unref();
   }
   for (let i = 0; i < 20; i++) {
+    if (tunnelDead) return false;
     if (await apiProbe(1000)) return true;
     await new Promise((r) => setTimeout(r, 500));
   }
@@ -70,7 +78,14 @@ export async function apiJson(
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
   const onAbort = () => controller.abort();
-  opts.signal?.addEventListener("abort", onAbort, { once: true });
+  // An already-aborted signal never fires its "abort" event again — check the
+  // flag first so a pre-aborted call fails immediately instead of running to
+  // completion against a still-open controller.
+  if (opts.signal?.aborted) {
+    controller.abort();
+  } else {
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+  }
   try {
     const res = await fetch(`${API_BASE}${path}`, { ...init, signal: controller.signal });
     if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);

package/src/index.ts

@@ -162,6 +162,10 @@ export function apply(ctx: Context) {
               configHint() + fmtTurnResult(args.capability, r, maxChars) + htmlNote,
           });
         } catch (err: any) {
+          if (exec.signal.aborted) {
+            // user cancelled mid-CLI-run: report it as a cancellation, not a failure
+            throw new Error("[deeptutor_run cancelled]");
+          }
           throw new Error(
             configGuide() +
               `[deeptutor_run failed (HTTP and CLI both unavailable)] ${err?.message ?? String(err)}`,
@@ -200,7 +204,8 @@ export function apply(ctx: Context) {
         },
         top_k: {
           type: "number",
-          description: "Number of hits to return, default 5",
+          description:
+            "Number of hits to return, default 5 (applied locally to the CLI search result; the deeptutor CLI has no --top-k flag)",
         },
         max_chars: {
           type: "number",
@@ -267,7 +272,8 @@ export function apply(ctx: Context) {
             );
           }
         }
-        // CLI fallback (local or SSH)
+        // CLI fallback (local or SSH). NOTE: `kb search` has no --top-k flag
+        // (verified on deeptutor CLI 1.5.x); top_k is applied locally below.
         let argv: string[];
         if (args.action === "list") {
           argv = ["kb", "list", "--format", "json"];
@@ -284,7 +290,6 @@ export function apply(ctx: Context) {
             "--mode",
             args.mode ?? "hybrid",
           ];
-          if (args.top_k) argv.push("--top-k", String(args.top_k));
         }
         const { stdout, stderr, code, killed } = await runCli(argv, {
           signal: exec.signal,
@@ -300,16 +305,30 @@ export function apply(ctx: Context) {
         let body = stdout.trim() || "(empty result)";
         if (args.action === "search") {
           try {
-            const arr = JSON.parse(stdout);
-            if (Array.isArray(arr)) {
-              body = arr
-                .map((s: any, i: number) => {
-                  const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
-                  const src = s.source ?? s.doc_name ?? s.file ?? "";
-                  return `[${i + 1}]${src ? `  source: ${src}` : ""}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
-                })
-                .join("\n\n");
-              body = `${arr.length} hits:\n\n` + body;
+            const parsed = JSON.parse(stdout);
+            const fmtHit = (s: any, i: number) => {
+              const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
+              const src = s.source ?? s.doc_name ?? s.file ?? "";
+              const title = s.title ? `  title: ${s.title}` : "";
+              const score = typeof s.score === "number" ? `  score: ${s.score}` : "";
+              return `[${i + 1}]${src ? `  source: ${src}` : ""}${title}${score}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
+            };
+            // Current deeptutor CLI (1.5.x) returns an object
+            // { query, answer, content, sources, provider }; older builds
+            // returned a bare array of hits. Accept both.
+            if (Array.isArray(parsed)) {
+              const hits = args.top_k ? parsed.slice(0, args.top_k) : parsed;
+              body = `${hits.length} hits:\n\n` + hits.map(fmtHit).join("\n\n");
+            } else if (parsed && typeof parsed === "object") {
+              const parts: string[] = [];
+              if (parsed.query) parts.push(`Query: ${parsed.query}`);
+              if (typeof parsed.answer === "string" && parsed.answer.trim())
+                parts.push(`Answer: ${parsed.answer.trim()}`);
+              const sources = Array.isArray(parsed.sources) ? parsed.sources : [];
+              const hits = args.top_k ? sources.slice(0, args.top_k) : sources;
+              parts.push(`${hits.length} hits:`);
+              parts.push(hits.map(fmtHit).join("\n\n"));
+              body = parts.join("\n\n");
             }
           } catch {
             /* non-JSON output returned as-is */

package/src/turn.ts

@@ -128,21 +128,44 @@ export function wsRunTurn(
   });
 }
 
-/** Execute one turn via the CLI (local or SSH). */
-export async function cliRunTurn(
-  params: RunParams,
-  timeoutMs: number,
-  signal?: AbortSignal,
-): Promise<TurnResult> {
+/**
+ * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
+ * Scalar config values go as repeatable --config k=v; object/array values are
+ * collected into --config-json (the CLI's documented form for complex config)
+ * instead of being stringified into a k=<json> value that no parser expects.
+ */
+export function buildRunArgs(params: RunParams): string[] {
   const argv = ["run", params.capability, params.prompt, "--format", "json"];
   for (const kb of params.kbs ?? []) argv.push("--kb", kb);
   for (const t of params.tools ?? []) argv.push("--tool", t);
   if (params.session_id) argv.push("--session", params.session_id);
   if (params.language) argv.push("--language", params.language);
-  for (const [k, v] of Object.entries(params.config ?? {}))
-    argv.push("--config", `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`);
-  const { stdout, stderr, code, killed } = await runCli(argv, { signal, timeoutMs });
-  if (killed) throw new Error(`CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`);
+  const complexConfig: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(params.config ?? {})) {
+    if (typeof v === "object" && v !== null) complexConfig[k] = v;
+    else argv.push("--config", `${k}=${v}`);
+  }
+  if (Object.keys(complexConfig).length > 0) {
+    argv.push("--config-json", JSON.stringify(complexConfig));
+  }
+  return argv;
+}
+
+/** Execute one turn via the CLI (local or SSH). `run` is injectable for tests. */
+export async function cliRunTurn(
+  params: RunParams,
+  timeoutMs: number,
+  signal?: AbortSignal,
+  run: typeof runCli = runCli,
+): Promise<TurnResult> {
+  const { stdout, stderr, code, killed } = await run(buildRunArgs(params), { signal, timeoutMs });
+  if (killed) {
+    // A kill can come from the user cancelling (signal) or from the timeout;
+    // report the real reason instead of always blaming the timeout.
+    throw new Error(
+      signal?.aborted ? "Aborted" : `CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`,
+    );
+  }
   if (code !== 0) throw new Error(`CLI exit=${code}: ${stderr || "(no stderr)"}`);
   const state: TurnResult = { answer: "", errors: [], toolCalls: [] };
   for (const line of stdout.split("\n")) {