Skip to content

Commit 850e6a4

Browse files
sepo-engopencodeclaude
authored
fix: derive user-facing docs links from the live instance, else drop (TKT-414) (#52)
* fix(app,core,cli): derive user-facing docs links from the live instance, else drop (TKT-414) TKT-397 fixed the model-facing prompt files; this closes the 5 user-facing surfaces from feedback anomalyco#208 with the same mechanism and the same failure mode: opencode.ai/docs describes upstream, not this fork. - desktop-menu.ts's Documentation entry now dispatches through the desktop command registry (docs.open) instead of a static href, matching the exportLogs precedent. DesktopCommands() derives <connected-server>/docs via a new pure desktopDocsUrl() helper and opens it with platform.openExternal; the command is only offered while a server is actually connected. - providers.ts's Cloudflare AI Gateway hint and github.handler.ts's `github install` outro are both standalone-CLI surfaces with no live server instance -- URL dropped, prose kept. - config.ts's `command`/`agent` schema descriptions (editor tooltips, no runtime instance context) -- URL dropped, prose kept. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01M1CJmqai46ihahdKMVNB27 * fix(app): register docs.open unconditionally, honest toast when disconnected (TKT-414 review) Peer review (Henry) found the macOS native menu has no per-command enabled/disabled plumbing (packages/desktop/src/main/menu.ts's nativeItem only special-cases "updater"), so gating the command's registration on a connected server left the item always clickable there and silently doing nothing when disconnected -- presence without function, worse than the "absence over wrongness" the ticket asks for. Windows already disables it correctly via commandDisabled, but the fix should not depend on which native menu implementation is rendering it. Register docs.open unconditionally on desktop; onSelect resolves the URL at click time and opens it, or shows a toast naming why it can't ("Documentation is served by a running instance...") when no server is connected. One more i18n key (command.docs.unavailable), same pending-first-attempt bookkeeping as command.docs.open. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01M1CJmqai46ihahdKMVNB27 * docs(web): relink two shipped docs pages within the docs bundle, not to upstream (TKT-414 review) mcp-servers.mdx and plugins.mdx used absolute https://opencode.ai/docs/... links where every other page in this same directory uses the established root-relative /docs/... convention. Both files ship inside the embedded docs bundle TKT-391 serves at this build's own /docs -- the absolute form reopened the loop TKT-397/#47 closed one level down: the model is told to trust this instance's own docs, and one level inside them a link sent the reader back to upstream. Mechanical fix, matching the convention already used by every sibling page (config.mdx, sdk.mdx, etc.). Per Ethan/Henry's review: the READMEs and install script from a separate audit (anomalyco#220) are explicitly out of scope here -- a product decision for the consolidation round, not touched. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01M1CJmqai46ihahdKMVNB27 --------- Co-authored-by: opencode <[email protected]> Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent f7c543c commit 850e6a4

12 files changed

Lines changed: 205 additions & 11 deletions

File tree

‎packages/app/src/app.tsx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ import { SessionEntitiesProvider } from "@/context/session-entities-provider"
5959
import { SessionEntitiesSync } from "@/context/session-entities-sync"
6060
import { SDKProvider, useSDK } from "@/context/sdk"
6161
import { WslServersProvider } from "@/wsl/context"
62+
import { desktopDocsUrl } from "@/desktop-docs"
63+
import { showToast } from "@/utils/toast"
6264
import DirectoryLayout, { DirectoryDataProvider } from "@/pages/directory-layout"
6365
import LegacyLayout from "@/pages/layout"
6466
import NewLayout from "@/pages/layout-new"
@@ -331,6 +333,7 @@ function DesktopCommands() {
331333
const command = useCommand()
332334
const language = useLanguage()
333335
const platform = usePlatform()
336+
const server = useServer()
334337

335338
command.register("desktop", () => {
336339
const commands: CommandOption[] = []
@@ -344,6 +347,26 @@ function DesktopCommands() {
344347
},
345348
})
346349
}
350+
// TKT-414 review (Henry): registered unconditionally, not gated on a connected server --
351+
// the macOS native menu (packages/desktop/src/main/menu.ts) has no per-command
352+
// enabled/disabled plumbing, so gating the registration left the item always clickable
353+
// there but silently doing nothing when disconnected. Always-registered + an honest
354+
// no-server message is the "absence over wrongness" shape without adding that plumbing.
355+
if (platform.platform === "desktop") {
356+
commands.push({
357+
id: "docs.open",
358+
title: language.t("command.docs.open"),
359+
category: language.t("command.category.settings"),
360+
onSelect: () => {
361+
const docsUrl = desktopDocsUrl(server.current?.http.url)
362+
if (docsUrl) {
363+
platform.openExternal(docsUrl)
364+
return
365+
}
366+
showToast({ title: language.t("command.docs.open"), description: language.t("command.docs.unavailable") })
367+
},
368+
})
369+
}
347370
return commands
348371
})
349372

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import { describe, expect, test } from "bun:test"
2+
import { desktopDocsUrl } from "./desktop-docs"
3+
4+
describe("desktopDocsUrl", () => {
5+
test("derives /docs on the connected server's own origin", () => {
6+
expect(desktopDocsUrl("http://127.0.0.1:4096")).toBe("http://127.0.0.1:4096/docs")
7+
})
8+
9+
test("drops the URL when no server is connected, rather than guessing", () => {
10+
expect(desktopDocsUrl(undefined)).toBeUndefined()
11+
})
12+
})

‎packages/app/src/desktop-docs.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// TKT-414: this build serves its own docs (TKT-391) at the connected server's own origin --
2+
// opencode.ai/docs describes a different program. undefined (no connected server) means don't
3+
// offer the command at all; absence over wrongness, per TKT-397/TKT-414.
4+
export function desktopDocsUrl(serverUrl: string | undefined) {
5+
if (!serverUrl) return undefined
6+
return new URL("/docs", serverUrl).toString()
7+
}

‎packages/app/src/desktop-menu.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,15 @@ describe("desktop menu", () => {
1111
expect(items.every((item) => item.type === "item" && item.command === "logs.export" && !item.action)).toBe(true)
1212
})
1313

14+
test("opens documentation through the desktop command registry, not a hardcoded upstream URL", () => {
15+
const items = DESKTOP_MENU.flatMap((menu) => menu.items ?? []).filter(
16+
(item) => item.type === "item" && item.labelKey === "desktop.menu.documentation",
17+
)
18+
19+
expect(items).toHaveLength(1)
20+
expect(items.every((item) => item.type === "item" && item.command === "docs.open" && !item.href)).toBe(true)
21+
})
22+
1423
test("provides translated labels for role-backed entries", () => {
1524
const windowMenu = DESKTOP_MENU.find((menu) => menu.role === "windowMenu")
1625
const roleItems = DESKTOP_MENU.flatMap((menu) => menu.items ?? []).filter(

‎packages/app/src/desktop-menu.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ export const DESKTOP_MENU: DesktopMenu[] = [
279279
id: "help",
280280
labelKey: "desktop.menu.help",
281281
items: [
282-
{ type: "item", labelKey: "desktop.menu.documentation", href: "https://opencode.ai/docs" },
282+
{ type: "item", labelKey: "desktop.menu.documentation", command: "docs.open" },
283283
{ type: "item", labelKey: "desktop.menu.supportForum", href: "https://discord.com/invite/opencode" },
284284
{ type: "item", labelKey: "desktop.menu.exportLogs", command: "logs.export" },
285285
{ type: "separator" },

‎packages/app/src/i18n/en.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ export const dict = {
2020
"command.category.workspace": "Workspace",
2121
"command.category.settings": "Settings",
2222
"command.logs.export": "Export logs",
23+
"command.docs.open": "Open documentation",
24+
"command.docs.unavailable": "Documentation is served by a running instance. Connect to a server to open it.",
2325

2426
"theme.scheme.system": "System",
2527
"theme.scheme.light": "Light",

‎packages/app/src/i18n/parity.test.ts‎

Lines changed: 137 additions & 3 deletions
Large diffs are not rendered by default.

‎packages/core/src/v1/config/config.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,11 @@ export const Info = Schema.Struct({
3838
server: Schema.optional(ConfigServerV1.Server).annotate({
3939
description: "Server configuration for opencode serve and web commands",
4040
}),
41+
// TKT-414: a schema description has no live-instance context (it's read by external editors,
42+
// not this running build) -- opencode.ai/docs describes a different program for a fork.
43+
// Absence over wrongness: drop the URL, keep the prose, per TKT-397/TKT-414.
4144
command: Schema.optional(Schema.Record(Schema.String, ConfigCommandV1.Info)).annotate({
42-
description: "Command configuration, see https://opencode.ai/docs/commands",
45+
description: "Command configuration",
4346
}),
4447
skills: Schema.optional(ConfigSkillsV1.Info).annotate({ description: "Additional skill folder paths" }),
4548
references: Schema.optional(ConfigReference.Info).annotate({
@@ -106,7 +109,7 @@ export const Info = Schema.Struct({
106109
}),
107110
[Schema.Record(Schema.String, ConfigAgentV1.Info)],
108111
),
109-
).annotate({ description: "Agent configuration, see https://opencode.ai/docs/agents" }),
112+
).annotate({ description: "Agent configuration" }),
110113
provider: Schema.optional(Schema.Record(Schema.String, ConfigProviderV1.Info)).annotate({
111114
description: "Custom provider configurations and model overrides",
112115
}),

‎packages/opencode/src/cli/cmd/github.handler.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,9 @@ export const githubInstall = Effect.fn("Cli.github.install")(function* () {
193193
].join("\n")
194194
}
195195

196+
// TKT-414: `github install` is a standalone setup wizard, no live server instance --
197+
// opencode.ai/docs describes a different program. Absence over wrongness: drop the
198+
// URL, keep the prose, per TKT-397/TKT-414.
196199
prompts.outro(
197200
[
198201
"Next steps:",
@@ -201,8 +204,6 @@ export const githubInstall = Effect.fn("Cli.github.install")(function* () {
201204
step2,
202205
"",
203206
" 3. Go to a GitHub issue and comment `/oc summarize` to see the agent in action",
204-
"",
205-
" Learn more about the GitHub agent - https://opencode.ai/docs/github/#usage-examples",
206207
].join("\n"),
207208
)
208209
}

‎packages/opencode/src/cli/cmd/providers.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -472,8 +472,11 @@ export const ProvidersLoginCommand = effectCmd({
472472
}
473473

474474
if (["cloudflare", "cloudflare-ai-gateway"].includes(provider)) {
475+
// TKT-414: this is a disconnected-CLI hint (auth login runs standalone, no live
476+
// server instance) -- opencode.ai/docs describes a different program. Absence over
477+
// wrongness: drop the URL, keep the prose, per TKT-397/TKT-414.
475478
yield* Prompt.log.info(
476-
"Cloudflare AI Gateway can be configured with CLOUDFLARE_GATEWAY_ID, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_API_TOKEN environment variables. Read more: https://opencode.ai/docs/providers/#cloudflare-ai-gateway",
479+
"Cloudflare AI Gateway can be configured with CLOUDFLARE_GATEWAY_ID, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_API_TOKEN environment variables.",
477480
)
478481
}
479482

0 commit comments

Comments
 (0)