ghostrail 0.15.2 → 0.17.0

package/dist/cli/commands.js

@@ -7,10 +7,11 @@ import { fileURLToPath } from "node:url";
 import { spawnCollect } from "../backend/proc.js";
 import { DEFAULT_BOARD_PORT, PORT_FALLBACK_ATTEMPTS, isAddressInUse, isValidPort, portCandidates, } from "../board/port.js";
 import { createBoardServer, isLoopback, normalizeToken } from "../board/server.js";
-import { buildProposal, writeProfile } from "../claude-profile/index.js";
+import { DEFAULT_CLAUDE_PINS, buildProposal, writeProfile } from "../claude-profile/index.js";
 import { parseDuration } from "../config/duration.js";
 import { parseConfig, parseMergedConfig } from "../config/load.js";
 import { createDashboardServer, defaultStateDir } from "../dashboard/index.js";
+import { hasFailure, renderDoctorJson, renderDoctorText, runDoctor, } from "../doctor/index.js";
 import { buildLoopDeps, buildRespondDeps, buildTriageDeps, repoGhRunner, resolveRepoSlug, } from "../factory/build.js";
 import { describeMigration, migrateLegacyStore, resolveWorkRepo, stateDirFor, } from "../factory/state.js";
 import { entryKey, findByPath, findForRepoResolving, replaceEntry, upsert, } from "../global/registry.js";
@@ -18,6 +19,7 @@ import { canonicalRepoId, localRepoId } from "../global/repo-id.js";
 import { GlobalStore, resolveGlobalDir } from "../global/store.js";
 import { DEFAULT_FACTORY_IMAGE, dockerBuildArgs, dockerDir, parseImageFlags, } from "../image/build.js";
 import { extractPlaceholders, isClean, missingSignals, repoPathFor, } from "../init/drift.js";
+import { mergeRegions, parseRegions, regionHashes } from "../init/regions.js";
 import { classify, hashContent, mergeManifest, readManifest, writeManifest, } from "../init/template.js";
 import { FileLock } from "../lock/file-lock.js";
 import { concurrencyAdvice } from "../loop/advice.js";
@@ -430,10 +432,49 @@ export async function cmdBoard(argv, streams, env = process.env, cwd = process.c
 }
 /** The cross-ghostrail dashboard's default port, one above the board's. */
 export const DEFAULT_DASHBOARD_PORT = 5051;
+/**
+ * The `owner/repo` slug for a registered ghostrail, for `gh --repo`.
+ *
+ * The registry's `repo` is the ghostrail's identity and is already canonical
+ * (`host/owner/name`), so it answers this without running anything. Two entries
+ * cannot: `local:<path>` has no remote by definition, and an entry written
+ * before repo identities existed has no `repo` at all. Both fall back to the
+ * checkout's origin, which is what `board` does with its one repo.
+ *
+ * Undefined is not a failure. It leaves `gh` to infer the repo from the
+ * checkout, exactly as an unscoped invocation always has.
+ */
+async function dashboardRepoSlug(entry) {
+    const repo = entry.repo;
+    if (repo !== undefined && !repo.startsWith("local:")) {
+        const parts = repo.split("/");
+        if (parts.length === 3)
+            return `${parts[1]}/${parts[2]}`;
+    }
+    return resolveBoardRepoSlug(entry.path);
+}
 /** Build the dashboard server's dependencies from the real environment. */
 function dashboardDeps(env, manager) {
     const store = globalStoreFor(env);
+    // A ghostrail's slug does not change while the dashboard runs, and resolving
+    // it can cost a `git` call. The page refetches PR status for every expanded
+    // row every 10s, so without this that cost recurs for as long as a row is
+    // open. Keyed on the identity, so two clones of one repo share the answer.
+    const slugs = new Map();
+    const slugFor = (entry) => {
+        const key = entryKey(entry);
+        const known = slugs.get(key);
+        if (known !== undefined)
+            return known;
+        const resolving = dashboardRepoSlug(entry);
+        slugs.set(key, resolving);
+        return resolving;
+    };
     return {
+        // Constructing this runs nothing; only a request that needs it spends a
+        // subprocess. A machine with no `gh` and no credentials still serves the
+        // whole dashboard, with PR status reported as unavailable.
+        prStatus: async (entry, prNumber) => new GhHost(repoGhRunner(entry.path), await slugFor(entry)).getPrStatus(prNumber),
         readRegistry: () => store.readRegistry(),
         writeRegistry: (entries) => store.writeRegistry(entries),
         health: ghostrailHealth,
@@ -1130,11 +1171,19 @@ async function promptPathsAt(configPath) {
  * `ghostrail init <template> --update`: take the template changes this repo
  * never edited, and name what a customized file is missing.
  *
- * Two jobs split by whether the answer is mechanical. A file still matching its
- * recorded baseline was never touched, so a changed template can overwrite it.
- * A file the repo edited is never written; instead the placeholders and result
- * fields the template gained are named, because that is what every hand port has
- * actually consisted of, and the skill places them in the repo's own wording.
+ * Three jobs, ordered by how much can be proved.
+ *
+ * A file still matching its recorded baseline was never touched, so a changed
+ * template can overwrite it whole.
+ *
+ * A file the repo edited is never overwritten, but the managed regions inside
+ * it can be rewritten in place (TJ-1539): ghostrail owns those outright, so
+ * their current text is irrelevant to producing the new text. A region the repo
+ * edited is left alone and reported, never silently discarded.
+ *
+ * Whatever is left is named, not written: the placeholders and result fields
+ * the template gained, which is what every hand port consisted of before
+ * regions existed, and the skill places them in the repo's own wording.
  */
 async function applyTemplateUpdate(template, srcDir, repo, streams, env) {
     const manifest = await readManifest(repo);
@@ -1145,8 +1194,11 @@ async function applyTemplateUpdate(template, srcDir, repo, streams, env) {
     // compared against: a repo can be current with the release and behind main.
     streams.out(`comparing against ${template} @ ${VERSION}\n\n`);
     const written = {};
+    const writtenRegions = {};
     let pending = 0;
     let took = 0;
+    let mergedRegions = 0;
+    let mergedFiles = 0;
     for (const rel of rels) {
         const key = manifestKey(rel);
         const repoRel = repoPathFor(key, templatePrompts, repoPrompts);
@@ -1180,29 +1232,91 @@ async function applyTemplateUpdate(template, srcDir, repo, streams, env) {
             streams.out(`  ${repoRel}\n    took the template's version (you had not edited it)\n`);
             continue;
         }
-        // Customized, or no baseline to prove otherwise. Never written.
-        const signals = missingSignals(current ?? "", templateContent);
-        if (isClean(signals)) {
-            streams.out(`  ${repoRel}\n    customized, nothing to take\n`);
-            continue;
+        // Customized, or no baseline to prove otherwise. The file as a whole is
+        // never written, but the regions ghostrail owns inside it can be (TJ-1539).
+        let text = current ?? "";
+        const lines = [];
+        const recordedRegions = manifest?.regions?.[key];
+        const merged = mergeRegions(text, templateContent, recordedRegions);
+        if ("error" in merged) {
+            // Malformed markers on either side. Write nothing and fall back to the
+            // signal report, which is always available and always safe.
+            lines.push(`      markers unusable: ${merged.error}`);
+        }
+        else if (recordedRegions === undefined && merged.conflicted.length > 0) {
+            // Every region is unprovable for the same one reason, so say it once
+            // rather than per region. Report progress, not just the problem: a
+            // region already matching the template IS recorded by this run, so the
+            // count climbs as regions are ported and the advice cannot loop.
+            //
+            // Pointing at a bare `init` here would loop forever: it keeps a
+            // customized file rather than overwriting it, so it never records a
+            // baseline for the one file that needs one.
+            const adopted = Object.keys(merged.hashes).length;
+            const total = adopted + merged.conflicted.length;
+            lines.push(`      adopting regions: ${adopted}/${total} match the template and are recorded`);
+            lines.push("      bring the rest to the template's text and re-run; each one that matches");
+            lines.push("      is recorded, and merges on its own from then on");
+            pending++;
+            if (adopted > 0)
+                writtenRegions[key] = merged.hashes;
+        }
+        else {
+            for (const id of merged.updated)
+                lines.push(`      updated         ${id}`);
+            for (const id of merged.inserted)
+                lines.push(`      inserted        ${id}`);
+            for (const id of merged.conflicted) {
+                lines.push(`      edited locally  ${id}  (left alone; port it by hand)`);
+                pending++;
+            }
+            for (const id of merged.unplaceable) {
+                lines.push(`      unplaceable     ${id}  (no shared region to anchor to)`);
+                pending++;
+            }
+            if (merged.updated.length + merged.inserted.length > 0) {
+                text = merged.text;
+                await writeFile(join(repo, repoRel), text, "utf8");
+                mergedRegions += merged.updated.length + merged.inserted.length;
+                mergedFiles++;
+                // Region baselines only. Recording the merged file's whole-file hash
+                // would make `classify` call it `upstream-changed` on the next run,
+                // and that branch overwrites the file, destroying the customization
+                // this path exists to protect.
+                writtenRegions[key] = merged.hashes;
+            }
+            else if (Object.keys(merged.hashes).length > 0) {
+                writtenRegions[key] = merged.hashes;
+            }
         }
-        streams.out(`  ${repoRel}\n    customized, and the template gained:\n`);
+        // Whatever the regions did or could not do, the editable remainder can
+        // still be missing a signal. Read it off the merged text so a placeholder
+        // just delivered by a region is not reported as still missing.
+        const signals = missingSignals(text, templateContent);
         for (const name of signals.placeholders) {
-            streams.out(`      placeholder   {{${name}}}\n`);
+            lines.push(`      placeholder     {{${name}}}`);
             pending++;
         }
         for (const name of signals.fields) {
-            streams.out(`      result field  "${name}"\n`);
+            lines.push(`      result field    "${name}"`);
             pending++;
         }
+        if (lines.length === 0) {
+            streams.out(`  ${repoRel}\n    customized, nothing to take\n`);
+            continue;
+        }
+        streams.out(`  ${repoRel}\n    customized:\n${lines.join("\n")}\n`);
     }
-    if (Object.keys(written).length > 0) {
-        await writeManifest(repo, mergeManifest(manifest, template, VERSION, written));
+    if (Object.keys(written).length > 0 || Object.keys(writtenRegions).length > 0) {
+        await writeManifest(repo, mergeManifest(manifest, template, VERSION, written, writtenRegions));
     }
     await registerGhostrail(repo, env, streams);
     streams.out("\n");
     if (took > 0)
         streams.out(`took ${took} file(s) you had not edited\n`);
+    if (mergedRegions > 0) {
+        streams.out(`merged ${mergedRegions} managed region(s) into ${mergedFiles} customized file(s)\n`);
+    }
     if (pending === 0) {
         streams.out("nothing needs placing by hand\n");
         return 0;
@@ -1284,6 +1398,20 @@ export async function cmdInit(argv, streams, cwd = process.cwd(), env = process.
     // current content would later read as "never edited", which is worse than
     // admitting the baseline is unknown.
     const baselines = {};
+    const regionBaselines = {};
+    /**
+     * Record the per-region baselines for a file whose content provably IS the
+     * template's. Without this a repo would customize its editable text, hit the
+     * region path on the next `--update`, find nothing recorded, and be told
+     * every untouched region is a local edit. The merge would then almost never
+     * fire, which is the entire feature.
+     */
+    const recordRegions = (key, content) => {
+        const parsed = parseRegions(content);
+        if (!parsed.ok || parsed.regions.length === 0)
+            return;
+        regionBaselines[key] = regionHashes(parsed.regions);
+    };
     try {
         const existing = await readManifest(repo);
         for (const rel of await scaffoldFiles(srcDir)) {
@@ -1301,6 +1429,7 @@ export async function cmdInit(argv, streams, cwd = process.cwd(), env = process.
                     const current = await readIfPresent(to);
                     if (current !== undefined && hashContent(current) === templateHash) {
                         baselines[key] = templateHash;
+                        recordRegions(key, content);
                     }
                 }
                 continue;
@@ -1309,8 +1438,9 @@ export async function cmdInit(argv, streams, cwd = process.cwd(), env = process.
             await writeFile(to, content, "utf8");
             written.push(rel);
             baselines[key] = templateHash;
+            recordRegions(key, content);
         }
-        await writeManifest(repo, mergeManifest(existing, template, VERSION, baselines));
+        await writeManifest(repo, mergeManifest(existing, template, VERSION, baselines, regionBaselines));
     }
     catch (error) {
         streams.err(`init failed: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -1675,7 +1805,7 @@ export async function cmdClaudeSetup(argv, streams, env = process.env) {
         home: env.HOME ?? homedir(),
         profile: join(globalDir, "claude"),
         write: false,
-        pins: ["testbotpro"],
+        pins: [...DEFAULT_CLAUDE_PINS],
     });
     const proposal = await buildProposal(flags.home, flags.profile, flags.pins);
     streams.out("Claude profile setup\n");
@@ -1820,4 +1950,60 @@ async function openSecretsInEditor(path, flags, streams, env, deps) {
         streams.err(`editor exited ${code}; the file is written. ${fill}`);
     return 0;
 }
+/** Parse `doctor` flags: the shared `-c/-C` pair, plus `--json` and `--quick`. */
+function parseDoctorFlags(argv, defaults) {
+    const base = parseCommandFlags(argv, defaults);
+    return {
+        ...base,
+        json: defaults.json || argv.includes("--json"),
+        quick: defaults.quick || argv.includes("--quick"),
+    };
+}
+/**
+ * Load `ghostrail.toml` merged with the global settings as a {@link Result},
+ * rather than printing and returning undefined like {@link loadConfig} — unlike
+ * every other command, `doctor` has useful things to say even when config is
+ * broken (credentials, the Claude profile, run history), so it never aborts.
+ */
+async function loadDoctorConfig(configPath, env) {
+    let repoToml;
+    try {
+        repoToml = await readFile(configPath, "utf8");
+    }
+    catch {
+        return { ok: false, errors: [{ path: "", message: `cannot read config file: ${configPath}` }] };
+    }
+    const globalToml = await globalStoreFor(env).readSettings();
+    return parseMergedConfig(repoToml, globalToml);
+}
+/**
+ * `ghostrail doctor`: probe a setup rather than merely inspect it, and name the
+ * fix for whatever is broken. See specs/doctor-command.spec.md.
+ */
+export async function cmdDoctor(argv, streams, env = process.env, deps = {}) {
+    const flags = parseDoctorFlags(argv, {
+        config: "ghostrail.toml",
+        repo: ".",
+        json: false,
+        quick: false,
+    });
+    const secrets = await applySecrets(flags, env);
+    const configPath = isAbsolute(flags.config) ? flags.config : join(flags.repo, flags.config);
+    const config = await loadDoctorConfig(configPath, env);
+    const claudeProfileDir = await resolveClaudeProfile(env);
+    const state = await stateDirFor(flags.repo, config.ok ? config.value : undefined, env);
+    const historyRows = await new FileStore(state.dir).listRuns();
+    const report = await runDoctor({
+        repoPath: flags.repo,
+        config,
+        env,
+        quick: flags.quick,
+        claudeProfileDir,
+        claudeSourceHome: env.HOME ?? homedir(),
+        historyRows,
+    }, deps);
+    const rendered = flags.json ? renderDoctorJson(report) : renderDoctorText(report);
+    streams.out(redactSecrets(rendered, secrets));
+    return hasFailure(report) ? 1 : 0;
+}
 //# sourceMappingURL=commands.js.map