dsh-deeptutor 0.1.6 → 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)}`,

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")) {