WeKnora/cli/cmd/doc/fetch.go

169 lines
6.7 KiB
Go
Raw Normal View History

refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
// Package doc — fetch.go implements `weknora doc fetch <url>`.
package doc
import (
"cmp"
"context"
"errors"
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
)
// docFetchFields enumerates the fields surfaced for `--format json` discovery
// on `doc fetch`.
var docFetchFields = []string{
"id", "knowledge_base_id", "tag_id", "type", "title", "description",
"source", "channel", "parse_status", "summary_status", "enable_status",
"embedding_model_id", "file_name", "file_type", "file_size", "file_hash",
"file_path", "storage_size",
"created_at", "updated_at", "processed_at", "error_message",
}
// FetchOptions holds CLI flag values for `doc fetch`.
type FetchOptions struct {
URL string
Name string // --name: FileName hint for file-vs-crawl mode detection
Title string // --title: display title for the new entry
FileType string // --file-type: extension hint for extension-less URLs
TagID string // --tag-id: associate the new entry with a tag
Channel string // --channel: ingestion-channel tag (default "api")
EnableMultimodel *bool // tri-state: nil = server default
feat(cli): --dry-run + risk metadata + validation parity on 19 mutations Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action=<action> on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: <action> (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally
2026-05-27 20:28:48 +00:00
DryRun bool
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
}
// FetchService is the narrow SDK surface for `doc fetch`.
// *sdk.Client satisfies it.
type FetchService interface {
CreateKnowledgeFromURL(
ctx context.Context,
kbID string,
req sdk.CreateKnowledgeFromURLRequest,
) (*sdk.Knowledge, error)
}
// NewCmdFetch builds `weknora doc fetch <url>`.
func NewCmdFetch(f *cmdutil.Factory) *cobra.Command {
opts := &FetchOptions{}
cmd := &cobra.Command{
Use: "fetch <url>",
Short: "Fetch a remote document into a knowledge base",
Long: `Server fetches the document at the given URL and ingests it into the resolved
knowledge base. KB resolution follows the standard 4-level chain:
--kb flag > WEKNORA_KB_ID env > .weknora/project.yaml > error.
When the URL has a known file extension (.pdf, .docx, .md, .txt) the server
automatically switches from web-page-crawl mode to file-download mode. Pass
--file-type or --name with a recognisable extension to force file-download mode
for extension-less URLs.
Server-side ingestion knobs:
--name <name> Override the recorded file name; also used as the
file-type hint when the extension is recognisable.
--title <title> Set the display title stored with the entry.
--file-type <ext> Explicit file-type hint (e.g. "pdf") for URLs
without an extension.
--tag-id <id> Associate the new entry with a tag.
--enable-multimodel Toggle multimodal extraction (image-in-PDF → text).
Unset ⇒ server default; pass true or false to override.
--channel <name> Override the ingestion-channel tag (default "api").`,
Example: ` weknora doc fetch https://example.com/whitepaper.pdf
weknora doc fetch https://example.com/no-ext --file-type pdf --title "Whitepaper"
weknora doc fetch https://example.com/article.html --name "Q3 Article" --tag-id tag_abc
weknora doc fetch https://example.com/report.pdf --kb my-kb --enable-multimodel`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.URL = args[0]
fopts, err := cmdutil.CheckFormatFlag(c)
if err != nil {
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
feat(cli): --dry-run + risk metadata + validation parity on 19 mutations Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action=<action> on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: <action> (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally
2026-05-27 20:28:48 +00:00
// Pure-local validation runs before the dry-run gate so --dry-run
// rejects identically to the live path.
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
if c.Flags().Changed("enable-multimodel") {
raw, _ := c.Flags().GetString("enable-multimodel")
v, perr := parseTriBool(raw)
if perr != nil {
return perr
}
opts.EnableMultimodel = &v
}
if err := cmdutil.ValidateHTTPURL("<url>", opts.URL); err != nil {
return err
}
feat(cli): --dry-run + risk metadata + validation parity on 19 mutations Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action=<action> on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: <action> (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally
2026-05-27 20:28:48 +00:00
if opts.DryRun {
// Local-only KB resolution: plan reports the raw --kb value
// (UUID or name) without an SDK lookup.
kbID, err := f.ResolveKBLocal(c)
if err != nil {
return err
}
if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{
Action: "doc.fetch",
Args: map[string]any{
"url": opts.URL,
"kb": kbID,
},
}); handled {
return err
}
}
cli, err := f.Client()
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
if err != nil {
return err
}
feat(cli): --dry-run + risk metadata + validation parity on 19 mutations Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action=<action> on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: <action> (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally
2026-05-27 20:28:48 +00:00
kbID, err := f.ResolveKB(c)
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
if err != nil {
return err
}
return runFetch(c.Context(), opts, fopts, cli, kbID)
},
}
refactor(cli): finish context→profile cascade + post-review hardening (BREAKING) Post-review polish on the v0.7 wire / surface contract. Bundles five follow-ups that landed after the main BREAKING feat commit: 1. Complete context→profile cascade (internal API + YAML schema) The prior commit renamed only the user-visible surface (commands / flags / env / project link / envelope field). The internal Go API and on-disk config schema were still half-renamed — an L-25 self-consistency violation flagged by post-merge review. Closed here: Internal Go API: - config.Context → config.Profile - config.Config.CurrentContext → CurrentProfile - config.Config.Contexts → Profiles - LoginOptions.Context → LoginOptions.Profile - clearContextSecrets() → clearProfileSecrets() - saveContextRef() → saveProfileRef() - secrets.Store: param name `context` → `profile` (interface + FileStore + KeyringStore + MemStore) - cmdutil.LoadSecret(store, context, key) → LoadSecret(store, profile, key) - cmdutil.RefreshAndPersist's ctxName → profileName - Local var `ctx := &config.Profile{...}` → `prof := &config.Profile{...}` in auth/login.go to eliminate the visual collision with Go stdlib context.Context that motivated the whole rename in the first place. On-disk config.yaml schema: - current_context: → current_profile: - contexts: → profiles: - Pre-1.0 break, no compat alias. Users on v0.6 dogfooded configs must delete ~/.config/weknora/config.yaml or hand-rename the two keys (CHANGELOG migration note added). Tests / fixtures / golden files: - factory_test.go YAML fixture + assertion updated. - acceptance/e2e/e2e_test.go writeContextYAML → writeProfileYAML, fixture YAML keys updated. - acceptance/testdata/wire/doctor.error_network.json golden updated ("active context" → "active profile" in hint string). User-visible prose sweep: - cmd/mcp/serve.go --help Long: "active context (or --context)" → "active profile (or --profile)" — most-visible miss. - cmd/{kb/list, search/kb, session/list, api/api} Short/Long help. - cmd/auth/login.go stdout: `(context=%s)` → `(profile=%s)`. - cmd/auth/logout.go error: `"no current context"` → `"no current profile"`. - cmd/doctor/doctor.go hint string (also the wire golden above). - cmd/auth/refresh.go error: `"refresh token missing for context"` → `"refresh token missing for profile"`. - README.md: `## Multi-context` H2 → `## Multi-profile`; code-block comment `# current context` → `# current profile`. Code-comment / docstring sweep across cli/cmd/auth/ and cli/internal/cmdutil/. Comments referencing Go stdlib context.Context, the RAG / LLM "context window" concept, and historical CHANGELOG entries for v0.4 / v0.5 were left alone. CHANGELOG v0.7 BREAKING entry gains the on-disk-schema bullet under the existing "context → profile" item. 2. Profile name validation (shell-injection guard) `envelope.error.retry_command` is a single shell-string field. An AI agent that exec()s it via `sh -c <retry_command>` was injectable through a maliciously-named profile: weknora auth logout --name 'x; rm -rf ~' # would produce: retry_command = "weknora auth logout --name x; rm -rf ~ -y" `cmd/profile/add.go` already enforced an alphanumeric + `-_.` allowlist via `validateName`. The `auth login` and `auth logout` paths bypassed it. - Moved validation from `cmd/profile/add.go` to `cli/internal/cmdutil/profilename.go` as exported `ValidateProfileName` (cmdutil is the import-cycle-safe home; internal/config can't depend on cmdutil). - `auth login` runs the validator before any persist call. - `auth logout` runs the validator on `opts.Name` before constructing `retry_command`. - Unit tests (`profilename_test.go`) cover the allowlist, empty rejection, path-traversal, shell metacharacters (`;`, `&`, `|`, `$()`, backticks, quotes, whitespace, glob, redirects), and the user-facing hint text. The shell-metachar test exists as a regression guard. Wire shape (`retry_command` string → `retry_command_argv []string`) remains a v0.8 additive change per ROADMAP — this fix removes the practical exploit path without touching the wire contract. 3. AI-agent terminology disambiguation "agent" has three referents in this codebase: (a) WeKnora's server-side Custom Agent resource, (b) the removed `agent invoke` verb, (c) external LLM/automation consumers. Per project memory feedback_no_meta_disambiguation_in_docs, the fix is full-term naming, not "X has N meanings" prose. Surgical changes at section headers + ambiguous prose: - AGENTS.md: "Agent decision shortcuts" → "AI agent decision shortcuts"; "agent-callable surface" → "AI-agent-callable surface". - README.md: "Designed to be agent-first" → "AI-agent-first"; "Other agent ergonomics" → "Other AI-agent ergonomics"; "in agent contexts" → "in AI-agent contexts"; "for CI / agents" → "for CI / AI agents". Anaphoric "agents" inside paragraphs that already established "AI agents" was left alone — full substitution everywhere would have been prose noise without clarity gain. 4. Wire-contract review follow-ups Real findings from a second-pass review of the v0.7 envelope / streaming / surface design. Per project memory feedback_check_in_domain_anchor_first, candidate findings were first verified against the in-domain peer CLI explicitly cited as the envelope anchor; two earlier-flagged issues turned out to be in-pattern and were withdrawn. Surviving fixes: - AGENTS.md success-envelope example rewritten. The prior example showed `has_more: false` / `_notice: {}` as if they were always present, but both fields are `omitempty` and never serialize when zero / nil. Replaced with three realistic shapes (list / single resource / mutation with no payload) and added a note that optional fields are omitted when empty. - cmd/chat/chat.go Args: MinimumNArgs(1) → ExactArgs(1). v0.6 silently joined `weknora chat hello world` into `"hello world"`. v0.7 now rejects multi-arg with exit 2, matching `weknora session ask`. BREAKING; CHANGELOG entry added under v0.7 BREAKING. - internal/output/envelope.go extracts NewEnvelope(data, meta, profile) constructor. The jq-filter path in cmdutil.FormatOptions.Emit was manually rebuilding the envelope literal alongside the canonical WriteEnvelope path — drift risk when fields are added. Single construction point now. - internal/cmdutil/factory.go adds AddKBFlag(cmd) helper. Five files (chat, doc/list, doc/upload, doc/create, doc/fetch) had verbatim-identical `cmd.Flags().String("kb", ...)` declarations. Centralised so flag name + help text stay in sync with Factory.ResolveKB. Docstring reordering + gofmt fixup landed in the same edit to keep ResolveKB's own godoc attached to its function. 5. OSS-readiness comment / doc sweep Pre-publication scrub of code, comments, and shipped Markdown to remove references that only make sense in the development repo: - AGENTS.md "Deliberate deviations + mainstream alignments" section: removed peer-project name-drops from the comparison table; rewrote as five flagged design decisions with rationale but no specific competitor named. The four rows that previously contrasted against a named peer CLI now state WeKnora's choice + rationale directly. Section header renamed to "Design decisions worth flagging" since it is no longer a deviation/alignment matrix. - CHANGELOG v0.7 BREAKING rationales: three references to a named peer CLI removed; the context→profile rationale now cites only mainstream multi-credential CLIs by category (AWS / Stripe / OpenAI / Anthropic), and the `api -d/--data` removal rationale cites only `gh api` / `curl`. `chat` BREAKING entry rationale similarly simplified. - 35 cross-references to design-spec section numbers (§4.1 / §4.5 / §5.3 etc.) removed from Go doc comments and test comments across 13 files. The referenced spec lives outside the shipped tree; readers of the public repo cannot resolve them. Each reference replaced with a self-contained semantic description (e.g. "the batch envelope" / "AGENTS.md section on the success path"). - Mixed-language strings translated to English: - Four Go comments: internal/cmdutil/exit.go:213,215, internal/cmdutil/errors.go:156, internal/output/batch_test.go:90, internal/output/envelope_test.go:27. - One CHANGELOG section title: `v0.7 — Agent-first wire contract + 命令面集中清理` → `... + command-surface cleanup`. - CJK test fixtures (internal/text/truncate_test.go CJK truncation cases, cmd/session/list_test.go Chinese session title, acceptance/e2e/e2e_test.go Chinese RAG corpus) retained — they are intentional test inputs, not stray prose. - Makefile help comment: `golangci-lint added in PR-9` → `golangci-lint planned`. Internal PR numbering should not surface in shipped Makefile prose. Build green, 28/28 packages, +5 new ValidateProfileName tests. go vet / gofmt / go mod verify / go mod tidy all clean. Rationale for the cascade: pre-1.0 is the cheapest moment to close L-25 self-consistency (L-26). The half-finished internal rename would have perpetuated the very `context` vs `context.Context` ambiguity that motivated v0.7's user-visible rename in the first place.
2026-05-21 15:44:16 +00:00
cmdutil.AddKBFlag(cmd)
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
cmd.Flags().StringVar(&opts.Name, "name", "", "File name hint (also used as file-type hint when extension is recognisable)")
cmd.Flags().StringVar(&opts.Title, "title", "", "Display title for the new entry")
cmd.Flags().StringVar(&opts.FileType, "file-type", "", "File-type hint such as \"pdf\" when the URL has no extension")
cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Tag id to associate with the new entry")
cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")")
cmd.Flags().String("enable-multimodel", "", "Toggle multimodal extraction (true|false); unset ⇒ server default")
cmd.Flags().Lookup("enable-multimodel").NoOptDefVal = "true"
cmdutil.AddFormatFlag(cmd, docFetchFields...)
feat(cli): --dry-run + risk metadata + validation parity on 19 mutations Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action=<action> on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: <action> (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally
2026-05-27 20:28:48 +00:00
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "Ingest a remote URL into the resolved knowledge base. KB resolved via --kb flag, WEKNORA_KB_ID env, or project link. Emits the created Knowledge object with its id.",
RequiredFlags: []string{"<url> (positional)", "--kb (or WEKNORA_KB_ID / project link)"},
Examples: []string{
`weknora doc fetch https://example.com/whitepaper.pdf --kb kb_eng`,
},
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, source, parse_status",
})
refactor(cli): command-surface rename — session ask / doc fetch / doc create / doc delete --all Three command renames consolidate the v0.7 verb table: - `weknora agent invoke` → `weknora session ask --agent <id>`. Server route POST /sessions/{session_id}/agent-qa is session- anchored, so the verb moves with it. `weknora agent` subtree keeps CRUD only (list / view / create / edit / delete / status / check). SDK call (AgentQAStreamWithRequest) preserved verbatim; only the command surface + flag layout move. - `weknora doc upload` split into three commands: - `weknora doc upload <file>` — local file (only). - `weknora doc fetch <url>` — server-side remote fetch (was `upload --from-url`). URL-only flags (--title / --file-type / --tag-id) move with the verb. - `weknora doc create --text` — direct text knowledge entry via server CreateManualKnowledge. - `weknora kb empty <id>` → `weknora doc delete --all --kb=<id>`. Atomic server ClearKnowledgeBaseContents (no list-then-delete race). Same exit-10 -y/--yes guard as other destructive verbs; unified through the extended ConfirmDestructive helper. Parent commands (agent, kb, doc, chunk, session, auth, profile, search) lose their explicit Args:NoArgs + Run:cmd.Help so the unknown-subcommand guard fires correctly — `weknora agent invoke ag_x q` now emits the typed input.unknown_subcommand envelope with detail.available[] instead of cobra's free-form exit-2 prose. Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §3.4 / §10.7
2026-05-21 10:42:27 +00:00
return cmd
}
// runFetch ingests a remote URL via SDK CreateKnowledgeFromURL.
func runFetch(ctx context.Context, opts *FetchOptions, fopts *cmdutil.FormatOptions, svc FetchService, kbID string) error {
req := sdk.CreateKnowledgeFromURLRequest{
URL: opts.URL,
FileName: opts.Name,
FileType: opts.FileType,
EnableMultimodel: opts.EnableMultimodel,
Title: opts.Title,
TagID: opts.TagID,
Channel: cmp.Or(opts.Channel, uploadChannel),
}
k, err := svc.CreateKnowledgeFromURL(ctx, kbID, req)
if err != nil {
if errors.Is(err, sdk.ErrDuplicateURL) {
return cmdutil.Wrapf(cmdutil.CodeResourceAlreadyExists, err,
"URL already ingested into this knowledge base")
}
return cmdutil.WrapHTTP(err, "fetch document from %s", opts.URL)
}
return renderUploadSuccess(k, fopts, "Ingested", opts.Name, opts.URL)
}