Documentation
¶
Overview ¶
Package commands — `browzer org docs add`.
Uploads documents to org-scope (workspaceId=null). Unlike `workspace docs`, this command does NOT require a git root, a .browzer/config.json, or a local cache. Each invocation is stateless — pass explicit file paths and they are uploaded as org-scoped documents that are not bound to any workspace.
Package commands — `browzer plugin` group.
Prints install / uninstall instructions for the Browzer Claude Code plugin. Claude Code only loads plugins via two official paths — `/plugin marketplace add` + `/plugin install` inside the IDE, or the `claude --plugin-dir <path>` flag for local dev. There is no supported filesystem-drop install, so this command is a printer, not a copier.
Package commands — preflight helper used by `init` and `sync`.
Both commands walk the docs tree before uploading. Phase 7 adds a server-authoritative chunk-budget check in front of the upload so users hit "your plan is full" with an actionable message BEFORE a workspace is half-indexed.
The helper is intentionally shared — both call sites pass the same []walker.DocFile slice and want the same failure surface.
Package commands wires every cobra command into the root tree.
Each command lives in its own file (login.go, init.go, sync.go, ...) mirroring the legacy src/commands/*.ts layout. NewRootCommand is the single entrypoint called from cmd/browzer/main.go.
Package commands — `browzer workspace docs`.
Interactive document re-indexer. The legacy `sync` command walked the filesystem and blindly applied a cache-based delta, which made it impossible for users to opt specific docs in or out. `workspace docs` replaces that with an interactive `huh` multi-select that:
- Fetches server-side indexed docs, local candidate docs, and live billing quotas concurrently.
- Merges them into a single list where already-indexed items are pre-checked and new items are shown but unchecked by default.
- Lets the user toggle items. On submit we compute a delta (insert / re-upload / delete / keep), call preflight on the insert set, then execute.
Quota enforcement: huh's `Validate` hook on MultiSelect runs only on Next/Prev/Submit (see field_multiselect.go:449/456), NOT per-toggle. We rely on submit-time validation + server preflight — no attempt to reject individual toggles mid-flight.
Package commands — spec parsing for non-interactive `workspace docs`.
This file is PURE: no I/O apart from reading an `@file` reference, no globals, no cobra dependency. All entry points are unit-testable without a TUI, network, or authenticated client. The rest of the non-interactive mode (flag wiring, mutual-exclusion checks, delta application, safeguards) lives in workspace_docs.go and composes these primitives.
Vocabulary:
- "spec" — the raw string the user passed after --add/--remove/ --replace. Can be a sentinel (new/all/none), an @file reference, a stdlib glob, or a comma-separated list.
- "scope" — which sentinels are legal for the flag being parsed. --add allows `new`; --replace allows `all`/`none`; --remove allows none.
- "resolver" — a closure that takes the merged picker items and returns the set of paths matched. Resolution is deferred until after the merge so globs can see the full candidate list.
Package commands — `browzer workspace index`.
Thin alias for `browzer sync --skip-docs`. Delegates to runSyncFlow with SkipDocs=true and JSONMode="index" (backward-compat wire shape).
Retained behaviors:
- cold-start 600s auth timeout (via runSyncFlow → requireAuth(600)).
- --dry-run / --json / --save plumbing forwarded into syncFlowOptions.
- Stamps ProjectConfig.LastSyncCommit on success (inside runSyncFlow).
- JSON payload shape preserved: {mode:"index", workspaceId, codeFiles}.
Package commands — "browzer workspace sync" (and the "browzer sync" top-level alias).
Reconciles the server's indexed set with the local filesystem: re-uploads changed docs, deletes docs that were removed locally, adds new local docs that pass the stacked ignore filter (.gitignore ∩ .browzerignore), and keeps unchanged docs.
Order is strictly: code index FIRST, then docs. Package nodes must exist in the graph before linkEntitiesToWorkspace runs during entity extraction — reversing the order means RELEVANT_TO edges are never created for documents indexed in the same sync run.
Index ¶
- Variables
- func DaemonVersion() string
- func NewRootCommand(version string) *cobra.Command
- func ReconcileWorkspaceManifest(ctx context.Context, client WorkspaceSyncClient, ...) error
- func SetDaemonVersion(v string)
- type ApplyResult
- type DocDeltaPlan
- type DocPickerItem
- type SpecMode
- type SpecResolver
- type SpecScope
- type WorkspaceSyncClient
- type WorkspaceSyncManifest
Constants ¶
This section is empty.
Variables ¶
var ErrJobNotFound = errors.New("job not found")
ErrJobNotFound is a placeholder sentinel — wired so future api-level errors can be classified without string-matching.
var Ultra bool
Ultra is the package-level flag for --ultra (compact output across read/explore/search/deps). Set by NewRootCommand's PersistentPreRunE.
Functions ¶
func DaemonVersion ¶ added in v0.8.0
func DaemonVersion() string
DaemonVersion returns the current version string.
func NewRootCommand ¶
NewRootCommand returns the configured cobra root command. version is injected from main via -ldflags so the published binary reports its own release.
func ReconcileWorkspaceManifest ¶ added in v1.3.3
func ReconcileWorkspaceManifest( ctx context.Context, client WorkspaceSyncClient, manifest WorkspaceSyncManifest, serverList []api.WorkspaceDto, ) error
ReconcileWorkspaceManifest applies bidirectional last-writer-wins reconciliation between the local WorkspaceManifest and the server-fetched workspace list (AC-5-cli).
Pull direction (server → local):
- Server entry exists, local manifest entry has a different Name/RootPath → update local manifest with server's values (server wins per record).
- Manifest entry exists but server list has no matching entry → remove from local manifest (server delete wins).
Push direction (local → server):
- Local entries with LocallyModified=true and PendingDelete=true → call client.DeleteWorkspace(ctx, id) then remove from manifest.
- Local entries with LocallyModified=true (rename, not delete) → call client.UpdateWorkspace(ctx, id, name, rootPath) then clear the flag.
Returns the modified manifest. The caller is responsible for saving it.
func SetDaemonVersion ¶ added in v0.8.0
func SetDaemonVersion(v string)
SetDaemonVersion is called from cmd/browzer/main.go at startup.
Types ¶
type ApplyResult ¶ added in v0.4.0
type ApplyResult struct {
// UnresolvedAdd are paths in --add's spec that had no matching item
// — caller MUST error.
UnresolvedAdd []string
// UnresolvedRemove are paths in --remove's spec that had no
// matching indexed item — caller SHOULD warn and continue.
UnresolvedRemove []string
// UnresolvedReplace are paths in --replace's spec that had no
// matching item — caller MUST error.
UnresolvedReplace []string
}
applySpecsToItems mutates items[i].Selected according to the supplied specs. It is deliberately split out from the cobra RunE so that tests can assert the selection logic without any flag parsing or I/O.
Rules (see top-of-file spec):
- In REPLACE mode, base selection is cleared; replaceSpec defines the final selected set. addSpec/removeSpec must be nil.
- In ADD/REMOVE mode, base selection = Indexed (current server state). addSpec unions items in; removeSpec removes them.
Returns the combined list of unresolved paths, partitioned by which spec they came from so the caller can error (add) or warn (remove).
type DocDeltaPlan ¶ added in v0.4.0
type DocDeltaPlan struct {
// ToInsert are locally-present items the user selected that the
// server does not yet know about.
ToInsert []DocPickerItem
// ToReUpload are selected items the server already has but whose
// local hash differs from the cached hash (best approximation of
// "content changed since last sync" — the server never returns a
// hash).
ToReUpload []DocPickerItem
// ToDelete are items the server has but the user deselected (either
// because the file was deleted locally, or because they explicitly
// unchecked it).
ToDelete []DocPickerItem
// ToKeep are selected items that are unchanged vs the cache — no-op.
ToKeep []DocPickerItem
}
DocDeltaPlan is the outcome of applying a user selection to the merged list. It partitions every item into exactly one bucket; the four slices together always cover the full input.
type DocPickerItem ¶ added in v0.4.0
type DocPickerItem struct {
RelativePath string
LocalHash string
LocalSize int64
LocalAbs string
ServerDocumentID string
ServerChunkCount int64
ServerSizeBytes int64
ServerStatus string
Indexed bool // server has this path
Selected bool // user intent after the picker (default = Indexed)
}
DocPickerItem is one row in the interactive picker. It is the merged view of "what lives on the filesystem" and "what lives on the server", so a single item can represent any combination.
Fields prefixed "Local" come from walker.WalkDocs, "Server" come from client.ListWorkspaceDocuments. A fully orphaned server entry (file deleted locally but still indexed) has empty Local* fields; a new file has empty Server* fields.
func (DocPickerItem) HasLocal ¶ added in v0.4.0
func (i DocPickerItem) HasLocal() bool
HasLocal reports whether the item exists on the filesystem right now.
type SpecMode ¶ added in v0.4.0
type SpecMode int
SpecMode identifies which flag produced a resolver — used by applySpecsToItems to pick the right base state.
type SpecResolver ¶ added in v0.4.0
type SpecResolver struct {
// Resolve returns matched: set of item.RelativePath that matched
// this spec, and unresolved: literal paths the user typed that
// could not be located in items (empty for sentinel/glob specs).
Resolve func(items []DocPickerItem) (matched map[string]bool, unresolved []string)
// Raw is the original spec string, retained for error messages.
Raw string
// Sentinel, when non-empty, names the sentinel form this spec used
// (`new`, `all`, `none`). Useful for downstream logic that needs to
// distinguish "explicit empty" (`none`) from "empty match".
Sentinel string
}
SpecResolver is the deferred matcher produced by parseSpec. It receives the merged item list AT APPLY TIME (so globs can resolve against the real candidate set) and returns the set of matching relative paths plus any paths the spec referenced but that do not exist in the item list.
The `unresolved` slice is what --add uses to hard-error ("path in spec but not in candidate set") and what --remove downgrades to a stderr warning.
type SpecScope ¶ added in v0.4.0
type SpecScope int
SpecScope enumerates the sentinels permitted for a given spec site. Using a typed enum (vs three booleans) keeps the parser call sites self-documenting and prevents "allow `new` on remove" type mistakes.
const ( // SpecScopeAdd permits the `new` sentinel (all not-yet-indexed local // files). Used by --add. SpecScopeAdd SpecScope = iota // SpecScopeRemove permits NO sentinels. Used by --remove. SpecScopeRemove // SpecScopeReplace permits `all` (every local file) and `none` // (empty set). Used by --replace. SpecScopeReplace )
type WorkspaceSyncClient ¶ added in v1.3.3
type WorkspaceSyncClient interface {
UpdateWorkspace(ctx context.Context, workspaceID, name, rootPath string) error
DeleteWorkspace(ctx context.Context, workspaceID string) error
}
WorkspaceSyncClient is the subset of api.Client used by ReconcileWorkspaceManifest. Defined as an interface so tests can inject a mock HTTP server.
type WorkspaceSyncManifest ¶ added in v1.3.3
type WorkspaceSyncManifest interface {
Get(id string) (cache.ManifestEntry, bool)
Upsert(entry cache.ManifestEntry)
Remove(id string)
All() []cache.ManifestEntry
}
WorkspaceSyncManifest is the subset of cache.WorkspaceManifest used by ReconcileWorkspaceManifest. Defined as an interface so tests can inject a controlled in-memory manifest without hitting the filesystem.
Source Files
¶
- ask.go
- common.go
- config_cmd.go
- daemon_cmd.go
- daemon_detach_unix.go
- deps.go
- explore.go
- gain.go
- ingest.go
- init.go
- job.go
- login.go
- logout.go
- mentions.go
- org_docs_add.go
- org_docs_list.go
- org_docs_show.go
- org_members_list.go
- org_show.go
- plan_status.go
- plugin.go
- preflight.go
- read.go
- root.go
- search.go
- status.go
- upgrade.go
- workflow.go
- workflow_append_dispatch.go
- workflow_append_dispatches.go
- workflow_append_review_history.go
- workflow_append_step.go
- workflow_append_steps.go
- workflow_audit_model_override.go
- workflow_complete_step.go
- workflow_describe_step_type.go
- workflow_get_config.go
- workflow_get_step.go
- workflow_init.go
- workflow_mutator_helpers.go
- workflow_patch.go
- workflow_query.go
- workflow_reapply_additional_context.go
- workflow_save.go
- workflow_schema.go
- workflow_set_config.go
- workflow_set_current_step.go
- workflow_set_finding_statuses.go
- workflow_set_status.go
- workflow_truncation_audit.go
- workflow_update_step.go
- workflow_validate.go
- workspace.go
- workspace_docs.go
- workspace_docs_list.go
- workspace_docs_spec.go
- workspace_files_list.go
- workspace_index.go
- workspace_manifest.go
- workspace_relink.go
- workspace_show.go
- workspace_sync.go
- workspace_unlink.go