@monster-orange/den 0.4.14 → 0.4.15

package/src/ui/cli/repo-command.ts

@@ -20,6 +20,13 @@
  *   existed: true, and an existing side-car is never overwritten.
  * - The workspace: `-w <ws>` (created and activated when missing), else the
  *   focused one, else a new `default` workspace, activated and focused.
+ * - `--dry-run` (ON-3, the MCP tool manifest_draft's twin): a local path
+ *   only. Detection and the validator run as above, and the answer carries
+ *   the side-car as YAML (`draft`) and `validation`; nothing is written, not
+ *   the side-car, the workspace entry or the catalog.
+ *
+ * `<cli> repo detect <folder> [--json]` (ON-3, repos_detect's twin): the git
+ * repos in a folder and suggested workspaces (onboard-reads.ts).
  */
 import { execFileSync } from "child_process";
 import * as fs from "fs";
@@ -69,6 +76,8 @@ export interface RepoAddArgs {
   health?: string;
   branch?: string;
   json: boolean;
+  /** `--dry-run`: detect and validate, write nothing (a local path only). */
+  dryRun?: boolean;
 }
 
 export interface RepoAddResult {
@@ -93,11 +102,17 @@ export interface RepoAddResult {
   fix?: string;
   ask?: string;
   choices?: string[];
+  /** `--dry-run`: nothing was written. */
+  dryRun?: boolean;
+  /** `--dry-run`: the side-car Den would write, as YAML. */
+  draft?: string;
+  /** `--dry-run`: the validator's answer for the draft. */
+  validation?: { valid: boolean; errors: { path: string; message: string }[] };
 }
 
 const USAGE = () =>
   `${product().cli} repo add <path|git-url> [--sidecar] [-w <workspace>] [--name <repo>] ` +
-  `[--run "<cmd>"] [--down "<cmd>"] [--health <url>] [--branch <branch>] [--json]`;
+  `[--run "<cmd>"] [--down "<cmd>"] [--health <url>] [--branch <branch>] [--dry-run] [--json]`;
 
 export const REPO_HELP = () =>
   [
@@ -111,7 +126,14 @@ export const REPO_HELP = () =>
     '  cannot decide, nothing is written and --json answers with "ask" and',
     '  "choices": re-run with --run "<cmd>". --health <url> adds an HTTP health',
     "  check. -w picks the workspace (default: the focused one, else a new",
-    "  `default`). Safe to re-run: the same repo answers existed: true.\n",
+    "  `default`). Safe to re-run: the same repo answers existed: true.",
+    "  --dry-run (a local folder only): detect and validate the side-car and",
+    '  print it ("draft"), writing nothing: no side-car, no workspace entry.\n',
+    `\n  ${product().cli} repo detect <folder> [--json]\n`,
+    "  Find the git repos in a folder inside your home (one or two levels deep),",
+    "  say how each one runs, and suggest workspaces: the repos in one parent",
+    "  folder go in one workspace named after it. Reads only: it never writes,",
+    "  never runs a repo's tools and never follows a symlink.\n",
   ].join("\n");
 
 const VALUE_FLAGS = new Set([
@@ -136,6 +158,7 @@ export function parseRepoAddArgs(argv: string[]): RepoAddArgs {
     const flag = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
     if (a === "--sidecar") out.sidecar = true;
     else if (a === "--json") out.json = true;
+    else if (a === "--dry-run" || a === "-n") out.dryRun = true;
     else if (VALUE_FLAGS.has(flag)) {
       const v = flag !== a ? a.slice(eq + 1) : argv[++i];
       if (v === undefined || v === "") throw new Error(`${flag} needs a value`);
@@ -236,6 +259,15 @@ export function repoAdd(
       fix: `${bin} repo add ${a.spec} --health http://localhost:<port>/ --json`,
     };
 
+  if (a.dryRun && url)
+    return {
+      ok: false,
+      dryRun: true,
+      error:
+        "--dry-run takes a local folder: a git URL would have to be cloned first",
+      fix: `${bin} repo add <path> --dry-run --json`,
+    };
+
   // ── Where the repo is ────────────────────────────────────────────────────
   let repoPath: string;
   let mode: "dev-managed" | "managed";
@@ -299,6 +331,10 @@ export function repoAdd(
     ? (originRepoName(repoPath) ?? name)
     : (originRepoName(repoPath) ?? path.basename(repoPath));
   let manifestInfo: RepoAddResult["manifest"];
+  /** --dry-run: the side-car that would be written. */
+  let drafted:
+    | { manifest: Record<string, unknown>; text: string; valid: boolean }
+    | undefined;
   if (own) {
     manifestInfo = { source: "repo", file: own };
   } else {
@@ -324,29 +360,43 @@ export function repoAdd(
         };
       const manifest = sidecarManifest(mName, d.commands, a.health);
       const v = validate(manifest);
+      const dry = a.dryRun
+        ? {
+            dryRun: true,
+            draft: formatManifestYaml(manifest),
+            validation: { valid: v.valid, errors: v.errors },
+          }
+        : {};
       if (!v.valid)
         return {
           ok: false,
           error: `the detected manifest is not valid: ${v.errors.map((e) => `${e.path} ${e.message}`).join("; ")}`,
           fix: `${bin} repo add ${a.spec} --run "<command>" --json`,
+          ...dry,
         };
       const file = sidecarFile(key);
-      fs.mkdirSync(path.dirname(file), { recursive: true });
-      // "wx": never overwrite a side-car someone may have edited.
-      fs.writeFileSync(file, formatManifestYaml(manifest), {
-        encoding: "utf-8",
-        flag: "wx",
-      });
+      if (a.dryRun) {
+        drafted = { manifest, text: dry.draft as string, valid: v.valid };
+      } else {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        // "wx": never overwrite a side-car someone may have edited.
+        fs.writeFileSync(file, formatManifestYaml(manifest), {
+          encoding: "utf-8",
+          flag: "wx",
+        });
+      }
       manifestInfo = {
         source: "sidecar",
         file,
-        written: true,
+        written: !a.dryRun,
         detected: d.commands.source,
       };
     }
   }
 
-  const manifest = readManifest(repoPath);
+  const manifest = drafted
+    ? (drafted.manifest as unknown as ReturnType<typeof readManifest>)
+    : readManifest(repoPath);
   if (!manifest)
     return {
       ok: false,
@@ -366,6 +416,34 @@ export function repoAdd(
       fix: `${bin} repo add ${a.spec} --name <repo> --json`,
     };
 
+  if (a.dryRun) {
+    // Nothing is written: not the side-car, not the workspace entry.
+    const flags = [
+      a.name !== undefined ? ` --name ${a.name}` : "",
+      a.run !== undefined ? ` --run "${a.run}"` : "",
+      a.down !== undefined ? ` --down "${a.down}"` : "",
+      a.health !== undefined ? ` --health ${a.health}` : "",
+      a.workspace !== undefined ? ` -w ${a.workspace}` : "",
+    ].join("");
+    return {
+      ok: true,
+      dryRun: true,
+      repo: name,
+      workspace: a.workspace ?? getFocusedWorkspaceName() ?? "default",
+      mode,
+      path: repoPath,
+      manifest: manifestInfo,
+      services: Object.keys(manifest.services ?? {}),
+      ...(drafted
+        ? {
+            draft: drafted.text,
+            validation: { valid: drafted.valid, errors: [] },
+          }
+        : {}),
+      next: [`${bin} repo add ${a.spec}${flags} --json`],
+    };
+  }
+
   // ── The workspace entry ──────────────────────────────────────────────────
   const ws = targetWorkspace(a.workspace);
   const file = readWorkspacesFile();
@@ -423,6 +501,18 @@ export function repoAdd(
 }
 
 function printHuman(r: RepoAddResult): void {
+  if (r.dryRun && r.ok) {
+    console.log(
+      `✓ Dry run: ${r.repo} would be added to workspace ${r.workspace} (${r.mode}, ${r.path}); nothing was written`,
+    );
+    if (r.manifest)
+      console.log(
+        `  manifest: ${r.manifest.source} ${r.manifest.file}${r.draft ? ` (would be written, from ${r.manifest.detected})` : ""}`,
+      );
+    if (r.draft) console.log(`\n${r.draft.replace(/^/gm, "    ")}`);
+    console.log(`  To add it: ${r.next?.[0] ?? ""}`);
+    return;
+  }
   if (!r.ok) {
     console.error(`✗ repo add: ${r.error}`);
     if (r.ask) console.error(`  ${r.ask}`);
@@ -442,6 +532,61 @@ function printHuman(r: RepoAddResult): void {
   console.log(`  Next: ${r.next?.[0] ?? ""}`);
 }
 
+/** `repo detect <folder> [--json]` (ON-3, repos_detect's twin). */
+async function cmdRepoDetect(argv: string[]): Promise<number> {
+  const { processPathRules, reposDetect } = await import("./onboard-reads.js");
+  const { registeredRepos } = await import("./onboard-command.js");
+  const { getStateDir } = await import("../../shared/paths.js");
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => a !== "--json");
+  const bad = positional.find((a) => a.startsWith("-"));
+  if (bad || positional.length !== 1) {
+    const r = {
+      ok: false,
+      error: bad ? `unknown flag ${bad}` : "repo detect needs one <folder>",
+      fix: `${runnable()} repo detect <folder> --json`,
+    };
+    if (json) printJson(r);
+    else console.error(`✗ repo detect: ${r.error}`);
+    return 2;
+  }
+  // A relative folder is the person's own, from where they typed it.
+  const given = positional[0];
+  const folder =
+    given.startsWith("~") || path.isAbsolute(given)
+      ? given
+      : path.resolve(getInvokeCwd(), given);
+  const r = reposDetect(folder, processPathRules(getStateDir()), {
+    registered: registeredRepos,
+    bin: runnable(),
+  });
+  if (json) printJson(r);
+  else if (!r.ok) console.error(`✗ repo detect: ${r.error}`);
+  else {
+    console.log(
+      `✓ ${r.repos.length} repo${r.repos.length === 1 ? "" : "s"} in ${r.path}${r.truncated ? " (stopped early: more are there)" : ""}`,
+    );
+    for (const x of r.repos) {
+      const how = x.runs
+        ? x.runs.up
+        : x.manifest !== "none"
+          ? `its ${x.manifest === "repo" ? "own" : "side-car"} manifest`
+          : (x.ask ?? "");
+      const inWs = x.registered?.length
+        ? ` (in ${x.registered.map((g) => g.workspace).join(", ")})`
+        : "";
+      console.log(`  ${x.name.padEnd(20)} ${how}${inWs}`);
+    }
+    if (r.workspaces.length) {
+      console.log("\n  Suggested workspaces:");
+      for (const w of r.workspaces)
+        console.log(`  ${w.name.padEnd(20)} ${w.repos.join(", ")}`);
+    }
+    if (r.next[0]) console.log(`\n  Next: ${r.next[0]}`);
+  }
+  return r.ok ? 0 : 1;
+}
+
 /** `repo <sub> …`; returns the exit code. */
 export async function cmdRepo(
   argv: string[],
@@ -453,6 +598,7 @@ export async function cmdRepo(
     return sub ? 0 : 1;
   }
   const json = rest.includes("--json");
+  if (sub === "detect") return cmdRepoDetect(rest);
   if (sub !== "add") {
     const r = {
       ok: false,

package/src/ui/cli/web-command.ts

@@ -64,6 +64,12 @@ import {
 } from "./server-identity.js";
 
 import { product } from "../../shared/product.js";
+import {
+  CLAIM_CODE_TTL_MS,
+  claimLink,
+  mintClaimCode,
+  personGrantRefusal,
+} from "../../shared/claim-code.js";
 import { redactSecrets } from "../../shared/redact.js";
 interface WebCommandOptions {
   /** `open` is `up` that always opens a fresh sign-in tab (SEC-1b). */
@@ -1142,6 +1148,7 @@ export const WEB_SUBCOMMANDS_WITH_HELP = [
   "logout",
   "owner",
   "approve",
+  "claim-link",
 ] as const;
 
 export function displayWebHelp(): void {
@@ -1190,6 +1197,9 @@ export function displayWebHelp(): void {
   console.log(
     "  approve <code>     Let in a computer whose signed-out page shows this code",
   );
+  console.log(
+    "  claim-link         Print a one-time setup link (30 min) that signs this machine's browser in",
+  );
   console.log("  (start/stop remain accepted as legacy aliases for up/down)");
   console.log();
   console.log(chalk.bold("Options:"));
@@ -1276,6 +1286,10 @@ export async function cmdWeb(args: string[]): Promise<void> {
     process.exitCode = await cmdWebApprove(args.slice(1));
     return;
   }
+  if (args[0] === "claim-link") {
+    process.exitCode = cmdWebClaimLink(args.slice(1));
+    return;
+  }
   if (args.includes("--help") || args.includes("-h")) {
     displayWebHelp();
     return;
@@ -1400,7 +1414,8 @@ export async function cmdWeb(args: string[]): Promise<void> {
   // SEC-1b: what opens is a sign-in link (localhost, one-time, 60 s). It
   // is printed only when the browser couldn't be opened: the one line the
   // person then needs.
-  let link: string | null = null;
+  // Inside an agent's session: the plain page, never a sign-in link.
+  let link: string | null = personGrantRefusal(process.env) ? url : null;
   const signIn = () => (link ??= freshLoginLink(options.port));
   const browser = openOrFocusDenWebUrl(
     signIn,
@@ -1450,9 +1465,65 @@ export function freshLoginLink(
   origin: string = localhostOrigin(port),
   stateDir: string = getStateDir(),
 ): string {
+  const refused = personGrantRefusal(process.env);
+  if (refused) throw new Error(refused);
   return loginLink(origin, mintLoginCode(ensureWebSecret(stateDir)), next);
 }
 
+/**
+ * `<cli> web claim-link [--json] [--port <port>]` (0.4.15): a one-time
+ * setup link, `http://localhost:<port>/?claim=<code>` (30 minutes), on
+ * stdout alone. Opening it signs that browser in, so it can approve an
+ * agent's changes from the first page. Refused inside an agent's session:
+ * the person opens it, never an agent. Never logged.
+ */
+export function cmdWebClaimLink(args: string[], io: CliIo = stdIo): number {
+  const usage = `Usage: ${product().cli} web claim-link [--json] [--port <port>]\n`;
+  if (isHelp(args)) {
+    io.out(
+      usage +
+        "  Prints a one-time setup link (it lasts 30 minutes and works once). Open it\n" +
+        "  yourself, in the browser on this machine: it signs that browser in, so you\n" +
+        "  can approve what an agent asks to change. Don't let any agent open it.\n",
+    );
+    return 0;
+  }
+  const refused = personGrantRefusal(process.env);
+  if (refused) {
+    io.err(`${product().cli}: ${refused}\n`);
+    return 1;
+  }
+  let port: number;
+  let rest: string[];
+  try {
+    ({ port, rest } = takePort(args));
+  } catch (e) {
+    io.err(`${(e as Error).message}\n`);
+    return 2;
+  }
+  const asJson = rest.includes("--json");
+  if (rest.some((a) => a !== "--json")) {
+    io.err(usage);
+    return 2;
+  }
+  const now = Date.now();
+  const url = claimLink(
+    localhostOrigin(port),
+    mintClaimCode(ensureWebSecret(io.stateDir ?? getStateDir()), now),
+  );
+  if (asJson)
+    io.out(
+      `${JSON.stringify({ url, expiresAt: new Date(now + CLAIM_CODE_TTL_MS).toISOString() })}\n`,
+    );
+  else {
+    io.err(
+      `${product().cli}: open this link yourself within 30 minutes; it signs in one browser, once. Don't let any agent open it.\n`,
+    );
+    io.out(`${url}\n`);
+  }
+  return 0;
+}
+
 interface CliIo {
   out: (s: string) => void;
   err: (s: string) => void;
@@ -1570,6 +1641,11 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
     io.out(LOGIN_HELP());
     return 0;
   }
+  const refused = personGrantRefusal(process.env);
+  if (refused) {
+    io.err(`${product().cli}: ${refused}\n`);
+    return 1;
+  }
   const a = parseLoginArgs(args, io);
   if (typeof a === "number") return a;
   const link = freshLoginLink(
@@ -1610,6 +1686,11 @@ export async function cmdWebLoginWait(
     io.out(LOGIN_HELP());
     return 0;
   }
+  const refused = personGrantRefusal(process.env);
+  if (refused) {
+    io.err(`${product().cli}: ${refused}\n`);
+    return 1;
+  }
   const a = parseLoginArgs(args, io);
   if (typeof a === "number") return a;
   if (a.noWait)
@@ -2029,6 +2110,11 @@ export async function cmdWebApprove(
     io.err(usage);
     return 2;
   }
+  const refused = list ? null : personGrantRefusal(process.env);
+  if (refused) {
+    io.err(`${product().cli}: ${refused}\n`);
+    return 1;
+  }
   const stateDir = io.stateDir ?? getStateDir();
   const r = list
     ? await serverCall(stateDir, port, "GET", "/api/web/waiting")
@@ -2133,6 +2219,11 @@ export async function cmdWebOwner(
   }
   const stateDir = io.stateDir ?? getStateDir();
   const cli = product().cli;
+  const refused = sub === "show" ? null : personGrantRefusal(process.env);
+  if (refused) {
+    io.err(`${cli}: ${refused}\n`);
+    return 1;
+  }
   if (sub === "show") {
     const o = readWebOwner(stateDir);
     if (asJson) io.out(`${JSON.stringify({ owner: o }, null, 2)}\n`);

package/src/ui/mcp/api.ts

@@ -129,6 +129,10 @@ const READ_ROUTES = new Set([
   "/api/stacks",
   "/api/edge",
   "/api/server-info",
+  // ON-3: onboarding reads (nothing written).
+  "/api/onboard/status",
+  "/api/onboard/repos",
+  "/api/onboard/manifest",
 ]);
 
 /** Action routes and their method. Anything else is never reached. */
@@ -138,6 +142,8 @@ const ACTION_ROUTES: Record<string, string> = {
   "/api/service/exec": "GET",
   "/api/run": "GET",
   "/api/workspace/sync": "POST",
+  // ON-3's writes: asks the person to allow one (held; nothing runs here).
+  "/api/approvals": "POST",
 };
 
 /**
@@ -145,6 +151,8 @@ const ACTION_ROUTES: Record<string, string> = {
  * and Bring in's list and import (MCP agent_import, AG-17.1).
  */
 const ACTION_ROUTE_PATTERNS: { re: RegExp; method: string }[] = [
+  // One held request's state (its own, the server checks). Never /decide.
+  { re: /^\/api\/approvals\/[A-Za-z0-9_-]{16}$/, method: "GET" },
   {
     re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/agents\/[A-Za-z0-9._-]{1,64}\/resume$/,
     method: "POST",
@@ -222,6 +230,8 @@ export interface DenApi {
     query?: Query,
     method?: "GET" | "POST",
     body?: unknown,
+    /** Extra request headers (an approval's ticket). */
+    headers?: Record<string, string>,
   ): Promise<unknown>;
   /** An SSE route, read to a bound; the connection is closed after. */
   stream(path: string, query: Query, opts: StreamOpts): Promise<StreamResult>;
@@ -302,6 +312,7 @@ export function createDenApi(opts: {
     query: Query,
     signal?: AbortSignal,
     body?: unknown,
+    extra: Record<string, string> = {},
   ): Promise<Response> {
     assertAllowedRequest(method, path, query);
     await ensureOurs();
@@ -309,6 +320,7 @@ export function createDenApi(opts: {
       const res = await fetch(buildUrl(baseUrl, path, query), {
         method,
         headers: {
+          ...extra,
           ...opts.headers(),
           ...(opts.auth ?? cliAuthHeaders)(),
           ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
@@ -338,8 +350,8 @@ export function createDenApi(opts: {
   return {
     baseUrl,
 
-    async get(path, query = {}, method = "GET", body) {
-      const res = await request(method, path, query, undefined, body);
+    async get(path, query = {}, method = "GET", body, headers) {
+      const res = await request(method, path, query, undefined, body, headers);
       const text = await res.text();
       try {
         return JSON.parse(text) as unknown;

package/src/ui/mcp/server.ts

@@ -22,7 +22,12 @@ import { product } from "../../shared/product.js";
 import { DEFAULT_PORT } from "../../shared/constants.js";
 import { createDenApi, type DenApi } from "./api.js";
 import { ownServer } from "../cli/server-identity.js";
-import { callTool, toolsFor, type ToolContext } from "./tools.js";
+import {
+  approvalsState,
+  callTool,
+  toolsFor,
+  type ToolContext,
+} from "./tools.js";
 import { plural } from "../../shared/plural.js";
 import {
   checkGrants,
@@ -60,7 +65,8 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
         `through the running ${p.title} web server (\`${opts.cli} web up\`). ` +
         (opts.cfg.actions.length
           ? `Actions enabled: ${opts.cfg.actions.join(", ")}.`
-          : "Read-only: the org has enabled no actions (mcp.actions).") +
+          : "The org has enabled no actions (mcp.actions).") +
+        ` The ${approvalsState(opts.cfg)}.` +
         (opts.scope
           ? ` Scoped to workspace "${opts.scope.workspace}" as ${opts.scope.actor}: ` +
             "a call naming another workspace is refused, and lists show this one only, " +
@@ -258,6 +264,10 @@ export async function runOneShot(
   if (shot.kind === "list") {
     const names = tools.map((t) => t.name);
     out(names.length ? `${names.join("\n")}\n` : "");
+    // Stdout stays one name a line; the state goes to stderr.
+    (opts.err ?? ((t: string) => process.stderr.write(t)))(
+      `${approvalsState(opts.cfg)}\n`,
+    );
     return 0;
   }
   const ctx: ToolContext = {