2026-05-10 18:43:55 +00:00
// Package initcmd implements `weknora init` — creates a per-project link file
// at <cwd>/.weknora/project.yaml that anchors the working tree to a context
// + knowledge-base id (spec §2.4 "weknora init").
//
// Package name is `initcmd` (not `init`) to avoid colliding with Go's reserved
// init() function naming. The cobra Use: string is "init" — what users type.
package initcmd
import (
"context"
"fmt"
"os"
"path/filepath"
"time"
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/projectlink"
)
// Options captures `weknora init` flags.
type Options struct {
Context string // --context: override active context for this link
KBID string // --kb-id
KBName string // --kb
Yes bool // --yes: skip interactive prompt
Force bool // --force: overwrite existing link
JSONOut bool // --json
}
// initResult is the typed payload emitted under data.
type initResult struct {
Context string ` json:"context" `
KBID string ` json:"kb_id" `
KBName string ` json:"kb_name,omitempty" `
ProjectLinkPath string ` json:"project_link_path" `
}
// NewCmd builds the `weknora init` command.
func NewCmd ( f * cmdutil . Factory ) * cobra . Command {
opts := & Options { }
cmd := & cobra . Command {
Use : "init" ,
Short : "Link the current directory to a context + knowledge base" ,
Long : ` Writes a . weknora / project . yaml in the current working directory that pins
the active context and a knowledge - base id . Subsequent commands run from this
directory ( or any subdirectory ) automatically resolve -- kb - id from the link
unless overridden by the -- kb - id / -- kb flags or WEKNORA_KB_ID env var .
Mirrors the npm init / cargo init / git init UX pattern : one - time setup that
feat(cli): add agent-first affordance — envelope, exit-10, --dry-run
Borrows the lark-cli agent-affordance model
(https://github.com/larksuite/cli/blob/main/AGENTS.md +
skills/lark-shared/SKILL.md) so weknora is designed to be agent-friendly:
error messages, output format, and flag design follow conventions agents
can rely on.
cli/AGENTS.md (operational reference for LLM agents invoking weknora):
Public document covering envelope schema, exit-code protocol
(0/1/2/10/130), stdout/stderr separation, and behavioral rules.
Sensitive commands (\`context use\`, \`kb delete\`, \`doc delete\`, \`init\`)
gain "AI agents:" paragraphs in their cobra Long descriptions so
guidance shows in --help.
format.Envelope schema additions:
Risk per-operation classification (read / write / high-risk-write +
action description), populated by write commands on both success
and failure paths.
Notice system advisories (CLI update available, server-CLI version
skew); type defined, emit sites land in v0.3.
DryRun marker for envelopes returned from --dry-run preview paths.
RiskLevel constants realigned to lark's taxonomy: read / write /
high-risk-write (was: read / mutating / destructive — not yet wired by
any command).
cmdutil.Error gains OperationRisk; PrintErrorEnvelope auto-attaches it
to envelope.Risk so destructive failure paths surface uniformly.
Exit-10 confirmation protocol:
New ErrorCode \`input.confirmation_required\` mapped to exit code 10 in
cmdutil.ExitCode. ConfirmDestructive now returns this code (with
OperationRisk attached) when stdout is non-TTY or --json was set, with
-y/--yes absent. Previous behavior — silent proceed in non-TTY — was
unsafe: scripts and agents could delete resources with no explicit
approval. Three test cases re-pinned around the new contract.
This is a wire-contract change for any caller who relied on silent
proceed; v0.0/v0.1 had no destructive commands, so the blast radius is
contained to v0.2 itself.
--dry-run global flag:
cmd write paths (kb create/delete, doc upload/delete, api POST/PUT/PATCH/
DELETE) check cmdutil.IsDryRun(cmd) and skip the SDK call, emitting an
envelope with dry_run=true plus a Risk classification. Read commands
ignore --dry-run by design (no side effect to preview). Human-mode
prints \`[dry-run] would <action>\` to stdout.
Command discovery: agents introspect via the existing \`--help\` surface
(consistent with gh / kubectl / aws / gcloud / terraform — none of them
ship a CLI-tree self-description command). An earlier draft added a
\`weknora schema\` reflection command; dropped after a mainstream survey
found it has no stable analog (lark-cli's schema describes Lark API
methods, not its own CLI tree).
Tests: 27 cli packages pass at this commit. Added two new tests covering
envelope.risk and envelope._notice serialization.
2026-05-10 18:44:34 +00:00
removes the need to re - pass -- kb - id on every command .
AI agents : ` + " ` init ` " + ` writes to the user ' s working directory . Only run
it when the user explicitly asked to link this directory — don ' t run it as a
side effect of unrelated automation . ` ,
2026-05-10 18:43:55 +00:00
Example : ` weknora init -- kb - id kb_abc # explicit id
weknora init -- kb engineering -- yes # name → id , no prompt
weknora init # interactive ( TTY )
weknora init -- force -- kb - id kb_xyz # overwrite existing link ` ,
Args : cobra . NoArgs ,
RunE : func ( c * cobra . Command , _ [ ] string ) error {
return runInit ( c . Context ( ) , opts , f )
} ,
}
cmd . Flags ( ) . StringVar ( & opts . Context , "context" , "" , "Context to record in the link (defaults to active context)" )
cmd . Flags ( ) . StringVar ( & opts . KBID , "kb-id" , "" , "Knowledge base id to link" )
cmd . Flags ( ) . StringVar ( & opts . KBName , "kb" , "" , "Knowledge base name (resolved to id)" )
cmd . Flags ( ) . BoolVar ( & opts . Yes , "yes" , false , "Skip interactive prompt" )
cmd . Flags ( ) . BoolVar ( & opts . Force , "force" , false , "Overwrite an existing .weknora/project.yaml" )
cmd . Flags ( ) . BoolVar ( & opts . JSONOut , "json" , false , "Output JSON envelope" )
cmd . MarkFlagsMutuallyExclusive ( "kb-id" , "kb" )
agent . SetAgentHelp ( cmd , "Creates .weknora/project.yaml linking cwd to a context + KB. Pass --kb-id (or --kb name) and --yes for non-interactive use; --force overwrites an existing link." )
return cmd
}
func runInit ( ctx context . Context , opts * Options , f * cmdutil . Factory ) error {
cwd , err := os . Getwd ( )
if err != nil {
return cmdutil . Wrapf ( cmdutil . CodeLocalFileIO , err , "get cwd" )
}
linkPath := filepath . Join ( cwd , projectlink . DirName , projectlink . FileName )
// Pre-flight: refuse to clobber unless --force.
if _ , statErr := os . Stat ( linkPath ) ; statErr == nil && ! opts . Force {
return cmdutil . NewError ( cmdutil . CodeProjectAlreadyLinked , fmt . Sprintf ( "project already linked: %s" , linkPath ) )
}
// Resolve context: --context flag wins, else config.CurrentContext.
ctxName , err := resolveContext ( opts , f )
if err != nil {
return err
}
// Resolve KB: --kb-id > --kb > interactive prompt.
kbID , kbName , err := resolveKB ( ctx , opts , f )
if err != nil {
return err
}
link := & projectlink . Project {
Context : ctxName ,
KBID : kbID ,
CreatedAt : time . Now ( ) . UTC ( ) ,
}
if err := projectlink . Save ( linkPath , link ) ; err != nil {
return cmdutil . Wrapf ( cmdutil . CodeLocalFileIO , err , "write project link" )
}
r := initResult {
Context : ctxName ,
KBID : kbID ,
KBName : kbName ,
ProjectLinkPath : linkPath ,
}
if opts . JSONOut {
return format . WriteEnvelope ( iostreams . IO . Out , format . Success ( r , & format . Meta {
Context : ctxName ,
KBID : kbID ,
} ) )
}
if kbName != "" {
fmt . Fprintf ( iostreams . IO . Out , "✓ Linked %s to %s (kb=%s, id=%s)\n" , linkPath , ctxName , kbName , kbID )
} else {
fmt . Fprintf ( iostreams . IO . Out , "✓ Linked %s to %s (kb_id=%s)\n" , linkPath , ctxName , kbID )
}
return nil
}
// resolveContext returns the context name to record in the link.
func resolveContext ( opts * Options , f * cmdutil . Factory ) ( string , error ) {
if opts . Context != "" {
return opts . Context , nil
}
cfg , err := f . Config ( )
if err != nil {
return "" , err
}
if cfg . CurrentContext == "" {
return "" , cmdutil . NewError ( cmdutil . CodeAuthUnauthenticated , "no active context; run `weknora auth login` first" )
}
return cfg . CurrentContext , nil
}
// resolveKB applies the --kb-id / --kb / prompt fallback chain. Returns
// (kbID, kbName) where kbName is empty when only --kb-id was supplied.
func resolveKB ( ctx context . Context , opts * Options , f * cmdutil . Factory ) ( string , string , error ) {
if opts . KBID != "" {
return opts . KBID , "" , nil
}
if opts . KBName != "" {
cli , err := f . Client ( )
if err != nil {
return "" , "" , err
}
id , err := cmdutil . ResolveKBNameToID ( ctx , cli , opts . KBName )
if err != nil {
return "" , "" , err
}
return id , opts . KBName , nil
}
// No flag: try interactive prompt when allowed.
if opts . Yes || ! iostreams . IO . IsStdoutTTY ( ) {
return "" , "" , cmdutil . NewError ( cmdutil . CodeKBIDRequired , "--kb-id or --kb is required (no TTY / --yes set)" )
}
cli , err := f . Client ( )
if err != nil {
return "" , "" , err
}
return promptForKB ( ctx , cli , f )
}
// promptForKB lists available knowledge bases on stderr, then asks the user
// for an id or name (huh-backed Input via TTYPrompter). Resolved against the
// listed set so a typed name is converted to the canonical id.
func promptForKB ( ctx context . Context , svc cmdutil . KBLister , f * cmdutil . Factory ) ( string , string , error ) {
kbs , err := svc . ListKnowledgeBases ( ctx )
if err != nil {
return "" , "" , cmdutil . Wrapf ( cmdutil . ClassifyHTTPError ( err ) , err , "list knowledge bases" )
}
if len ( kbs ) == 0 {
return "" , "" , cmdutil . NewError ( cmdutil . CodeKBNotFound , "no knowledge bases visible to active context; create one first" )
}
fmt . Fprintln ( iostreams . IO . Err , "Available knowledge bases:" )
for _ , kb := range kbs {
fmt . Fprintf ( iostreams . IO . Err , " %s %s\n" , kb . ID , kb . Name )
}
p := f . Prompter ( )
answer , err := p . Input ( "Knowledge base id or name" , "" )
if err != nil {
return "" , "" , cmdutil . Wrapf ( cmdutil . CodeInputMissingFlag , err , "kb prompt" )
}
for _ , kb := range kbs {
if kb . ID == answer || kb . Name == answer {
return kb . ID , kb . Name , nil
}
}
return "" , "" , cmdutil . NewError ( cmdutil . CodeKBNotFound , fmt . Sprintf ( "knowledge base not found: %s" , answer ) )
}