co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/cli/commands/config.js

@@ -0,0 +1,220 @@
+/** The `config` command: read and edit the user config without opening the
+ * file (CORE-22, F12). `set` is `config set` under its own name, so both share
+ * the mapping and masking here.
+ *
+ * The key list is derived from `UserConfig` at runtime where possible: a
+ * kebab-case name maps to the camelCase JSON key, so a new field needs no
+ * second place to be registered. `secretFields` decides what is masked. */
+import { configPath, getCacheDir, readConfig, reposDir } from "../../config.js";
+import { getEnv } from "../../util/runtime.js";
+import { die } from "../error.js";
+import { renderCommandHelp } from "./registry.js";
+/** Fields whose value must never be printed in full. */
+export const SECRET_FIELDS = new Set([
+    "token",
+    "githubPat",
+    "githubAppPrivateKey",
+    "githubWebhookSecret",
+    "githubOAuthClientSecret",
+    "remoteToken",
+    "dashboardPasswordHash",
+]);
+/** `lowModel` -> `low-model`. The inverse of {@link configKey}. */
+export function flagName(field) {
+    return field.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/** `low-model` -> `lowModel`. */
+export function configKey(name) {
+    return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/** Masks a secret for display: 12 characters or more keep the last four so a
+ * user can tell two keys apart, anything shorter is fully hidden. `password`
+ * is handled by the caller because it is a hash, not a key. */
+export function maskSecret(value) {
+    if (value.length >= 12)
+        return `••••${value.slice(-4)}`;
+    return "••••";
+}
+/** The env var that supplies each field, mirroring args.ts. Only the fields
+ * that actually read env are listed. */
+export const ENV_BY_FIELD = {
+    token: ["CO_MAINTAINER_TOKEN", "OPENROUTER_API_KEY", "HETZNER_API_KEY"],
+    githubPat: ["GITHUB_TOKEN", "GH_TOKEN"],
+    ai: ["CO_MAINTAINER_AI"],
+    auth: ["CO_MAINTAINER_AUTH"],
+    lowModel: ["OPENROUTER_LOW_MODEL", "HETZNER_LOW_MODEL", "LOW_MODEL"],
+    highModel: ["OPENROUTER_HIGH_MODEL", "HETZNER_HIGH_MODEL", "HIGH_MODEL"],
+    webhookUrl: ["CM_WEBHOOK_URL"],
+    reviewBlocking: ["CO_MAINTAINER_REVIEW_BLOCKING"],
+};
+/** Renders one field for people. A secret is masked; the password hash, which
+ * nobody can use, only reports whether it is set. */
+export function displayValue(field, value) {
+    if (field === "dashboardPasswordHash") {
+        return value === undefined ? "not set" : "set";
+    }
+    if (value === undefined)
+        return "";
+    if (SECRET_FIELDS.has(field))
+        return maskSecret(String(value));
+    if (Array.isArray(value))
+        return value.join(",");
+    if (typeof value === "object" && value !== null)
+        return JSON.stringify(value);
+    return String(value);
+}
+/** Values a field falls back to when neither env nor the file sets it, so
+ * `config list` can say a row is the default rather than leaving it out. */
+export const DEFAULTS = {
+    reviewBlocking: "model",
+};
+/** Every top-level UserConfig key with a value and where it came from. */
+export function configRows(config) {
+    const rows = [];
+    for (const field of KNOWN_FIELDS) {
+        const fromEnv = (ENV_BY_FIELD[field] ?? []).find((name) => getEnv(name) !== undefined);
+        const fileValue = config[field];
+        const value = fromEnv ? getEnv(fromEnv) : fileValue;
+        if (value === undefined) {
+            const fallback = DEFAULTS[field];
+            if (fallback === undefined)
+                continue;
+            rows.push({
+                key: flagName(field),
+                field,
+                value: fallback,
+                source: "default",
+            });
+            continue;
+        }
+        rows.push({
+            key: flagName(field),
+            field,
+            value: displayValue(field, value),
+            source: fromEnv ? "env" : "file",
+        });
+    }
+    if (config.repos && Object.keys(config.repos).length > 0) {
+        rows.push({
+            key: "repos",
+            field: "repos",
+            value: `${Object.keys(config.repos).length} repo(s)`,
+            source: "file",
+        });
+    }
+    return rows.sort((a, b) => a.key.localeCompare(b.key));
+}
+function printList(config) {
+    const rows = configRows(config);
+    const width = Math.max(...rows.map((row) => row.key.length));
+    for (const row of rows) {
+        console.log(`${row.key.padEnd(width)}  ${row.value.padEnd(24)}${row.source}`);
+    }
+}
+/** Resolves a user-supplied key name to its field. Accepts kebab-case
+ * (`low-model`), camelCase (`lowModel`), and rejects anything that is not a
+ * `UserConfig` key, so a typo cannot silently read undefined. */
+export function resolveField(name) {
+    const field = configKey(name);
+    const match = KNOWN_FIELDS.find((known) => known === field || known === name);
+    if (!match)
+        die(`Unknown config key: ${name}`);
+    return match;
+}
+/** The scalar `UserConfig` keys `config` can read and write. `repos` and
+ * `defaults` are nested maps, not settings, so they are not listed.
+ * `satisfies` makes this the type's own vocabulary: a name that is not a
+ * `UserConfig` key is a compile error rather than a silently undefined read. */
+export const KNOWN_FIELDS = [
+    "auth",
+    "ai",
+    "lowModel",
+    "highModel",
+    "token",
+    "githubPat",
+    "githubAppId",
+    "githubAppPrivateKey",
+    "githubAppPrivateKeyPath",
+    "githubWebhookSecret",
+    "webhookUrl",
+    "githubOAuthClientId",
+    "githubOAuthClientSecret",
+    "githubOAuthAllowedUser",
+    "passwordAuthDisabled",
+    "githubAuthEnabled",
+    "dashboardPasswordHash",
+    "maxConcurrentJobs",
+    "reviewBlocking",
+    "remoteHost",
+    "remoteToken",
+    "remoteNoticeShownFor",
+    "remoteSyncTimeoutSeconds",
+    "maxConcurrentRemoteReviewsPerToken",
+    "remoteToolOutputMaxChars",
+];
+/** `co-maintainer config <sub> ...`. `set` is handled by runSet, which this
+ * command delegates to so there is one implementation of the write rules. */
+export async function runConfig(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+        console.log(renderCommandHelp("config") ??
+            "Usage: co-maintainer config <list|get|set|unset|path>");
+        return;
+    }
+    const config = readConfig();
+    if (sub === "list") {
+        printList(config);
+        return;
+    }
+    if (sub === "path") {
+        console.log(configPath());
+        if (rest.includes("--all")) {
+            console.log(reposDir());
+            console.log(`${getCacheDir()}/co-maintainer`);
+        }
+        return;
+    }
+    if (sub === "get") {
+        const name = rest.find((arg) => !arg.startsWith("-"));
+        if (!name)
+            die("Usage: co-maintainer config get <key>");
+        const field = resolveField(name);
+        const fromEnv = (ENV_BY_FIELD[field] ?? []).find((envName) => getEnv(envName) !== undefined);
+        const effective = fromEnv
+            ? getEnv(fromEnv)
+            : (config[field] ?? DEFAULTS[field]);
+        if (effective === undefined) {
+            die(`No value for ${name}.`);
+        }
+        // A machine reading this wants the real value, not a mask, which is why
+        // `get` prints it plainly and `list` is what a screen-share shows.
+        console.log(String(displayValue(field, effective)));
+        return;
+    }
+    if (sub === "unset") {
+        const name = rest.find((arg) => !arg.startsWith("-"));
+        if (!name)
+            die("Usage: co-maintainer config unset <key>");
+        const field = resolveField(name);
+        const { runSet } = await import("./set.js");
+        await runSet([`--unset=${field}`, "--no-verify"]);
+        return;
+    }
+    if (sub === "set") {
+        const { runSet } = await import("./set.js");
+        // `config set key value` and `config set --key=value` both work. The
+        // verification in runSet is left on: a key or model typed through this
+        // path deserves the same check as one typed through `set`.
+        const positional = rest.filter((arg) => !arg.startsWith("-"));
+        if (positional.length >= 2 && !rest[0]?.startsWith("-")) {
+            const [name, ...valueParts] = positional;
+            const field = resolveField(name);
+            const value = valueParts.join(" ");
+            await runSet([`--${flagName(field)}=${value}`]);
+            return;
+        }
+        await runSet(rest);
+        return;
+    }
+    die(`Unknown config subcommand: ${sub}`);
+}

package/dist/src/cli/commands/probe.js

@@ -1,112 +1,22 @@
-import { clientFor } from "../../services/setup.js";
-import { analyzeProbe } from "../../knowledge/probe.js";
+import { clientFor, runInitOrRemake } from "../../services/setup.js";
+import { probePlan } from "../../services/probe.js";
+import { log, startHeartbeat } from "../../util/log.js";
+import { estimateInit, readJobHistory } from "../../ai/estimate.js";
+import { loadPrices } from "../../ai/pricing.js";
 import { cacheSet } from "../../store/cache_db.js";
-import { log, startHeartbeat, timed } from "../../util/log.js";
 export async function runProbe(options) {
     const operationStarted = performance.now();
     const stopHeartbeat = startHeartbeat("probing repository");
     const client = clientFor(options);
     log("probe", `reading ${options.repo} via ${options.auth}`);
-    const meta = await timed("probe repository metadata", options.logTime, () => client.request(`repos/${options.repo}`));
-    let latestReleaseAt = "";
-    log("probe", "reading release metadata");
-    try {
-        const releases = await timed("probe release metadata", options.logTime, () => client.pages(`repos/${options.repo}/releases?per_page=1`, 1));
-        latestReleaseAt = String(releases[0]?.published_at ?? releases[0]?.created_at ?? "");
-    }
-    catch {
-        // Release metadata is an optional probe signal.
-    }
-    log("probe", "reading pull request list");
-    const pulls = await timed("probe pull request listing", options.logTime, () => client.pages(`repos/${options.repo}/pulls?state=all&sort=updated&direction=desc`, undefined, (page, fetched) => log("probe", `pull request listing · page ${page} · fetched ${fetched} · total unknown`)));
-    const yearBuckets = new Map();
-    for (const pull of pulls) {
-        const year = new Date(String(pull.updated_at)).getFullYear();
-        yearBuckets.set(year, [...(yearBuckets.get(year) ?? []), pull]);
-    }
-    const sampleTargets = new Map();
-    for (const pull of pulls.slice(0, 30)) {
-        sampleTargets.set(Number(pull.number), pull);
-    }
-    for (const yearPulls of yearBuckets.values()) {
-        for (const pull of yearPulls.slice(0, 3)) {
-            sampleTargets.set(Number(pull.number), pull);
-        }
-    }
-    const samplePulls = [...sampleTargets.values()];
-    const detailSamples = [];
-    log("probe", `sampling ${samplePulls.length} pull request details · concurrency=${options.ghConcurrent}`);
-    await timed("probe PR detail sampling", options.logTime, async () => {
-        const details = new Array(samplePulls.length);
-        let cursor = 0;
-        let completed = 0;
-        const worker = async () => {
-            while (cursor < samplePulls.length) {
-                const index = cursor++;
-                const pull = samplePulls[index];
-                try {
-                    details[index] = await client.request(`repos/${options.repo}/pulls/${Number(pull.number)}`);
-                }
-                catch {
-                    // A missing detail should not invalidate the rest of the probe.
-                }
-                finally {
-                    completed++;
-                    log("probe", `PR detail sampling · ${completed}/${samplePulls.length} · ${Math.round((completed / samplePulls.length) * 100)}%`);
-                }
-            }
-        };
-        await Promise.all(Array.from({ length: Math.min(options.ghConcurrent, samplePulls.length) }, worker));
-        detailSamples.push(...details.filter((detail) => !!detail));
+    const plan = await probePlan(client, options.repo, {
+        ghConcurrent: options.ghConcurrent,
+        logTime: options.logTime,
+        log: (message) => log("probe", message),
     });
-    const branch = String(meta.default_branch ?? "main");
-    log("probe", `sampled ${detailSamples.length} PR details; reading ${branch} commit history`);
-    const commits = await timed("probe commit history", options.logTime, () => client.pages(`repos/${options.repo}/commits?sha=${encodeURIComponent(branch)}`, undefined, (page, fetched) => log("probe", `commit history · page ${page} · fetched ${fetched} · total unknown`)));
-    const analysis = await timed("probe analysis", options.logTime, async () => analyzeProbe({ ...meta, latest_release_at: latestReleaseAt }, pulls, detailSamples, commits));
-    const recommendation = ["--include-codebase"];
-    if (analysis.includePullRequests) {
-        recommendation.push("--include-pull-requests");
-    }
-    if (analysis.includePullRequestChanges) {
-        recommendation.push("--include-pull-request-changes");
-    }
-    if (analysis.includeCommitHistory) {
-        recommendation.push("--include-commit-history");
-    }
-    if (pulls.length || Boolean(meta.has_issues)) {
-        recommendation.push("--include-how-repo-works");
-    }
-    if (analysis.maxPullRequestChangeLines) {
-        recommendation.push(`--max-pull-request-change-lines=${analysis.maxPullRequestChangeLines}`);
-    }
-    if (analysis.maxPrMonths) {
-        recommendation.push(`--max-pr-months=${analysis.maxPrMonths}`);
-    }
-    if (analysis.maxCommits) {
-        recommendation.push(`--max-commits=${analysis.maxCommits}`);
-    }
-    const command = [
-        "co-maintainer",
-        "init",
-        options.repo,
-        ...recommendation,
-    ].join(" ");
-    const report = {
-        repo: options.repo,
-        ...analysis.report,
-        recommendations: {
-            includePullRequests: analysis.includePullRequests,
-            includePullRequestChanges: analysis.includePullRequestChanges,
-            includeCommitHistory: analysis.includeCommitHistory,
-            maxPrMonths: analysis.maxPrMonths ?? "all",
-            maxCommits: analysis.maxCommits ?? "all",
-            maxPullRequestChangeLines: analysis.maxPullRequestChangeLines ?? "all",
-        },
-        reasons: analysis.reasons,
-        recommendedCommand: command,
-        createdAt: new Date().toISOString(),
-    };
-    await timed("probe report write", options.logTime, () => cacheSet("probe", options.repo, JSON.stringify(report)));
+    const analysis = plan.analysis;
+    const command = plan.command;
+    await cacheSet("probe", options.repo, JSON.stringify(plan.report));
     console.log(`\nrecommended\n  ${command}`);
     console.log("\nresearch");
     console.log(`  PRs: ${analysis.report.pullRequests} · sampled: ${analysis.report.sampledPullRequests}`);
@@ -114,9 +24,66 @@ export async function runProbe(options) {
     console.log(`  windows: PR months=${analysis.maxPrMonths ?? "all"} · commits=${analysis.maxCommits ?? "all"} · diff lines=${analysis.maxPullRequestChangeLines ?? "all"}`);
     for (const reason of analysis.reasons)
         console.log(`  - ${reason}`);
-    console.log("  This is a recommendation only; probe does not create or modify a skill.");
+    // The estimate is separate from the recommendation: the flags say what to
+    // read, this says what that costs in time and dollars (CORE-24). Prices are
+    // only fetched when an OpenRouter model would actually be billed, so a
+    // plain `--ai=none` probe makes no network call.
+    const needsPrices = options.ai === "openrouter" &&
+        Boolean(options.lowModel && options.highModel);
+    const [prices, history] = await Promise.all([
+        needsPrices
+            ? loadPrices()
+            : Promise.resolve({ prices: new Map(), source: "unavailable" }),
+        readJobHistory(options.repo),
+    ]);
+    const estimate = estimateInit({
+        pullRequests: analysis.includePullRequests
+            ? Number(analysis.report.pullRequests ?? 0)
+            : 0,
+        includeCodebase: analysis.includePullRequests,
+        lowModel: options.lowModel,
+        highModel: options.highModel,
+        prices: prices.prices,
+        history,
+    });
+    console.log("\nestimate");
+    console.log(`  AI jobs: ${estimate.extract} extract + ${estimate.synth} synth`);
+    console.log(`  tokens: ${range(estimate.tokensIn)} in · ${range(estimate.tokensOut)} out`);
+    console.log(`  time: ${secondsRange(estimate.seconds)}s`);
+    if (estimate.usd) {
+        console.log(`  cost: $${estimate.usd[0].toFixed(4)}-$${estimate.usd[1].toFixed(4)}`);
+    }
+    else if (needsPrices && prices.source === "unavailable") {
+        console.log("  cost: unknown (could not read OpenRouter prices)");
+    }
+    else {
+        console.log("  cost: set --ai=openrouter with both models to estimate dollars");
+    }
+    console.log(`  basis: ${estimate.basis === "history"
+        ? "this repository's recorded jobs"
+        : "the cm-dx-lab calibration"}; an estimate, not a bill`);
+    console.log("\nnext");
+    console.log(`  ${command}`);
+    console.log(`  or run it now: co-maintainer probe ${options.repo} --run`);
+    console.log("  Probe only reads. It does not write guides.");
     if (options.logTime) {
         console.log(`  total time: ${((performance.now() - operationStarted) / 1000).toFixed(2)}s`);
     }
     stopHeartbeat();
+    if (options.run) {
+        // Same process, no re-spawn: the dashboard learned that lesson already
+        // (the second path had its own failure modes). `init` inherits the
+        // recommended flags, which is exactly the command printed above.
+        options.command = "init";
+        await runInitOrRemake(options);
+    }
+}
+/** `120-190` for a token range, rounded to whole tokens. */
+function range([low, high]) {
+    const round = (value) => Math.round(value).toLocaleString("en-US");
+    return `${round(low)}-${round(high)}`;
+}
+/** `8-14` for a seconds range, rounded to whole seconds. */
+function secondsRange([low, high]) {
+    return `${Math.round(low)}-${Math.round(high)}`;
 }

package/dist/src/cli/commands/registry.d.ts

@@ -0,0 +1,57 @@
+/** The command registry (CORE-20).
+ *
+ * One place that knows every command, its aliases, its usage lines, its flags
+ * and its examples. Everything the user reads as help is rendered from here,
+ * so a flag cannot drift out of the help and a command cannot be documented
+ * twice with different wording. It is also the source CORE-81 will export to
+ * the command reference, which is why it is data rather than template strings.
+ */
+export type FlagSpec = {
+    /** Without the leading dashes, e.g. `include-codebase`. */
+    name: string;
+    /** The value placeholder when the flag takes one, e.g. `N` in `--port=N`. */
+    value?: string;
+    default?: string;
+    description: string;
+};
+export type FlagGroup = {
+    title: string;
+    flags: FlagSpec[];
+};
+export type CommandSpec = {
+    name: string;
+    /** Other spellings that run the same handler. Hidden aliases stay out of the
+     * global help but still resolve. */
+    aliases?: string[];
+    /** A hidden command is resolvable but never listed. */
+    hidden?: boolean;
+    summary: string;
+    usage: string[];
+    groups: FlagGroup[];
+    examples: string[];
+    docs?: string;
+};
+export declare const COMMANDS: CommandSpec[];
+/** Every name a command answers to, including hidden aliases. */
+export declare function allNames(): string[];
+export declare function findCommand(name: string): CommandSpec | undefined;
+/** Commands listed in the global help. A hidden alias or command is resolvable
+ * but invisible. */
+export declare function visibleCommands(): CommandSpec[];
+/** Levenshtein distance, iterative and allocation-light: the help path runs it
+ * on every unknown token, and the strings are short. */
+export declare function levenshtein(a: string, b: string): number;
+/** The closest candidate within `maxDistance`, or undefined. Ties keep the
+ * first candidate, which is the declaration order in `COMMANDS`. */
+export declare function closest(input: string, candidates: string[], maxDistance?: number): string | undefined;
+/** `prob` becomes `Unknown command: prob. Did you mean probe?`. */
+export declare function unknownCommandMessage(input: string): string;
+/** `--jsno` becomes `Unknown option: --jsno. Did you mean --json?`. */
+export declare function unknownOptionMessage(input: string): string;
+/** The global help: every visible command with its one-line summary. */
+export declare function renderGlobalHelp(): string;
+/** One command's help: usage, flags grouped, examples, docs link. */
+export declare function renderCommandHelp(name: string): string | undefined;
+/** The registry as markdown, so CORE-81 can build the command reference from
+ * the same data the runtime help uses. */
+export declare function registryToMarkdown(): string;