feat(cli): add project-link foundation with init and link commands

v0.2 grounds the CLI's resource commands (kb / doc / chat / query) in a
per-project link file (.weknora/project.yaml) so users don't have to pass
--kb-id on every invocation. Mirrors npm/cargo/git: walk up the cwd tree
to find the project root, override via flag or env when needed.

This commit ships the foundation layer:

  - cli/internal/projectlink/  Discover (walk-up, depth=64) / Load / Save
  - cmdutil.Factory.ResolveKB  5-level fallback chain:
      --kb-id flag → --kb name (ListKnowledgeBases lookup) →
      WEKNORA_KB_ID env → walk-up project link → CodeKBIDRequired
  - cmdutil.ResolveKBNameToID   shared name→id helper used by init / link
                                / Factory.ResolveKB (was duplicated 3 ways
                                in early implementation; reuse review #2)
  - cli/cmd/init/               interactive (huh prompt) or flag-driven
                                first-time setup; refuses to overwrite
                                without --force
  - cli/cmd/link/               non-interactive update; --kb-id and --kb
                                are mutually exclusive and one is required

Also registers the v0.2 ErrorCode set (all codes for the eight new
commands) and AST-scan identToErrorCode mapping in one place — keeps the
acceptance/contract suite green across the v0.2 commit chain even before
later commits reference each code.
This commit is contained in:
nullkey
2026-05-11 02:43:55 +08:00
committed by lyingbug
parent fc694d5d21
commit 19afd5eed9
13 changed files with 1141 additions and 17 deletions
+85
View File
@@ -0,0 +1,85 @@
// Package projectlink reads and writes the per-project link file
// .weknora/project.yaml that anchors a working directory to a context+KB.
//
// Discovery walks up from the start directory until either (a) a
// .weknora/project.yaml is found, (b) the filesystem root is reached, or
// (c) the walk exceeds a 64-level depth limit (cycle protection for
// pathological symlink setups). Pattern matches `cargo`, `npm`, and `git`
// — find-the-project's-root walks; mount-boundary crossing is allowed
// (npm/cargo behave the same — a project may straddle a bind-mount).
package projectlink
import (
"errors"
"fmt"
"os"
"path/filepath"
"time"
"github.com/Tencent/WeKnora/cli/internal/xdg"
"gopkg.in/yaml.v3"
)
// Project is the on-disk schema of .weknora/project.yaml.
type Project struct {
Context string `yaml:"context,omitempty"`
KBID string `yaml:"kb_id"`
CreatedAt time.Time `yaml:"created_at"`
}
// FileName is the project link file basename relative to .weknora/.
const FileName = "project.yaml"
// DirName is the project-link directory name.
const DirName = ".weknora"
const maxWalkDepth = 64
// Discover walks up from startDir looking for <DirName>/<FileName>.
// Returns (path, true, nil) when found, (root, false, nil) when none is
// found within depth limit, or ("", false, err) on filesystem errors.
func Discover(startDir string) (string, bool, error) {
dir, err := filepath.Abs(startDir)
if err != nil {
return "", false, fmt.Errorf("resolve start dir: %w", err)
}
for range maxWalkDepth {
candidate := filepath.Join(dir, DirName, FileName)
info, err := os.Stat(candidate)
if err == nil && !info.IsDir() {
return candidate, true, nil
}
if err != nil && !errors.Is(err, os.ErrNotExist) {
// Permission errors etc. — keep walking up; missing read access
// to a parent dir doesn't necessarily mean the project starts
// here. Cargo/npm have the same behavior.
// Fall through to parent walk.
}
parent := filepath.Dir(dir)
if parent == dir {
// Hit filesystem root
return "", false, nil
}
dir = parent
}
return "", false, nil
}
// Load reads and parses the project link file at path.
func Load(path string) (*Project, error) {
data, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("read project link: %w", err)
}
var p Project
if err := yaml.Unmarshal(data, &p); err != nil {
return nil, fmt.Errorf("project link corrupt: %w", err)
}
return &p, nil
}
// Save writes the project link to path atomically (0600 perms).
// Creates parent .weknora/ directory if missing.
func Save(path string, p *Project) error {
return xdg.WriteAtomicYAML(path, p)
}
@@ -0,0 +1,112 @@
package projectlink_test
import (
"os"
"path/filepath"
"testing"
"time"
"github.com/Tencent/WeKnora/cli/internal/projectlink"
)
func TestDiscover_FoundInCwd(t *testing.T) {
dir := t.TempDir()
mkLink(t, dir)
got, found, err := projectlink.Discover(dir)
if err != nil {
t.Fatalf("Discover: %v", err)
}
if !found {
t.Fatalf("expected found=true")
}
want := filepath.Join(dir, ".weknora", "project.yaml")
if got != want {
t.Errorf("got %q, want %q", got, want)
}
}
func TestDiscover_FoundInParent(t *testing.T) {
root := t.TempDir()
mkLink(t, root)
deep := filepath.Join(root, "a", "b", "c")
if err := os.MkdirAll(deep, 0o755); err != nil {
t.Fatal(err)
}
got, found, err := projectlink.Discover(deep)
if err != nil {
t.Fatalf("Discover: %v", err)
}
if !found {
t.Fatal("expected found=true")
}
if filepath.Dir(filepath.Dir(got)) != root {
t.Errorf("expected discovered file under %q, got %q", root, got)
}
}
func TestDiscover_NotFound(t *testing.T) {
dir := t.TempDir()
_, found, err := projectlink.Discover(dir)
if err != nil {
t.Fatalf("Discover: %v", err)
}
if found {
t.Fatal("expected found=false in empty tree")
}
}
func TestLoad_RoundTrip(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, ".weknora", "project.yaml")
in := &projectlink.Project{Context: "prod", KBID: "kb_abc", CreatedAt: time.Now().UTC().Round(time.Second)}
if err := projectlink.Save(path, in); err != nil {
t.Fatalf("Save: %v", err)
}
out, err := projectlink.Load(path)
if err != nil {
t.Fatalf("Load: %v", err)
}
if out.Context != in.Context || out.KBID != in.KBID {
t.Errorf("round trip: got %+v want %+v", out, in)
}
}
func TestLoad_Corrupt(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, ".weknora", "project.yaml")
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte("not: yaml: : :"), 0o600); err != nil {
t.Fatal(err)
}
_, err := projectlink.Load(path)
if err == nil {
t.Fatal("expected error for corrupt yaml")
}
}
func TestSave_CreatesParent(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, ".weknora", "project.yaml")
if err := projectlink.Save(path, &projectlink.Project{KBID: "kb_x"}); err != nil {
t.Fatalf("Save: %v", err)
}
if _, err := os.Stat(filepath.Join(dir, ".weknora")); err != nil {
t.Errorf("parent .weknora not created: %v", err)
}
if _, err := os.Stat(path); err != nil {
t.Errorf("file not created: %v", err)
}
}
func mkLink(t *testing.T, dir string) {
t.Helper()
d := filepath.Join(dir, ".weknora")
if err := os.MkdirAll(d, 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(d, "project.yaml"), []byte("kb_id: kb_test\n"), 0o600); err != nil {
t.Fatal(err)
}
}