ultracode-ai 1.3.0

package/dist/commands/doctor.js

@@ -0,0 +1,188 @@
+/**
+ * `ultracode doctor [--json]`
+ *
+ * Fully offline environment check: Node version, git availability, config
+ * directory writability, config validity, API-key presence (masked — the key
+ * value is never printed) and terminal capabilities. Critical failures set
+ * exit code 1.
+ */
+import path from "node:path";
+import process from "node:process";
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { USER_CONFIG_DIR, serializeError } from "ultracode-shared";
+import { safeDispose } from "../context.js";
+import { resolveHome } from "../utils/resolve-home.js";
+import { maskSecret } from "../utils/text.js";
+/** Environment variables checked for API-key presence. */
+export const API_KEY_VARS = [
+    "MISTRAL_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "ULTRACODE_API_KEY",
+];
+/** Minimum supported Node.js major version. */
+export const MIN_NODE_MAJOR = 22;
+/**
+ * Minimum supported Node.js minor version *within* {@link MIN_NODE_MAJOR}.
+ * A newer major satisfies the requirement regardless of its minor; only the
+ * boundary major is gated on this minor. Mirrors the `engines.node`
+ * (`>=22.13.0`) declared by every workspace package.
+ */
+export const MIN_NODE_MINOR = 13;
+/** Default writability probe: mkdir -p, then create + delete a marker file. */
+export async function defaultCheckWritable(dir) {
+    const marker = path.join(dir, `.ultracode-doctor-${randomUUID()}`);
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(marker, "doctor", "utf8");
+        await fs.unlink(marker);
+        return true;
+    }
+    catch (err) {
+        return serializeError(err).message;
+    }
+}
+/** Build the production {@link DoctorDeps} from a {@link CliContext}. */
+export function makeDefaultDoctorDeps(ctx) {
+    return {
+        nodeVersion: ctx.nodeVersion,
+        env: ctx.env,
+        isTTY: ctx.stdout.isTTY === true,
+        gitVersion: () => ctx.gitVersion(),
+        configDir: resolveHome(USER_CONFIG_DIR, ctx.homedir),
+        checkWritable: defaultCheckWritable,
+        loadConfig: async () => {
+            const facade = await ctx.createFacade({ cwd: ctx.cwd });
+            await safeDispose(facade);
+        },
+    };
+}
+/** Run all doctor checks. Never throws — failures become `ok: false` checks. */
+export async function collectDoctorReport(deps) {
+    const checks = [];
+    // 1. Node.js version (critical)
+    const [majorRaw, minorRaw] = deps.nodeVersion.split(".");
+    const major = Number.parseInt(majorRaw ?? "", 10);
+    const minor = Number.parseInt(minorRaw ?? "", 10);
+    const required = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
+    // A newer major always qualifies; the boundary major additionally requires
+    // minor >= MIN_NODE_MINOR (an unparseable minor on the boundary major fails).
+    const nodeOk = Number.isFinite(major) &&
+        (major > MIN_NODE_MAJOR ||
+            (major === MIN_NODE_MAJOR && Number.isFinite(minor) && minor >= MIN_NODE_MINOR));
+    checks.push({
+        name: "node",
+        ok: nodeOk,
+        critical: true,
+        detail: nodeOk
+            ? `Node.js v${deps.nodeVersion} (>= ${required} required)`
+            : `Node.js v${deps.nodeVersion} is not supported — version ${required} or newer is required`,
+    });
+    // 2. git availability (non-critical)
+    let git = null;
+    try {
+        git = await deps.gitVersion();
+    }
+    catch {
+        git = null;
+    }
+    checks.push({
+        name: "git",
+        ok: git !== null,
+        critical: false,
+        detail: git !== null ? git : "git not found in PATH — versioning features are unavailable",
+    });
+    // 3. config directory writable (critical)
+    let writable;
+    try {
+        writable = await deps.checkWritable(deps.configDir);
+    }
+    catch (err) {
+        writable = serializeError(err).message;
+    }
+    checks.push({
+        name: "config-dir",
+        ok: writable === true,
+        critical: true,
+        detail: writable === true
+            ? `config directory writable: ${deps.configDir}`
+            : `config directory not writable (${deps.configDir}): ${writable}`,
+    });
+    // 4. configuration loads + validates (critical)
+    try {
+        await deps.loadConfig();
+        checks.push({
+            name: "config",
+            ok: true,
+            critical: true,
+            detail: "configuration loaded and validated",
+        });
+    }
+    catch (err) {
+        const s = serializeError(err);
+        checks.push({
+            name: "config",
+            ok: false,
+            critical: true,
+            detail: `configuration invalid: ${s.message}`,
+        });
+    }
+    // 5. API keys (presence only, masked; non-critical)
+    const present = API_KEY_VARS.filter((k) => {
+        const v = deps.env[k];
+        return typeof v === "string" && v.trim() !== "";
+    });
+    checks.push({
+        name: "api-keys",
+        ok: present.length > 0,
+        critical: false,
+        detail: present.length > 0
+            ? present.map((k) => `${k}=${maskSecret(deps.env[k] ?? "")}`).join(", ")
+            : "no API keys found in the environment — run `ultracode --setup`",
+    });
+    // 6. terminal capabilities (informational, non-critical)
+    const colorHints = [];
+    if (deps.env["NO_COLOR"] !== undefined)
+        colorHints.push("colors disabled (NO_COLOR)");
+    if (deps.env["TERM"] === "dumb")
+        colorHints.push("TERM=dumb");
+    checks.push({
+        name: "terminal",
+        ok: deps.isTTY,
+        critical: false,
+        detail: deps.isTTY
+            ? `interactive TTY available${colorHints.length > 0 ? ` — ${colorHints.join(", ")}` : ""}`
+            : "stdout is not a TTY — interactive mode unavailable (use `run -p`)",
+    });
+    const ok = checks.every((c) => c.ok || !c.critical);
+    return { ok, checks };
+}
+/** Render a {@link DoctorReport} as a ✓/✗ checklist. */
+export function renderDoctorReport(report) {
+    const lines = ["UltraCode Doctor"];
+    for (const c of report.checks) {
+        lines.push(`${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+    }
+    lines.push(report.ok ? "✓ all critical checks passed" : "✗ critical problems found");
+    return `${lines.join("\n")}\n`;
+}
+/** Register the `doctor` command on `program`. */
+export function registerDoctorCommand(program, ctx) {
+    program
+        .command("doctor")
+        .description("check the local environment (offline) and report problems")
+        .option("--json", "output as JSON")
+        .action(async (opts) => {
+        const report = await collectDoctorReport(makeDefaultDoctorDeps(ctx));
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify(report)}\n`);
+        }
+        else {
+            ctx.stdout.write(renderDoctorReport(report));
+        }
+        if (!report.ok)
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/ext-format.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure, ANSI-free, total formatters for the budget/authoring/learning result
+ * types. Mirrors `../format.ts` for the versioning subsystem. Never throws.
+ */
+import type { BudgetStatusView, CostEstimate, LearnRunReport, LearnSource, LedgerEntry, SkillFrontmatter, AuthoringTestResult as TestResult } from "ultracode-core";
+/** Format a {@link BudgetStatusView} as an indented plain-text report. */
+export declare function formatBudgetStatus(s: BudgetStatusView): string;
+/** Format a {@link CostEstimate} (used standalone by `budget estimate`). */
+export declare function formatCostEstimate(e: CostEstimate): string;
+/** Format a budget ledger ({@link LedgerEntry}[]) as a chronological list. */
+export declare function formatLedger(entries: ReadonlyArray<LedgerEntry>): string;
+/** Format a list of skills ({@link SkillFrontmatter}[]). */
+export declare function formatSkillList(skills: ReadonlyArray<SkillFrontmatter>): string;
+/** Format a {@link TestResult} with a per-check ✓/✗ breakdown. */
+export declare function formatTestResult(t: TestResult): string;
+/** Format a list of learn sources ({@link LearnSource}[]). */
+export declare function formatSourceList(sources: ReadonlyArray<LearnSource>): string;
+/** Format a {@link LearnRunReport} after an executed learn run. */
+export declare function formatLearnReport(r: LearnRunReport): string;
+/** Truncate a free-form block (rationale/diff) for display. */
+export declare function formatBlock(label: string, text: string): string;
+//# sourceMappingURL=ext-format.d.ts.map

package/dist/commands/ext-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-format.d.ts","sourceRoot":"","sources":["../../src/commands/ext-format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,mBAAmB,IAAI,UAAU,EAClC,MAAM,gBAAgB,CAAC;AAexB,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAc9D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAiB1D;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAWxE;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAO/E;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAMtD;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAQ5E;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAS3D;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/D"}

package/dist/commands/ext-format.js

@@ -0,0 +1,115 @@
+/**
+ * Pure, ANSI-free, total formatters for the budget/authoring/learning result
+ * types. Mirrors `../format.ts` for the versioning subsystem. Never throws.
+ */
+import { truncate } from "ultracode-shared";
+/** Cap applied to free-form blocks. */
+const MAX_BLOCK_CHARS = 10_000;
+/** Format a USD amount with two decimals (total; clamps non-finite to 0). */
+function usd(n) {
+    return `$${(Number.isFinite(n) ? n : 0).toFixed(2)}`;
+}
+/** Format a EUR amount with two decimals. */
+function eur(n) {
+    return `${(Number.isFinite(n) ? n : 0).toFixed(2)} EUR`;
+}
+/** Format a {@link BudgetStatusView} as an indented plain-text report. */
+export function formatBudgetStatus(s) {
+    const lines = ["Budget Status"];
+    if (s.periodStart !== undefined)
+        lines.push(`  Period start: ${s.periodStart}`);
+    lines.push(`  Spent:     ${usd(s.spentUsd)}`);
+    lines.push(`  Cap:       ${s.capUsd === null ? "(none)" : usd(s.capUsd)}`);
+    lines.push(`  Remaining: ${usd(s.remainingUsd)}`);
+    if (s.entries !== undefined)
+        lines.push(`  Ledger entries: ${s.entries}`);
+    if (s.byCategory && Object.keys(s.byCategory).length > 0) {
+        lines.push("  By category:");
+        for (const [cat, amount] of Object.entries(s.byCategory)) {
+            lines.push(`    - ${cat}: ${usd(amount)}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a {@link CostEstimate} (used standalone by `budget estimate`). */
+export function formatCostEstimate(e) {
+    const lines = ["Cost Estimate"];
+    if (e.pages !== undefined)
+        lines.push(`  Pages: ${e.pages}`);
+    lines.push(`  Tokens: ${e.tokensIn} in / ${e.tokensOut} out`);
+    lines.push(`  USD range: ${usd(e.usdLow)} – ${usd(e.usdHigh)}`);
+    lines.push(`  EUR: ${eur(e.eur)} (fx ${e.fxRate})`);
+    if (e.byModel.length > 0) {
+        lines.push("  By model:");
+        for (const m of e.byModel) {
+            lines.push(`    - ${m.model}: ${m.tokensIn} in / ${m.tokensOut} out → ${usd(m.usd)}`);
+        }
+    }
+    const assumptions = e.assumptions.join("; ").trim();
+    if (assumptions !== "") {
+        lines.push(`  Assumptions: ${truncate(assumptions, 400)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a budget ledger ({@link LedgerEntry}[]) as a chronological list. */
+export function formatLedger(entries) {
+    if (entries.length === 0)
+        return "(no ledger entries)\n";
+    const lines = [`Budget History — ${entries.length} entr${entries.length === 1 ? "y" : "ies"}`];
+    for (const e of entries) {
+        const model = e.model !== undefined ? ` ${e.model}` : "";
+        const note = e.note !== undefined && e.note !== "" ? ` — ${truncate(e.note, 120)}` : "";
+        lines.push(`  ${e.ts} [${e.category}]${model} est ${usd(e.estimatedUsd)} / act ${usd(e.actualUsd)}${note}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a list of skills ({@link SkillFrontmatter}[]). */
+export function formatSkillList(skills) {
+    if (skills.length === 0)
+        return "(no skills)\n";
+    const lines = [`Skills — ${skills.length}`];
+    for (const s of skills) {
+        lines.push(`  ${s.name} v${s.version} [${s.status}] (${s.catalog}) — ${truncate(s.description, 80)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a {@link TestResult} with a per-check ✓/✗ breakdown. */
+export function formatTestResult(t) {
+    const lines = [`Test Result — ${t.passed ? "✓ PASSED" : "✗ FAILED"}`];
+    for (const c of t.checks) {
+        lines.push(`  ${c.passed ? "✓" : "✗"} ${c.name} — ${truncate(c.detail, 200)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a list of learn sources ({@link LearnSource}[]). */
+export function formatSourceList(sources) {
+    if (sources.length === 0)
+        return "(no learning sources)\n";
+    const lines = [`Learning Sources — ${sources.length}`];
+    for (const s of sources) {
+        const last = s.lastProcessed !== undefined ? ` last ${s.lastProcessed}` : " never processed";
+        lines.push(`  ${s.id} [${s.catalog}/${s.schedule}] ${s.url}${last}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Format a {@link LearnRunReport} after an executed learn run. */
+export function formatLearnReport(r) {
+    const lines = [
+        `Learn Run — ${r.sourceId}`,
+        `  Pages: ${r.pagesChecked} checked, ${r.notModified} not-modified, ${r.unchanged} unchanged, ${r.processed} processed, ${r.errors} error(s)`,
+        `  Skills: ${r.skillsCreated} created, ${r.skillsUpdated} updated`,
+        `  Cost: est ${usd(r.estimatedUsd)} / act ${usd(r.actualUsd)}`,
+        `  Window: ${r.startedAt} → ${r.finishedAt}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** Truncate a free-form block (rationale/diff) for display. */
+export function formatBlock(label, text) {
+    if (text.trim() === "")
+        return "";
+    return `${label}:\n${truncate(text, MAX_BLOCK_CHARS)
+        .split(/\r?\n/)
+        .map((l) => `  ${l}`)
+        .join("\n")}\n`;
+}
+//# sourceMappingURL=ext-format.js.map

package/dist/commands/ext-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-format.js","sourceRoot":"","sources":["../../src/commands/ext-format.ts"],"names":[],"mappings":"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"}

package/dist/commands/ext-helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers for the budget/authoring/learning command groups.
+ *
+ * The `ultracode-core` `UltraCode` facade now exposes the additive
+ * `budget` / `authoring` / `learning` sub-APIs directly (Modules A/B/C of
+ * v1.2.0), so these helpers simply create/dispose a facade and narrow to the
+ * relevant sub-API — no casts, no ambient shapes.
+ */
+import type { BudgetFacade, AuthoringFacade, LearningFacade } from "ultracode-core";
+import type { CliContext, UltraCodeFacade } from "../context.js";
+/** The facade as consumed by the budget/authoring/learning command groups. */
+export type ExtendedFacade = UltraCodeFacade;
+/**
+ * Run `fn` against a freshly created facade, always disposing it afterwards
+ * (even on throw). Mirrors the `withFacade` pattern of the other command
+ * groups.
+ */
+export declare function withExtFacade<T>(ctx: CliContext, fn: (facade: ExtendedFacade) => Promise<T>): Promise<T>;
+/** Narrow accessor for the budget sub-API. */
+export declare function budgetOf(facade: ExtendedFacade): BudgetFacade;
+/** Narrow accessor for the authoring sub-API. */
+export declare function authoringOf(facade: ExtendedFacade): AuthoringFacade;
+/** Narrow accessor for the learning sub-API. */
+export declare function learningOf(facade: ExtendedFacade): LearningFacade;
+//# sourceMappingURL=ext-helpers.d.ts.map

package/dist/commands/ext-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/ext-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,8CAA8C;AAC9C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAE7D;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAEnE;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAEjE"}

package/dist/commands/ext-helpers.js

@@ -0,0 +1,36 @@
+/**
+ * Shared helpers for the budget/authoring/learning command groups.
+ *
+ * The `ultracode-core` `UltraCode` facade now exposes the additive
+ * `budget` / `authoring` / `learning` sub-APIs directly (Modules A/B/C of
+ * v1.2.0), so these helpers simply create/dispose a facade and narrow to the
+ * relevant sub-API — no casts, no ambient shapes.
+ */
+import { safeDispose } from "../context.js";
+/**
+ * Run `fn` against a freshly created facade, always disposing it afterwards
+ * (even on throw). Mirrors the `withFacade` pattern of the other command
+ * groups.
+ */
+export async function withExtFacade(ctx, fn) {
+    const facade = await ctx.createFacade({ cwd: ctx.cwd });
+    try {
+        return await fn(facade);
+    }
+    finally {
+        await safeDispose(facade);
+    }
+}
+/** Narrow accessor for the budget sub-API. */
+export function budgetOf(facade) {
+    return facade.budget;
+}
+/** Narrow accessor for the authoring sub-API. */
+export function authoringOf(facade) {
+    return facade.authoring;
+}
+/** Narrow accessor for the learning sub-API. */
+export function learningOf(facade) {
+    return facade.learning;
+}
+//# sourceMappingURL=ext-helpers.js.map

package/dist/commands/ext-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-helpers.js","sourceRoot":"","sources":["../../src/commands/ext-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAK5C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAe,EACf,EAA0C;IAE1C,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,QAAQ,CAAC,MAAsB;IAC7C,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,WAAW,CAAC,MAAsB;IAChD,OAAO,MAAM,CAAC,SAAS,CAAC;AAC1B,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,MAAsB;IAC/C,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC"}

package/dist/commands/learn.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `ultracode learn sources list|add <url>|remove <id>` and
+ * `ultracode learn run [sourceId]` / `ultracode learn schedule`.
+ *
+ * Documentation-learning commands backed by the facade's `learning` sub-API
+ * (Module C). `learn run` ALWAYS prints the budget cost report first
+ * (`budget.formatReport(estimate, decision)`), then requires explicit approval:
+ * `--yes`, or an interactive YES on a TTY. Without a TTY and without `--yes`
+ * the run is aborted before any network/LLM work happens.
+ *
+ * Every subcommand supports `--json` where it makes sense.
+ */
+import type { Command } from "commander";
+import type { CliContext } from "../context.js";
+/**
+ * Confirmation surface for `learn run` — injectable so tests stay offline and
+ * deterministic. The default reads a single line from `ctx.stdin`.
+ */
+export interface ConfirmIO {
+    /** True when an interactive prompt is possible (a TTY on both ends). */
+    interactive: boolean;
+    /** Ask a yes/no question; resolves true only for an affirmative answer. */
+    confirm(question: string): Promise<boolean>;
+}
+/** Build the default {@link ConfirmIO} from the context's stdin/stdout. */
+export declare function createConfirmIO(ctx: CliContext): ConfirmIO;
+/** Register the `learn` command group on `program`. */
+export declare function registerLearnCommands(program: Command, ctx: CliContext, io?: ConfirmIO): void;
+//# sourceMappingURL=learn.d.ts.map

package/dist/commands/learn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learn.d.ts","sourceRoot":"","sources":["../../src/commands/learn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqBhD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAID,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAiB1D;AAqBD,uDAAuD;AACvD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,UAAU,EACf,EAAE,GAAE,SAAgC,GACnC,IAAI,CA+HN"}

package/dist/commands/learn.js

@@ -0,0 +1,190 @@
+/**
+ * `ultracode learn sources list|add <url>|remove <id>` and
+ * `ultracode learn run [sourceId]` / `ultracode learn schedule`.
+ *
+ * Documentation-learning commands backed by the facade's `learning` sub-API
+ * (Module C). `learn run` ALWAYS prints the budget cost report first
+ * (`budget.formatReport(estimate, decision)`), then requires explicit approval:
+ * `--yes`, or an interactive YES on a TTY. Without a TTY and without `--yes`
+ * the run is aborted before any network/LLM work happens.
+ *
+ * Every subcommand supports `--json` where it makes sense.
+ */
+import process from "node:process";
+import { ValidationError } from "ultracode-shared";
+import { budgetOf, learningOf, withExtFacade } from "./ext-helpers.js";
+import { formatLearnReport, formatSourceList } from "./ext-format.js";
+const AFFIRMATIVE = new Set(["y", "yes", "j", "ja"]);
+/** Build the default {@link ConfirmIO} from the context's stdin/stdout. */
+export function createConfirmIO(ctx) {
+    const interactive = ctx.stdin.isTTY === true && ctx.stdout.isTTY === true;
+    return {
+        interactive,
+        confirm: (question) => new Promise((resolve) => {
+            ctx.stdout.write(question);
+            const onData = (chunk) => {
+                ctx.stdin.removeListener("data", onData);
+                ctx.stdin.pause?.();
+                const answer = (typeof chunk === "string" ? chunk : chunk.toString("utf8")).trim().toLowerCase();
+                resolve(AFFIRMATIVE.has(answer));
+            };
+            ctx.stdin.resume?.();
+            ctx.stdin.on("data", onData);
+        }),
+    };
+}
+/** Estimate → decision wrapper; falls back to a permissive decision if the
+ * facade does not expose `check` (so the report still renders). */
+async function decideFor(facade, estimate) {
+    const budget = budgetOf(facade);
+    if (typeof budget.check === "function") {
+        return budget.check(estimate, "learning");
+    }
+    return {
+        allowed: true,
+        requiresApproval: true,
+        remainingUsd: 0,
+        capUsd: null,
+        reason: "budget.check unavailable; manual approval required",
+    };
+}
+/** Register the `learn` command group on `program`. */
+export function registerLearnCommands(program, ctx, io = createConfirmIO(ctx)) {
+    const learn = program.command("learn").description("learn from documentation sources");
+    /* ---------------------------- sources ----------------------------- */
+    const sources = learn.command("sources").description("manage learning sources");
+    sources
+        .command("list")
+        .description("list registered documentation sources")
+        .option("--json", "output as JSON")
+        .action(async (opts) => withExtFacade(ctx, async (facade) => {
+        const list = await learningOf(facade).sources.list();
+        ctx.stdout.write(opts.json ? `${JSON.stringify(list)}\n` : formatSourceList(list));
+    }));
+    sources
+        .command("add")
+        .description("register a new documentation source")
+        .argument("<url>", "documentation root URL or sitemap")
+        .option("--catalog <catalog>", "catalog to file generated skills under")
+        .option("--schedule <schedule>", 'refresh schedule ("on-demand" | "annual" | cron)')
+        .option("--scope <scope>", "URL path scope filter")
+        .option("--locale <locale>", "default locale (e.g. de-de)")
+        .option("--json", "output as JSON")
+        .action(async (url, opts) => withExtFacade(ctx, async (facade) => {
+        if (url.trim() === "")
+            throw new ValidationError("Source URL must not be empty.");
+        const source = await learningOf(facade).sources.add({
+            url,
+            ...(opts.catalog !== undefined ? { catalog: opts.catalog } : {}),
+            ...(opts.schedule !== undefined ? { schedule: opts.schedule } : {}),
+            ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+            ...(opts.locale !== undefined ? { localeDefault: opts.locale } : {}),
+        });
+        ctx.stdout.write(opts.json ? `${JSON.stringify(source)}\n` : `✓ added source ${source.id} (${source.url})\n`);
+    }));
+    sources
+        .command("remove")
+        .description("remove a registered documentation source")
+        .argument("<id>", "source id")
+        .option("--json", "output as JSON")
+        .action(async (id, opts) => withExtFacade(ctx, async (facade) => {
+        const removed = await learningOf(facade).sources.remove(id);
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify({ id, removed })}\n`);
+        }
+        else {
+            ctx.stdout.write(removed ? `✓ removed source ${id}\n` : `source ${id} not found\n`);
+        }
+        if (!removed)
+            process.exitCode = 1;
+    }));
+    /* ------------------------------ run ------------------------------- */
+    learn
+        .command("run")
+        .description("plan and (after approval) run learning for a source — shows the cost report first")
+        .argument("[sourceId]", "source id; required unless exactly one source exists")
+        .option("--yes", "approve the run without an interactive prompt")
+        .option("--json", "output as JSON")
+        .action(async (sourceId, opts) => withExtFacade(ctx, async (facade) => {
+        const learning = learningOf(facade);
+        const id = await resolveSourceId(facade, sourceId);
+        const plan = await learning.plan(id);
+        const decision = await decideFor(facade, plan.estimate);
+        // ALWAYS show the cost report before doing anything else.
+        ctx.stdout.write(budgetOf(facade).formatReport(plan.estimate, decision));
+        if (!decision.allowed) {
+            ctx.stdout.write(`✗ run blocked by budget: ${decision.reason}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const approved = await approveRun(ctx, io, opts.yes === true);
+        if (!approved) {
+            // Non-TTY without --yes, or an explicit "no": abort WITHOUT network/LLM.
+            process.exitCode = 1;
+            return;
+        }
+        const report = await learning.run(id, {
+            approved: true,
+            onProgress: (p) => {
+                if (opts.json !== true && p.total > 0) {
+                    ctx.stdout.write(`  …${p.done}/${p.total}${p.url ? ` ${p.url}` : ""}\n`);
+                }
+            },
+        });
+        ctx.stdout.write(opts.json ? `${JSON.stringify(report)}\n` : formatLearnReport(report));
+    }));
+    /* ---------------------------- schedule ---------------------------- */
+    learn
+        .command("schedule")
+        .description("show each source's refresh schedule")
+        .option("--json", "output as JSON")
+        .action(async (opts) => withExtFacade(ctx, async (facade) => {
+        const list = await learningOf(facade).sources.list();
+        const rows = list.map((s) => ({
+            id: s.id,
+            schedule: s.schedule,
+            lastProcessed: s.lastProcessed ?? null,
+        }));
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify(rows)}\n`);
+            return;
+        }
+        if (rows.length === 0) {
+            ctx.stdout.write("(no learning sources)\n");
+            return;
+        }
+        ctx.stdout.write("Learning Schedule\n");
+        for (const r of rows) {
+            ctx.stdout.write(`  ${r.id}: ${r.schedule} (last ${r.lastProcessed ?? "never"})\n`);
+        }
+    }));
+}
+/** Resolve the source id, defaulting to the only source when omitted. */
+async function resolveSourceId(facade, sourceId) {
+    if (sourceId !== undefined && sourceId.trim() !== "")
+        return sourceId;
+    const list = await learningOf(facade).sources.list();
+    if (list.length === 1 && list[0] !== undefined)
+        return list[0].id;
+    if (list.length === 0)
+        throw new ValidationError("No learning sources registered. Add one with `learn sources add`.");
+    throw new ValidationError(`Multiple sources registered; specify one: ${list.map((s) => s.id).join(", ")}`);
+}
+/**
+ * Decide whether the run is approved: `--yes` short-circuits to true; otherwise
+ * an interactive YES is required. Without a TTY and without `--yes`, a hint is
+ * printed and the run is refused.
+ */
+async function approveRun(ctx, io, yes) {
+    if (yes)
+        return true;
+    if (!io.interactive) {
+        ctx.stdout.write("Refusing to start without approval: pass --yes (no interactive terminal available).\n");
+        return false;
+    }
+    const ok = await io.confirm("Proceed with the learn run? [y/N] ");
+    if (!ok)
+        ctx.stdout.write("Aborted.\n");
+    return ok;
+}
+//# sourceMappingURL=learn.js.map