@rolino/cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,9 +1,25 @@
 # @rolino/cli
 
+## 0.7.0
+
+### Minor Changes
+
+- f78e0ff: Prefer advertised Streamable HTTP MCP with client-owned OAuth, add explicit HTTP and STDIO transport selection, and keep local MCP as a fallback.
+- 358f37a: Expose additive safe Blog preparation, next-action, and quality summaries through the shared read contracts and existing clients.
+
+### Patch Changes
+
+- Updated dependencies [358f37a]
+  - @rolino/contracts@0.7.0
+  - @rolino/sdk@0.7.0
+  - @rolino/local-auth@0.7.0
+
 ## 0.6.0
 
 ### Minor Changes
 
+- Add matching backlink prospecting commands with safe JSON output and formula-safe contact CSV export. Rolino does not send email.
+
 - d162f85: Add safe Blog editorial cadence preview and apply operations across contracts, SDK, CLI, and MCP.
 - 50cb9fc: Add Google Business Profile as a disabled-by-default standard text and single-image publishing destination across shared public clients.
 - 1ac7ed5: Add signed custom Blog webhook setup, connection testing, one-time secret rotation, and safe idempotent replay parity.
@@ -93,6 +109,10 @@
 
 ### Minor Changes
 
+- Show additive safe Blog preparation and quality state in existing JSON reads.
+
+### Minor Changes
+
 - Add Blog image generation, exact local-file upload, image review, confirmed
   exact-bundle approval, future scheduling, and schedule cancellation commands
   with deterministic agent output, stable idempotency, safe errors, and

package/README.md

@@ -14,16 +14,17 @@ The supported installation keeps the CLI independent from MCP:
 npm install --global @rolino/cli
 ```
 
-Users who also want local MCP will install both packages explicitly:
+Users who need local STDIO MCP will install both packages explicitly:
 
 ```bash
 npm install --global @rolino/cli @rolino/mcp
 ```
 
-The CLI-only installation does not include `@rolino/mcp` or the MCP SDK. If a
-CLI-only user runs `rolino setup mcp`, the command explains how to install the
-separate MCP package and then retry. Rolino never downloads or installs MCP
-silently.
+The default `rolino setup mcp` mode checks the selected Rolino instance. It
+uses hosted Streamable HTTP when the instance advertises it. This mode does
+not need `@rolino/mcp`. If remote MCP is not available, the command uses local
+STDIO and explains how to install the separate MCP package. Rolino never
+downloads or installs MCP silently.
 
 Initial commands:
 
@@ -31,12 +32,24 @@ Initial commands:
 rolino auth login
 rolino auth status
 rolino auth logout
-rolino setup mcp --client codex [--scope user|project]
-rolino setup mcp --client claude-code [--scope user|project]
+rolino setup mcp --client codex [--transport auto|http|stdio] [--scope user|project]
+rolino setup mcp --client claude-code [--transport auto|http|stdio] [--scope user|project]
 rolino whoami
 rolino projects create --name NAME [--type PRODUCT|SERVICE|PERSONAL|COMPANY] [--website URL] [--description TEXT] [--idempotency-key KEY] --yes
 rolino projects list [--limit 50] [--cursor ID]
 rolino projects show PROJECT_ID
+rolino backlinks targets list --project PROJECT_ID
+rolino backlinks targets add --project PROJECT_ID --url URL --label LABEL
+rolino backlinks discover --project PROJECT_ID --limit 20
+rolino backlinks runs get --project PROJECT_ID --run RUN_ID
+rolino backlinks prospects list --project PROJECT_ID [--stage STAGE]
+rolino backlinks prospects get --project PROJECT_ID --prospect PROSPECT_ID
+rolino backlinks prospects approve --project PROJECT_ID --prospect PROSPECT_ID --expected-version VERSION
+rolino backlinks contacts research --project PROJECT_ID --prospect PROSPECT_ID
+rolino backlinks contacts list --project PROJECT_ID
+rolino backlinks contacts export --project PROJECT_ID --format csv
+rolino backlinks outreach update --project PROJECT_ID --prospect PROSPECT_ID --file DRAFT.json --expected-version VERSION
+rolino backlinks verify --project PROJECT_ID --prospect PROSPECT_ID --url PUBLIC_URL --expected-version VERSION
 rolino media list --project PROJECT_ID [--type IMAGE|VIDEO] [--query TEXT] [--limit 50] [--cursor ID]
 rolino media upload FILE_PATH --project PROJECT_ID --yes
 rolino posts create --project PROJECT_ID --caption TEXT [--platform INSTAGRAM|TIKTOK|YOUTUBE|BLUESKY|LINKEDIN|GOOGLE_BUSINESS_PROFILE] [--media ASSET_ID] --yes
@@ -70,10 +83,10 @@ rolino blog schedule cancel execute ARTICLE_ID --project PROJECT_ID --confirmati
 rolino doctor
 ```
 
-Interactive login uses standard OAuth Authorization Code with PKCE S256. It
-opens the configured Rolino instance, requests the exact \`/api/v1\` resource,
-uses the fixed \`http://127.0.0.1:48391/oauth/callback\` redirect, and obtains
-explicit workspace approval.
+Interactive login uses standard OAuth Authorization Code with PKCE S256. It
+opens the configured Rolino instance, requests the exact \`/api/v1\` resource,
+uses the fixed \`http://127.0.0.1:48391/oauth/callback\` redirect, and obtains
+explicit workspace approval.
 The approval screen always includes identity and workspace reads and lets the
 user independently opt into project creation, draft writing, confirmed
 scheduling, confirmed immediate publishing, and read-only SEO Intelligence.
@@ -89,20 +102,25 @@ with evidence. It cannot create a final draft in the same action.
 Optional permissions start off,
 and existing credentials never gain a newly selected permission. Revoke and
 reauthorize an existing connection to grant project creation or `seo:read`.
-Existing grants never receive `seo:read` automatically. OAuth tokens never
-pass through a browser URL. The CLI stores a short-lived access token and a
-rotating refresh token by host, issuer, client, and resource in the
-operating-system configuration directory. It does not read or migrate the old
-interactive credential, so the first use after this cutover requires sign-in;
+Existing grants never receive `seo:read` automatically. OAuth tokens never
+pass through a browser URL. The CLI stores a short-lived access token and a
+rotating refresh token by host, issuer, client, and resource in the
+operating-system configuration directory. It does not read or migrate the old
+interactive credential, so the first use after this cutover requires sign-in;
 `ROLINO_CONFIG_DIR` overrides that location. `auth logout` revokes the calling
-workspace grant and OAuth refresh token before deleting its local copy.
+workspace grant and OAuth refresh token before deleting its local copy.
 
 The terminal waits five minutes for browser approval. If that request expires,
 close the old approval page and run `rolino auth login` again; refreshing the
 page cannot restart the closed loopback listener.
 
-`setup mcp` finds the built Rolino stdio server, previews the exact token-free
-configuration, and asks before changing anything. User scope is the default.
+`setup mcp` checks `/api/v1/meta` and prefers hosted Streamable HTTP when it is
+available. Remote setup writes the `/mcp` URL and OAuth mode, does not start a
+local MCP process, and does not reuse `rolino auth login`. Run
+`codex mcp login rolino` after remote Codex setup. Use `--transport http` to
+require remote MCP or `--transport stdio` to require the local package and its
+shared CLI OAuth session. The command previews the exact token-free
+configuration and asks before changing anything. User scope is the default.
 Codex configuration is written to `CODEX_HOME/config.toml` or
 `~/.codex/config.toml`; Claude Code user scope is applied through its official
 CLI. Project scope writes `.codex/config.toml` or `.mcp.json` in the current

package/dist/bin.cjs

@@ -34,7 +34,7 @@ var import_commander = require("commander");
 // package.json
 var package_default = {
   name: "@rolino/cli",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "Agent-friendly command-line interface for Rolino",
   type: "module",
   license: "MIT",
@@ -91,9 +91,9 @@ var package_default = {
     dev: "tsx src/bin.ts"
   },
   dependencies: {
-    "@rolino/contracts": "0.6.0",
-    "@rolino/local-auth": "0.6.0",
-    "@rolino/sdk": "0.6.0",
+    "@rolino/contracts": "0.7.0",
+    "@rolino/local-auth": "0.7.0",
+    "@rolino/sdk": "0.7.0",
     commander: "^15.0.0",
     open: "^11.0.0"
   },
@@ -649,12 +649,18 @@ function removeExistingCodexEntry(source, newline) {
   return kept.join(newline).trimEnd();
 }
 function codexBlock(server, newline) {
+  const configuration = server.transport === "http" ? [
+    `url = ${tomlString(server.url)}`,
+    `auth = ${tomlString(server.auth)}`
+  ] : [
+    `command = ${tomlString(server.command)}`,
+    `args = [${server.args.map(tomlString).join(", ")}]`,
+    `env = { ROLINO_URL = ${tomlString(server.env.ROLINO_URL)} }`
+  ];
   return [
     CODEX_BEGIN,
     "[mcp_servers.rolino]",
-    `command = ${tomlString(server.command)}`,
-    `args = [${server.args.map(tomlString).join(", ")}]`,
-    `env = { ROLINO_URL = ${tomlString(server.env.ROLINO_URL)} }`,
+    ...configuration,
     CODEX_END
   ].join(newline);
 }
@@ -694,7 +700,12 @@ function updateClaudeProjectConfig(source, server) {
     ...parsed,
     mcpServers: {
       ...currentServers,
-      rolino: { type: "stdio", ...server }
+      rolino: server.transport === "http" ? { type: "http", url: server.url } : {
+        type: "stdio",
+        command: server.command,
+        args: server.args,
+        env: server.env
+      }
     }
   }, null, 2)}
 `;
@@ -726,6 +737,7 @@ async function setupCodex(options, server) {
     backupPath,
     changed,
     dryRun: options.dryRun ?? false,
+    transport: server.transport,
     server
   };
 }
@@ -746,6 +758,7 @@ async function setupClaudeCode(options, server) {
       backupPath,
       changed,
       dryRun: options.dryRun ?? false,
+      transport: server.transport,
       server
     };
   }
@@ -758,6 +771,7 @@ async function setupClaudeCode(options, server) {
       backupPath: null,
       changed: true,
       dryRun: true,
+      transport: server.transport,
       server
     };
   }
@@ -771,7 +785,12 @@ async function setupClaudeCode(options, server) {
     "mcp",
     "add-json",
     "rolino",
-    JSON.stringify({ type: "stdio", ...server }),
+    JSON.stringify(server.transport === "http" ? { type: "http", url: server.url } : {
+      type: "stdio",
+      command: server.command,
+      args: server.args,
+      env: server.env
+    }),
     "--scope",
     "user"
   ], options);
@@ -787,14 +806,51 @@ async function setupClaudeCode(options, server) {
     backupPath: null,
     changed: true,
     dryRun: false,
+    transport: server.transport,
     server
   };
 }
+function remoteMcpUrl(baseUrl) {
+  return new URL("mcp", `${baseUrl.replace(/\/$/, "")}/`).toString();
+}
+async function advertisedRemoteMcp(options) {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  try {
+    const response = await fetchImplementation(
+      new URL("api/v1/meta", `${options.baseUrl.replace(/\/$/, "")}/`),
+      {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(5e3)
+      }
+    );
+    if (!response.ok) return false;
+    const payload = await response.json();
+    return payload.data?.mcp?.streamableHttp === true;
+  } catch {
+    return false;
+  }
+}
+async function resolveTransport(options) {
+  const requested = options.transport ?? "stdio";
+  if (requested === "stdio") return "stdio";
+  if (await advertisedRemoteMcp(options)) return "http";
+  if (requested === "http") {
+    throw new TypeError(
+      "This Rolino instance does not advertise Streamable HTTP MCP. Use --transport stdio, or enable and verify remote MCP on the server."
+    );
+  }
+  return "stdio";
+}
 async function setupMcp(options) {
-  const serverPath = await resolveServerPath(options);
-  const server = {
+  const transport = await resolveTransport(options);
+  const server = transport === "http" ? {
+    transport: "http",
+    url: remoteMcpUrl(options.baseUrl),
+    auth: "oauth"
+  } : {
+    transport: "stdio",
     command: options.nodePath,
-    args: [serverPath],
+    args: [await resolveServerPath(options)],
     env: { ROLINO_URL: options.baseUrl }
   };
   return options.client === "codex" ? setupCodex(options, server) : setupClaudeCode(options, server);
@@ -935,6 +991,10 @@ function mcpScope(value) {
   if (value === "user" || value === "project") return value;
   throw new import_commander.InvalidArgumentError("MCP setup scope must be user or project.");
 }
+function mcpTransport(value) {
+  if (value === "auto" || value === "http" || value === "stdio") return value;
+  throw new import_commander.InvalidArgumentError("MCP transport must be auto, http, or stdio.");
+}
 function isoDateTime(value) {
   const date = new Date(value);
   if (Number.isNaN(date.getTime())) {
@@ -995,13 +1055,21 @@ function requireBlogExecutionConsent(options) {
   throw new TypeError("This Blog execute command requires explicit consent. Review the confirmed operation and pass --yes.");
 }
 function formatMcpSetupPreview(result) {
+  const connection = result.server.transport === "http" ? [
+    `Transport: Streamable HTTP`,
+    `Endpoint: ${result.server.url}`,
+    "Authentication: OAuth in the MCP client"
+  ] : [
+    "Transport: local STDIO",
+    `Command: ${result.server.command}`,
+    `Arguments: ${result.server.args.join(" ")}`,
+    `Rolino URL: ${result.server.env.ROLINO_URL}`
+  ];
   return [
     `Client: ${result.client === "codex" ? "Codex" : "Claude Code"}`,
     `Scope: ${result.scope}`,
     `Target: ${result.target}`,
-    `Command: ${result.server.command}`,
-    `Arguments: ${result.server.args.join(" ")}`,
-    `Rolino URL: ${result.server.env.ROLINO_URL}`,
+    ...connection,
     "No token will be written to MCP configuration."
   ].join("\n");
 }
@@ -1464,7 +1532,7 @@ async function runCli(argv = process.argv, overrides = {}) {
     });
   });
   const setup = program.command("setup").description("Configure local agent tools for Rolino");
-  setup.command("mcp").description("Configure the Rolino stdio MCP server for a supported client").requiredOption("--client <client>", "codex or claude-code", mcpClient).option("--scope <scope>", "user or project", mcpScope, "user").option("--server-path <path>", "absolute or working-directory-relative MCP server path").option("--dry-run", "show the intended configuration without writing it").option("--yes", "apply without an interactive confirmation").option("--force", "replace an existing Claude Code user-scoped Rolino server").action(async (local) => {
+  setup.command("mcp").description("Configure Rolino MCP with Streamable HTTP or local STDIO").requiredOption("--client <client>", "codex or claude-code", mcpClient).option("--scope <scope>", "user or project", mcpScope, "user").option("--transport <transport>", "auto, http, or stdio", mcpTransport, "auto").option("--server-path <path>", "absolute or working-directory-relative MCP server path").option("--dry-run", "show the intended configuration without writing it").option("--yes", "apply without an interactive confirmation").option("--force", "replace an existing Claude Code user-scoped Rolino server").action(async (local) => {
     const global = program.opts();
     commandExitCode = await execute({
       command: "setup mcp",
@@ -1477,7 +1545,8 @@ async function runCli(argv = process.argv, overrides = {}) {
           cwd: runtime.cwd,
           env: runtime.env,
           nodePath: runtime.nodePath,
-          cliEntryPath: runtime.cliEntryPath
+          cliEntryPath: runtime.cliEntryPath,
+          fetch: runtime.fetch
         };
         const preview = await setupMcp({ ...setupOptions, dryRun: true });
         let result = preview;
@@ -1504,11 +1573,12 @@ async function runCli(argv = process.argv, overrides = {}) {
             `${state} Rolino MCP for ${clientLabel}.`,
             `Scope: ${result.scope}`,
             `Target: ${result.target}`,
+            `Transport: ${result.transport === "http" ? "Streamable HTTP" : "local STDIO"}`,
             ...result.backupPath && !result.dryRun ? [`Backup: ${result.backupPath}`] : [],
             `Rolino URL: ${client.baseUrl}`,
             "No token was written to MCP configuration."
           ].join("\n"),
-          result.client === "codex" ? ["codex mcp list", "rolino auth login"] : ["claude mcp get rolino", "rolino auth login"]
+          result.client === "codex" ? result.transport === "http" ? ["codex mcp login rolino", "codex mcp list"] : ["rolino auth login", "codex mcp list"] : result.transport === "http" ? ["claude mcp get rolino", "Complete OAuth when Claude prompts you"] : ["rolino auth login", "claude mcp get rolino"]
         );
       }
     });
@@ -2247,6 +2317,106 @@ Revision: ${local.revision}` });
       writeSuccess(context, data, JSON.stringify(data, null, 2));
     } });
   });
+  const backlinks = program.command("backlinks").description("Review backlink prospects and public contact drafts. Rolino never sends email.");
+  const backlinkTargets = backlinks.command("targets");
+  backlinkTargets.command("list").requiredOption("--project <project-id>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks targets list", global, runtime, async action(context, client) {
+      const data = await client.backlinks.targets.list(local.project, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinkTargets.command("add").requiredOption("--project <project-id>").requiredOption("--url <url>").requiredOption("--label <label>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks targets add", global, runtime, async action(context, client) {
+      const data = await client.backlinks.targets.add(local.project, { url: local.url, label: local.label }, context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinks.command("discover").requiredOption("--project <project-id>").option("--limit <number>", "maximum saved prospects", Number, 20).option("--idempotency-key <key>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks discover", global, runtime, async action(context, client) {
+      const data = await client.backlinks.discoveries.start(local.project, { limit: local.limit }, local.idempotencyKey ?? context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  const backlinkRuns = backlinks.command("runs");
+  backlinkRuns.command("get").requiredOption("--project <project-id>").requiredOption("--run <run-id>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks runs get", global, runtime, async action(context, client) {
+      const data = await client.backlinks.discoveries.get(local.project, local.run, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  const backlinkProspects = backlinks.command("prospects");
+  backlinkProspects.command("list").requiredOption("--project <project-id>").option("--stage <stage>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks prospects list", global, runtime, async action(context, client) {
+      const stage = local.stage ? import_contracts.BacklinkProspectStageSchema.parse(local.stage.toUpperCase()) : void 0;
+      const data = await client.backlinks.prospects.list(local.project, { stage }, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinkProspects.command("get").requiredOption("--project <project-id>").requiredOption("--prospect <prospect-id>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks prospects get", global, runtime, async action(context, client) {
+      const data = await client.backlinks.prospects.get(local.project, local.prospect, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinkProspects.command("approve").requiredOption("--project <project-id>").requiredOption("--prospect <prospect-id>").requiredOption("--expected-version <number>", "current optimistic version", Number).action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks prospects approve", global, runtime, async action(context, client) {
+      const data = await client.backlinks.prospects.updateStage(local.project, local.prospect, { stage: "APPROVED", expectedVersion: local.expectedVersion }, context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  const backlinkContacts = backlinks.command("contacts");
+  backlinkContacts.command("research").requiredOption("--project <project-id>").requiredOption("--prospect <prospect-id>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks contacts research", global, runtime, async action(context, client) {
+      const data = await client.backlinks.prospects.researchContact(local.project, local.prospect, context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinkContacts.command("list").requiredOption("--project <project-id>").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks contacts list", global, runtime, async action(context, client) {
+      const data = await client.backlinks.contacts.list(local.project, { limit: 50 }, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinkContacts.command("export").requiredOption("--project <project-id>").option("--format <format>", "json or csv", "csv").action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks contacts export", global, runtime, async action(context, client) {
+      const data = await client.backlinks.contacts.list(local.project, { limit: 50 }, { requestId: context.requestId });
+      if (local.format !== "csv") return writeSuccess(context, data, JSON.stringify(data, null, 2));
+      const cell = (value) => {
+        let text = String(value ?? "").replace(/[\r\n]+/g, " ");
+        if (/^[=+\-@\t]/.test(text)) text = `'${text}`;
+        return `"${text.replaceAll('"', '""')}"`;
+      };
+      const csv = ["prospectId,name,role,email,sourceUrl,checkedAt", ...data.items.map((item) => [item.prospectId, item.name, item.role, item.email, item.sourceUrl, item.checkedAt].map(cell).join(","))].join("\n");
+      context.stdout.write(`${csv}
+`);
+    } });
+  });
+  const backlinkOutreach = backlinks.command("outreach");
+  backlinkOutreach.command("update").requiredOption("--project <project-id>").requiredOption("--prospect <prospect-id>").requiredOption("--file <file>").requiredOption("--expected-version <number>", "current draft version", Number).action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks outreach update", global, runtime, async action(context, client) {
+      const payload = JSON.parse(await (0, import_promises2.readFile)((0, import_node_path2.resolve)(runtime.cwd, local.file), "utf8"));
+      const data = await client.backlinks.prospects.updateOutreach(local.project, local.prospect, { ...payload, expectedVersion: local.expectedVersion }, context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
+  backlinks.command("verify").requiredOption("--project <project-id>").requiredOption("--prospect <prospect-id>").requiredOption("--url <url>").requiredOption("--expected-version <number>", "current prospect version", Number).action(async (local) => {
+    const global = program.opts();
+    commandExitCode = await execute({ command: "backlinks verify", global, runtime, async action(context, client) {
+      const data = await client.backlinks.prospects.verify(local.project, local.prospect, { url: local.url, expectedVersion: local.expectedVersion }, context.requestId, { requestId: context.requestId });
+      writeSuccess(context, data, JSON.stringify(data, null, 2));
+    } });
+  });
   const seo = program.command("seo").description("Read authorized SEO opportunities and weekly reports");
   const seoOpportunities = seo.command("opportunities").description("Read accepted SEO opportunities");
   seoOpportunities.command("list").description("List bounded SEO opportunities").requiredOption("--project <project-id>", "exact Rolino project ID").option("--limit <number>", "maximum opportunities to return", (value) => {