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
This commit is contained in:
+20
-130
@@ -1,6 +1,7 @@
|
||||
package doc
|
||||
|
||||
import (
|
||||
"cmp"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
@@ -35,7 +36,6 @@ type UploadOptions struct {
|
||||
Name string
|
||||
Recursive bool // --recursive: positional arg is a directory; walk + upload each match
|
||||
Glob string // --glob: filename pattern under --recursive (default "*")
|
||||
FromURL string // --from-url: ingest a remote URL via SDK CreateKnowledgeFromURL
|
||||
|
||||
// EnableMultimodel toggles server-side multimodal extraction
|
||||
// (e.g. images-in-PDF → OCR'd text). nil means "server default" -
|
||||
@@ -49,12 +49,6 @@ type UploadOptions struct {
|
||||
// Channel overrides the ingestion-channel tag recorded server-side.
|
||||
// Empty ⇒ uploadChannel ("api"). Free-form: server validates.
|
||||
Channel string
|
||||
|
||||
// URL-mode only fields. RunE-side validation rejects these if
|
||||
// --from-url is not set (positional file path or --recursive).
|
||||
Title string // --title: display title (URL mode)
|
||||
FileType string // --file-type: extension hint for extension-less URLs
|
||||
TagID string // --tag-id: associate the new knowledge entry with a tag
|
||||
}
|
||||
|
||||
// UploadService is the narrow SDK surface this command depends on.
|
||||
@@ -67,11 +61,6 @@ type UploadService interface {
|
||||
enableMultimodel *bool,
|
||||
customFileName, channel string,
|
||||
) (*sdk.Knowledge, error)
|
||||
CreateKnowledgeFromURL(
|
||||
ctx context.Context,
|
||||
kbID string,
|
||||
req sdk.CreateKnowledgeFromURLRequest,
|
||||
) (*sdk.Knowledge, error)
|
||||
}
|
||||
|
||||
// NewCmdUpload builds `weknora doc upload <file>`.
|
||||
@@ -89,35 +78,28 @@ Pass --name to override the recorded file name (useful when the local file
|
||||
has a generic name like "report.pdf" but you want to surface it as e.g.
|
||||
"Q3 Marketing Report.pdf" in the UI).
|
||||
|
||||
The three input modes (positional file / --recursive directory walk /
|
||||
--from-url remote ingest) are mutually exclusive - pass exactly one.
|
||||
Use --recursive --glob to upload a directory tree (see Examples).
|
||||
The two input modes (positional file / --recursive directory walk) are
|
||||
mutually exclusive - pass exactly one. Use --recursive --glob to upload a
|
||||
directory tree (see Examples). To ingest a remote URL use "weknora doc fetch";
|
||||
to create an entry from inline text use "weknora doc create".
|
||||
|
||||
Server-side ingestion knobs:
|
||||
|
||||
--enable-multimodel Toggle multimodal extraction (image-in-PDF → text).
|
||||
Unset ⇒ server default; pass true or false to override.
|
||||
Applies to file / --recursive / --from-url.
|
||||
Applies to file / --recursive.
|
||||
--metadata key=value Attach arbitrary key/value metadata. Repeatable.
|
||||
Empty value allowed; duplicate keys ⇒ last-wins.
|
||||
Malformed values (no '=', empty key) ⇒
|
||||
input.invalid_argument. File and --recursive modes
|
||||
only; rejected on --from-url because the URL-ingest
|
||||
request type carries no metadata field.
|
||||
input.invalid_argument.
|
||||
--channel <name> Override the ingestion-channel tag (default "api").
|
||||
Applies to file / --recursive / --from-url.
|
||||
|
||||
URL mode (--from-url) additionally accepts --title, --file-type, and --tag-id.
|
||||
Passing any of those without --from-url is rejected as input.invalid_argument.`,
|
||||
Applies to file / --recursive.`,
|
||||
Example: ` weknora doc upload report.pdf
|
||||
weknora doc upload notes.md --kb a32a63ff-fb36-4874-bcaa-30f48570a694
|
||||
weknora doc upload notes.md --kb my-kb
|
||||
weknora doc upload q3.pdf --name "Q3 Marketing Report.pdf"
|
||||
weknora doc upload report.pdf --enable-multimodel --metadata team=alpha --metadata sprint=Q4
|
||||
weknora doc upload ./docs --recursive --glob '*.pdf' --metadata team=alpha
|
||||
weknora doc upload --from-url https://example.com/whitepaper.pdf
|
||||
weknora doc upload --from-url https://example.com/no-ext --file-type pdf --title "Whitepaper"
|
||||
weknora doc upload --from-url https://example.com/article.html --name "Q3 Article" --tag-id tag_abc`,
|
||||
weknora doc upload ./docs --recursive --glob '*.pdf' --metadata team=alpha`,
|
||||
Args: cobra.MaximumNArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
@@ -149,33 +131,25 @@ Passing any of those without --from-url is rejected as input.invalid_argument.`,
|
||||
return err
|
||||
}
|
||||
|
||||
switch {
|
||||
case opts.FromURL != "":
|
||||
return runUploadFromURL(c.Context(), opts, fopts, cli, kbID)
|
||||
case opts.Recursive:
|
||||
if opts.Recursive {
|
||||
return runUploadRecursive(c.Context(), opts, fopts, cli, kbID, args[0])
|
||||
default:
|
||||
if err := validateUploadPath(args[0]); err != nil {
|
||||
return err
|
||||
}
|
||||
return runUpload(c.Context(), opts, fopts, cli, kbID, args[0])
|
||||
}
|
||||
if err := validateUploadPath(args[0]); err != nil {
|
||||
return err
|
||||
}
|
||||
return runUpload(c.Context(), opts, fopts, cli, kbID, args[0])
|
||||
},
|
||||
}
|
||||
cmd.Flags().String("kb", "", "Knowledge base UUID or name (overrides env / project link)")
|
||||
cmd.Flags().StringVar(&opts.Name, "name", "", "Custom file name to record (defaults to base name)")
|
||||
cmd.Flags().BoolVar(&opts.Recursive, "recursive", false, "Treat the positional argument as a directory to walk")
|
||||
cmd.Flags().StringVar(&opts.Glob, "glob", "*", "Filename pattern to filter when --recursive (e.g. '*.pdf')")
|
||||
cmd.Flags().StringVar(&opts.FromURL, "from-url", "", "Ingest a remote `URL` (HTTP/HTTPS) instead of a local file")
|
||||
// Tri-state flag: unset ⇒ server default, "true"/"false" override. The
|
||||
// raw string is decoded into opts.EnableMultimodel in RunE.
|
||||
cmd.Flags().String("enable-multimodel", "", "Toggle multimodal extraction (true|false); unset ⇒ server default")
|
||||
cmd.Flags().Lookup("enable-multimodel").NoOptDefVal = "true"
|
||||
cmd.Flags().StringSliceVar(&opts.Metadata, "metadata", nil, "Attach metadata `key=value` (repeatable; empty value allowed, last-wins on duplicate keys)")
|
||||
cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")")
|
||||
cmd.Flags().StringVar(&opts.Title, "title", "", "Display title for the new entry (--from-url only)")
|
||||
cmd.Flags().StringVar(&opts.FileType, "file-type", "", "File-type hint such as \"pdf\" when the URL has no extension (--from-url only)")
|
||||
cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Tag id to associate with the new entry (--from-url only)")
|
||||
cmdutil.AddFormatFlag(cmd, docUploadFields...)
|
||||
return cmd
|
||||
}
|
||||
@@ -217,105 +191,21 @@ func parseMetadataKV(raw []string) (map[string]string, error) {
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// effectiveChannel returns the channel string to send to the SDK. Empty
|
||||
// opts.Channel falls back to the default "api" so the wire payload is
|
||||
// identical to the pre-flag behavior.
|
||||
func effectiveChannel(opts *UploadOptions) string {
|
||||
if opts.Channel != "" {
|
||||
return opts.Channel
|
||||
}
|
||||
return uploadChannel
|
||||
}
|
||||
|
||||
// validateUploadFlags enforces mutual exclusion between the three input
|
||||
// modes (positional file path / --recursive directory walk / --from-url
|
||||
// remote ingest) and validates the URL when --from-url is set. It also
|
||||
// rejects the URL-mode-only flags (--title, --file-type, --tag-id) when
|
||||
// --from-url isn't set so misuse fails fast with a typed code.
|
||||
// validateUploadFlags enforces mutual exclusion between the two input modes
|
||||
// (positional file path / --recursive directory walk) and requires that at
|
||||
// least one input mode is supplied.
|
||||
func validateUploadFlags(opts *UploadOptions, args []string) error {
|
||||
hasPath := len(args) == 1
|
||||
hasURL := opts.FromURL != ""
|
||||
if hasURL {
|
||||
if hasPath {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"cannot pass a file path with --from-url; choose one input mode")
|
||||
}
|
||||
if opts.Recursive {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--recursive cannot be combined with --from-url")
|
||||
}
|
||||
// The server's URL-ingest request type has no Metadata field; a
|
||||
// --metadata pair would be silently dropped on the wire. Reject
|
||||
// up-front so callers don't think they've set metadata when they
|
||||
// haven't.
|
||||
if len(opts.Metadata) > 0 {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--metadata is not supported with --from-url (server URL-ingest has no metadata field)")
|
||||
}
|
||||
return cmdutil.ValidateHTTPURL("--from-url", opts.FromURL)
|
||||
}
|
||||
if !hasPath {
|
||||
// Wrap as FlagError so the exit code (2) matches what cobra's own
|
||||
// MinimumNArgs(1) would emit — consistent with every other command
|
||||
// that requires a positional argument.
|
||||
return cmdutil.NewFlagError(errors.New(
|
||||
"a file path is required (or pass --from-url)"))
|
||||
}
|
||||
return rejectURLOnlyFlags(opts)
|
||||
}
|
||||
|
||||
// rejectURLOnlyFlags errors on --title / --file-type / --tag-id when
|
||||
// --from-url is NOT set. Shared between validateUploadFlags (file mode)
|
||||
// and runUploadRecursive (directory walk) so a future URL-mode-only flag
|
||||
// only needs to add one entry here instead of two parallel checks.
|
||||
func rejectURLOnlyFlags(opts *UploadOptions) error {
|
||||
if opts.Title != "" {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--title is only valid with --from-url")
|
||||
}
|
||||
if opts.FileType != "" {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--file-type is only valid with --from-url")
|
||||
}
|
||||
if opts.TagID != "" {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--tag-id is only valid with --from-url")
|
||||
"a file path is required (or use `weknora doc fetch` for URLs, `weknora doc create` for inline text)"))
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// runUploadFromURL ingests a remote URL via SDK CreateKnowledgeFromURL.
|
||||
// `--name` becomes the FileName hint so the server's "known file extension"
|
||||
// detection upgrades crawl-mode to file-download-mode when appropriate.
|
||||
// Server-side knobs (--enable-multimodel, --metadata via Title/TagID/FileType)
|
||||
// propagate when set; the SDK request struct omits empty fields via
|
||||
// `json:",omitempty"` tags so wire payload stays minimal.
|
||||
func runUploadFromURL(ctx context.Context, opts *UploadOptions, fopts *cmdutil.FormatOptions, svc UploadService, kbID string) error {
|
||||
req := sdk.CreateKnowledgeFromURLRequest{
|
||||
URL: opts.FromURL,
|
||||
FileName: opts.Name,
|
||||
FileType: opts.FileType,
|
||||
EnableMultimodel: opts.EnableMultimodel,
|
||||
Title: opts.Title,
|
||||
TagID: opts.TagID,
|
||||
Channel: effectiveChannel(opts),
|
||||
}
|
||||
k, err := svc.CreateKnowledgeFromURL(ctx, kbID, req)
|
||||
if err != nil {
|
||||
if errors.Is(err, sdk.ErrDuplicateURL) {
|
||||
// Server returns 409 with the existing knowledge entry's data.
|
||||
// Surface as resource.already_exists; the data payload (if any)
|
||||
// is observable via err's wrap chain - but the typed code is
|
||||
// what agents branch on.
|
||||
return cmdutil.Wrapf(cmdutil.CodeResourceAlreadyExists, err,
|
||||
"URL already ingested into this knowledge base")
|
||||
}
|
||||
return cmdutil.WrapHTTP(err, "ingest URL %s", opts.FromURL)
|
||||
}
|
||||
|
||||
return renderUploadSuccess(k, fopts, "Ingested", opts.Name, opts.FromURL)
|
||||
}
|
||||
|
||||
// renderUploadSuccess emits the post-upload result. JSON path is the bare
|
||||
// Knowledge object; human path prints a checkmark line. Shared by single-
|
||||
// file upload and URL ingest; humanVerb varies (uploaded/ingested) and
|
||||
@@ -323,7 +213,7 @@ func runUploadFromURL(ctx context.Context, opts *UploadOptions, fopts *cmdutil.F
|
||||
// blank (URL ingest pre-redirect).
|
||||
func renderUploadSuccess(k *sdk.Knowledge, fopts *cmdutil.FormatOptions, humanVerb, customName, fallbackDisplay string) error {
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, k)
|
||||
return fopts.Emit(iostreams.IO.Out, k, nil)
|
||||
}
|
||||
displayed := customName
|
||||
if displayed == "" {
|
||||
@@ -362,7 +252,7 @@ func runUpload(ctx context.Context, opts *UploadOptions, fopts *cmdutil.FormatOp
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
k, err := svc.CreateKnowledgeFromFile(ctx, kbID, path, meta, opts.EnableMultimodel, opts.Name, effectiveChannel(opts))
|
||||
k, err := svc.CreateKnowledgeFromFile(ctx, kbID, path, meta, opts.EnableMultimodel, opts.Name, cmp.Or(opts.Channel, uploadChannel))
|
||||
if err != nil {
|
||||
if errors.Is(err, sdk.ErrDuplicateFile) {
|
||||
// SDK returns sentinel without an "HTTP error <status>:" prefix
|
||||
|
||||
Reference in New Issue
Block a user