53 Commits

Author	SHA1	Message	Date
sang-neo03	d12b39cf46	feat(vfs): allow absolute paths under a built-in path policy (#2580) ... * feat(vfs): allow absolute paths under a built-in path allowlist Path flags only accepted paths relative to the working directory, so an agent passing a full path (typically under /tmp) failed on its first call and had to retry with a relative one. Absolute paths are now accepted when they resolve inside a built-in allowlist: the working directory, /tmp, and ~/files. A built-in denylist covers system and credential locations and wins over the allowlist, including over the working directory. Both lists are compiled in and read no environment variable, flag, or config file, so the effective policy is fixed by the binary; upgrading is all it takes for the new behavior to apply. Containment is decided by file identity (device and inode) alongside the resolved name, because a single directory has many spellings: APFS folds U+017F onto "s", so ".sshh" spelled with it opens ~/.ssh, and NTFS and APFS both compare case-insensitively. Reads are hardened where the policy applies: O_NOFOLLOW pins the final component, O_NONBLOCK keeps a FIFO from blocking before it can be refused, and the opened descriptor is matched against the inspected object, rejected when it is not a regular file, and rejected when it carries extra hard links. The relaxed local-input tier used by apps upload keeps its own contract (symlinks are legitimate arguments there) and gains the denylist check instead. Two behaviors are deliberate rather than incidental. Working inside a denylisted directory now refuses even relative paths, since the denylist is unconditional. Running as root leaves only the working directory and /tmp, because the home directory is then /root, itself a deny root. Existing tests asserted the old "every absolute path is refused" baseline; they now assert the allowlist. Traversal fixtures escape to the filesystem root, which stays outside every allowed root on Linux, where the temp directory that hosts t.TempDir() is /tmp itself. * fix(vfs): close two paths around the built-in denylist A "~/..." argument had two readings: validation expanded it to the home directory, while a caller that keeps the original string — SafeLocalFlagPath returns it verbatim — opens whatever "~" names in the working directory. A symlink there carried reads past the denylist, confirmed by reading /etc/passwd through it. Every interpretation of an argument is now checked, so the shorthand still reaches ~/files while the literal entry cannot escape. With no LARKSUITE_CLI_CONFIG_DIR and no reachable home directory, core.GetBaseConfigDir keeps credentials in a bare ".lark-cli" resolved against the working directory, which is an allow root. That fallback is now mirrored as a deny root, so containers whose home lookup fails do not expose their stored tokens. * fix(vfs): enforce hard-link checks across readers * fix(vfs): stop an output hard link from rewriting a file outside the allowlist A hard link has no target for name resolution to follow, so a link inside an allowed root looked like an allowed destination while sharing its inode with a file outside every root. A caller that truncated the approved name in place rewrote that outside file: `auth qrcode --output <link>` reported success and replaced a 43-byte JSON file outside the allowlist with its PNG. Output validation now refuses an existing target that carries more than one name, which covers callers that write directly, and auth qrcode commits through a temp file and a rename, which replaces the directory entry and leaves the other names alone. Writers already going through FileIO.Save were never affected, since that path has always committed by rename. * fix(vfs): give the hard-link refusal a workable recovery hint The message told the caller to copy the file into an allowed directory, which answers a question they did not ask: the file that triggers this is normally already inside one, with every one of its names there too. It now states what the check actually cannot do — enumerate the other names a file is reachable by — and offers the step that works, which is to copy the file and use the copy. * test(vfs): pick the denylist fixture for the platform under test Two tests reached for "/etc/passwd" as a denylisted absolute path. That path is not absolute on Windows, so one test met the foreign-path rejection instead of the denylist it was asserting, and the other saw the path joined to the working directory and no rejection at all. Both now ask for a deny root that exists on the platform running them — the credential directories under the account home qualify everywhere — which keeps the denylist covered on Windows rather than skipping it there. Verified on Windows 10.0.19045 by running the package's test binary from this branch and from main: main passed, this branch failed these two, and both pass after the change. The other packages this branch touches were compared the same way and their Windows results are identical on both sides. * fix(vfs): state the hard-link check as the condition it tests The check read as "bail out unless the target can be inspected", which nilerr reads as an error swallowed on the way out. It now names the case it acts on — an existing regular file with more than one name — and the comment carries what the early return used to imply: a target that cannot be inspected has no link count to judge, and the write layer reports the real failure with proper typing. * docs(vfs): scope the policy's environment claim to what holds The header promised that neither list accepts runtime input and that no caller controlling the environment can widen them. Two inputs contradict that: LARKSUITE_CLI_CONFIG_DIR contributes a deny root, and where the account database cannot name the running uid, $HOME decides where ~/files points — reproduced in a container running as an unregistered uid, which wrote into a directory the environment chose. The comments now state the preference and its boundary rather than a guarantee, and record what the boundary costs: a directory named "files" under the named path, with the home directory itself still outside the allowlist and every candidate home still carrying the credential deny roots. The trustedHome note also said the pure-Go lookup falls back to $HOME silently; it does so only when $USER is set as well, and returns an error otherwise, which drops the ~/files root instead of moving it. No behavior change. * fix(auth): keep the mode of a QR output file that already exists Committing the QR write by rename fixed a hard link from rewriting a file outside the allowlist, but it also changed what happens to the target's mode. A rename installs the temp file's inode, mode included, where the previous in-place write left the existing file's mode untouched. Overwriting a target the caller had restricted to 0600 therefore published it as 0644. The mode now comes from the file already at the path; only a path with nothing at it takes the default. Verified against main, which preserved 0600 here, and covered by a test that fails when the fixed mode is restored. * test(sheets): move the csv file-alias tests onto the new path baseline Merging main brought #2559's tests for the --file → --csv alias, written against the policy this branch replaces. Two of them fail on it, both because the verdict they describe moved rather than disappeared. The out-of-tree case used /tmp, which the allowlist now accepts, so the value came back as a missing file instead of an out-of-tree one; it now names a path no allow root can contain. The directory case is refused when the descriptor is inspected, before a read is attempted, so the message reads "not a regular file". What the caller sees of both — the flag named, the cause kept, stdin offered — is unchanged. That message listed the kinds it refuses and omitted directories, which is how it reached a directory test reading as a mismatch. It now names them. * fix(im): let the path policy judge a download target `+messages-resources-download` refused an absolute --output before the shared policy saw it, so the flag stayed relative-only after the policy learned to accept full paths. It is the command behind 99% of a reported 1,189 download path errors in one week, where 97.2% of first calls passed an absolute path and every later success had switched to a relative one. The shape checks are gone. Both call sites already hand the result to ResolveSavePath, which applies the allowlist, the denylist and symlink resolution, so refusing a shape here decided nothing the policy would not decide better — an absolute path is now answered by where it points rather than by how it is written. The file-key checks stay, and they are what the batch caller relies on: it embeds the key in the path, and a key carrying a separator is refused as a malformed key, so a traversal cannot be built from one. Verified against a real tenant: /tmp and ~/files now save, while ~/.ssh, /etc and a path outside every root are still refused. * test(im): pin the download output contract the policy now decides The dry-run suite listed an absolute path among the values --output must refuse. That held while the command rejected the shape itself; now that the built-in policy decides, /tmp is an allowed root and the path is accepted, so the case asserted a rule that no longer exists. It is replaced by the two halves of the real contract: an absolute path inside an allowed root reaches the request, and a path that resolves outside every root — a parent escape from this working directory, or a denylisted directory — is still turned down as a validation error naming --output. * fix(vfs): hold a relative path to the working directory Accepting /tmp as an allow root gave a relative path somewhere new to go. A process whose working directory sits under /tmp — CI runners, containers and agent sandboxes commonly arrange that — could climb out with "../" and still satisfy the allowlist, because the sibling it landed in was also under /tmp. /tmp is world-writable, so that sibling can belong to another user or another session, and the write side commits by rename, which replaces an existing target unconditionally. The previous policy refused this: it required every resolved path to stay under the working directory. Naming a full path and climbing out of the working directory are different acts and no longer share one verdict. An absolute path is judged by the allowlist, which is what this branch set out to allow; a relative one has to resolve inside the working directory, whatever wider root contains it. The home denylist grows at the same time and for the same reason: the working directory is an allow root and running from the home directory is ordinary, so a credential store there is reachable by a relative name unless the list covers it. It now names the common ones — netrc, git and shell credentials, kube, docker, azure, gh, gcloud, the language package registries — and the shell histories, which carry pasted keys as reliably as a credential file. ---------	2026-09-01 22:18:29 +08:00
dc-bytedance	36c7291cc1	fix(auth): exclude im:message.send_as_user from batch scope sets (#2471) ... * fix(auth): exclude im:message.send_as_user from batch scope sets * test(auth): isolate requested-scope cache in batch-exclusion test * fix(auth): validate --exclude against pre-filter scope universe The batch-exclusion filter dropped im:message.send_as_user before --exclude was validated, so `--domain im --exclude im:message.send_as_user` returned invalid_argument and never sent the device authorization request. That broke automations relying on --exclude to skip the send-as-user approval. Validate --exclude against the selected universe (post recommend/common filter, pre batch exclusion) plus --scope; the wire request still uses the batch-filtered effective scopes. Excluding a batch-withheld scope is now a valid no-op, while excluding a scope outside the selection still errors so typos are not widened. * test(auth): assert exact scope membership in exclude regression test	2026-08-25 21:13:57 +08:00
sang-neo03	6952d3aa7f	feat(extension): add business command extension v1 (#2308) ... * feat(shortcuts): import typed shortcut framework from c07b64621 * feat(extension): add public command contract * feat(extension): compile and register business commands * feat(cmd): assemble business command sets * fix(auth): derive login domains from shortcuts * test(extension): add business command test runtime * ci: verify generated Go sources * test(auth): match help and interactive domains * fix(extension): validate command path segments * fix(extension): satisfy generator and error guards * fix(extension): follow generated domain naming contract * fix(command): complete extension runtime contracts * test(command): cover public extension surface * fix(command): remove unused typed runtime APIs * fix(command): address follow-up review findings * fix(command): enforce extension v1 contracts * fix(command): remove unreachable compatibility wrappers * fix(auth): keep scope-less domains addressable via --domain, matching main Move the declared-scope filter from allKnownDomains to the interactive selector only. On main, a scope-less shortcut domain (event) passes --domain validation and fails later with "no matching scopes found"; the previous unified filter changed that to "unknown domain" and dropped it from the --help list. The interactive picker still hides scope-less domains — selecting one can only fail. * feat(command): add PathSegment for user-provided path values Business code concatenates IDs into request paths but had no public escape helper (internal/validate.EncodePathSegment is unreachable from extension/command). Mirror its url.PathEscape semantics, use it in the business command examples, and pin the traversal defense: the validator decodes percent-encoding before the canonical check, so both raw and escaped dot sequences fail same-origin validation. * docs(command): add runnable chat-brief distribution example Mirror the audit-observer precedent: a buildable wrapper main under examples/ showing WithCommandSets against the real distribution shape (plugins, strict mode, and service commands stay enabled). Covers the single-read command (Validate, shared DryRun request, CallJSON, PathSegment, Tips) and a Page[T] list command whose pagination flags come from the compiler. The testdata/wrapper fixture stays test-only. Verified offline: --help renders tag-driven parameters, +chat-brief-list exposes --page-all/--page-limit/--page-delay, and --dry-run previews the request with a fake env token and no network access. * fix(command): normalize page envelopes and bound CollectAllPages Two pagination contract fixes from the extension design (owner plan §8.3): Page decoding accepted only a literal "items" array, so endpoints that spell their list field differently (drive uses files, some responses use records) walked every page while decoding nothing — CollectAllPages then returned an empty set marked complete, and downstream writes ran against it. Each page now normalizes its single top-level array field into Page.Items; zero or multiple array fields fail closed with a typed invalid-response error. CollectAllPages previously reused the user-facing --page-limit maximum (1000) as its walk bound. A complete-set collection holds every page in memory before the workflow's writes run, so it now uses the design's dedicated workflow bound of 100 pages. * feat(commandhost): note bounded repetition in Page dry-run previews A Page[T] command's dry-run can only show the first request; fabricating response-dependent page tokens is forbidden. Append the bounded-repeat explanation to the previewed request (preserving any business description), matching the design's dry-run contract. Also give the example's list command a --page-token resume flag seeded into the request, documenting the resume convention: the framework owns --page-all/--page-limit/--page-delay while the starting cursor is a business-declared input, independent of --page-all. * docs(command): generate domain constants with English comments The generator emitted Chinese titles while the rest of the public extension packages document in English. Switch the generator to the "en" service title and regenerate. The generator already rejects a domain missing either locale, so the switch keeps its own guard. * docs(command): mark the host adapter read surface The Host* types, InspectCommand, InspectDomain and CloneSets exist for lark-cli's host adapter, not for business commands, but nothing said so at the symbols themselves. They cannot move to a subpackage: a Command holds its declaration unexported, so a sibling package has no way to reach it, and moving the wire types to internal/ would cycle back through CommandMetadata and CommandContext. Also correct HostPagination, which is not adapter-only -- ContextOptions and commandtest both carry it. * refactor(command): type CommandMetadata.Service as DomainName A set already declares its domain through ExtendDomain(DomainIm), yet every command repeated the same domain as a bare string that only the host compiler checked. Typing the field points authors at the generated enum and forces an explicit conversion when the value comes from a string variable. This does not make a mistyped literal a compile error -- an untyped constant still converts to DomainName -- so the mismatch check in CompileSets stays the actual net. The example and the wrapper fixture now declare command.DomainIm. The chat-brief example was also not gofmt-clean, which the CI format gate would have caught. * refactor(command): extract the command-set assembly steps buildInternalWithConfig is an orchestrator, and the business command sets were compiled inline inside it. Move that step to resolveShortcutSnapshot so the entry point reads as one call and the built-in/external merge has a name. newCommand carried six near-identical blocks that each nil-checked a hook and wrapped it in the same type assertion. Split them into one binder per hook shape; Normalize and Validate now share bindArgsHook since their signatures match. The behaviour is unchanged: an undeclared hook still erases to nil, and an empty renderer map still yields nil. * perf(shortcuts): stop re-cloning an already-isolated snapshot AllShortcuts deep-copies because a Shortcut carries slice fields whose backing arrays a shallow copy would share: an external distribution mutating registered[0].Flags[0] would corrupt the process-global list. That copy is worth its ~165us over 500+ shortcuts. Paying it four times per startup is not. auth, schema and the mount path each cloned the snapshot again, but they receive it from AllShortcutsWithExternal with no third-party code in between, and nothing in this repository mutates a shortcut element -- mountDeclarative takes a value receiver and only replaces slice headers. Drop those three copies and document the boundary on AllShortcuts so the next reader does not reintroduce them. Startup drops from four full clones to one. Benchmarks pin the remaining cost so a regression points at a new clone rather than at growth in the shortcut set. * fix(command): align the commandtest page bound and escape wrapper paths Two review findings, both of which let a business command pass its tests and then misbehave in production. The commandtest recorder walked 1000 pages for a complete-set collection while the host adapter stops at 100, so a command tested against 300 pages of fixtures would fail its first real --page-all run with PaginationLimitError. The bound now lives in internal/pagination, which both sides already import, and the hard-limit test scripts itself from that constant instead of restating 1000 -- the literal was what let the two drift apart. The testdata wrapper concatenated args.ID straight into the request path, contradicting PathSegment's own documented rule and the chat-brief example. ValidateRequestView does not cover this: "abc/other-users-file" cleans to itself, so an unescaped separator silently retargets the request. Since testdata is what an integrator copies first, route both call sites through one readRequest helper, mirroring chat-brief. The e2e assertion could not have caught it either -- PathSegment("chat_1") is "chat_1", so the check passed with or without the call. It now sends "chat/1" and asserts %2F reaches the wire; removing PathSegment fails it. * fix(command): deny network to the pre-confirmation hooks and four review findings Normalize and Validate run before the high-risk confirmation gate, and both received the full CommandContext, so a high-risk business command could POST or DELETE from Validate and leave remote side effects behind before the user was ever asked to confirm. Moving the gate earlier would contradict the documented hook order and would also make --dry-run require --yes. The design already forbids this from the other side -- Validate is specified as parameter checking that issues no request -- so enforce that instead: Normalize and Validate get a context whose CallJSON and CollectPages refuse, while PreflightScopes stays available. The guard sits in CommandContext rather than in the wiring, so a future adapter that wires the callbacks anyway still cannot reach the API. commandtest mirrors it, otherwise a command would pass its tests and fail only in production. Page.Items now starts non-nil. It is declared required;nonnullable, but a zero-item collection encoded as {"items":null}, which a caller generating types from the published schema would reject. NewCmdAuthWithRecovery and NewCmdSchemaWithVisibility are restored as wrappers. Both were dropped for shortcut-aware variants, and both are reachable from outside this module: CommandVisibility is an ordinary exported func type, and *recovery.Projector cannot be named by an outside caller but can be passed as nil. A signature test now pins them. The path-traversal fixture said "../../secret", which the deterministic gate rejects as a generic credential assignment -- the reason CI is currently red. The filename carries no meaning; it is now "../../outside". * test(cmd): exercise the retained constructors instead of naming them The compatibility wrappers restored for outside callers are unreachable from inside this repository by construction, so the incremental dead-code gate rejected them. A signature-only assertion did not help: taking a function value and discarding it leaves the body unreachable, and it proved nothing about whether the wrapper still builds a working command. Call each one and assert the command it returns. NewCmdAuthWithRecovery is called with a nil projector, which is the exact call an outside module can make and the reason the wrapper has to keep compiling. Verified with the same deadcode version CI runs: neither function is reported, and no other function in this branch's files is either. * docs(command): document the hook contract and pin dry-run note idempotency Hooks is the first type a business author reads and carried no field documentation, so the rules lived only in the design doc: which of DryRun and DryRunE to set, that setting both fails to compile, that Execute owns the API call and must not write stdout, and that Normalize and Validate run before the confirmation gate and therefore get no network. The choice between DryRun and DryRunE is not old-versus-new -- neither is legacy. It follows from whether building the preview can fail, which is now what the field docs say. Also pin the dry-run note as idempotent. convertDryRun writes the bounded-repeat note into the projection it builds, never back into the hook's *DryRun, and DryRunAPI.Desc assigns rather than appends, so a hook that caches and returns the same preview cannot accumulate the note. Both properties were true and neither was tested. * refactor(command): settle the dry-run constructor, tips, and domain enum Three narrowings of the V1 business-command contract, none of which has a published compatibility surface: extension/command does not exist on main. Preview and NewDryRun were the same constructor twice -- one empty, one seeded with requests. Fold them into a variadic NewDryRun. Every existing NewDryRun() call keeps compiling, and the domain word in the contract is now spelled one way. The type DryRun already owns that identifier in this package, so naming the constructor DryRun outright cannot compile. Drop Metadata.Tips. It was pure passthrough into common.Shortcut.Tips and nothing in the execution path read it, so business commands lose only the ability to declare help tips; the repository's own typed shortcuts keep theirs. The mount test asserted a tip reached the rendered help as proof that metadata survives the extension -> commandhost -> common.Shortcut -> help conversion; it now asserts the risk line, which travels the same path. Hand-write the domain enumeration and delete the generator. Generating from shortcuts.AllShortcuts silently omitted approval, attendance and mindnotes: all three are published under `lark-cli --help` and served by typed and raw API commands, they just own no shortcut. The enum is now the 23 domains the CLI actually exposes. Those three would otherwise have been constants that compile and always fail, because CompileSets derived its mountable domains from the same shortcut list. It now reads the service registry, and shortcuts/register.go already creates a domain command group on demand when no built-in occupies it, so a business command can mount under a shortcut-less domain. * ci: stop generating extension/command The domain enumeration is hand-written now and extension/command holds no go:generate directive, so the path was a no-op that still read as if the package carried generated files. * refactor(command): drop DryRunE and let the preview render like a built-in DryRunE has no counterpart in the shipped CLI: `git show main:shortcuts/common/types.go` has no such field, it arrived with the typed-shortcut framework this branch imported, and no shortcut in the repository sets one. Business commands get the single DryRun hook that built-in shortcuts have. Validate already runs before it and owns the error channel, so a preview that cannot be built still fails there with a typed error -- which is what the repointed tests now assert, end to end through --dry-run and through commandtest.Preview. Also stop appending the bounded-repeat note. convertDryRun added "with --page-all, repeats with the returned page_token until exhaustion or --page-limit" to every Page[T] preview, so an external command's dry-run carried a sentence its author never wrote. Built-in paginated shortcuts say this themselves when they want it (im_chat_members_list.go calls dry.Desc), and external commands now do the same: the framework renders the description it was given and nothing else. The dry-run context keeps refusing requests -- runner.go does the same for built-ins, so removing that would be the divergence, not the alignment. Only the word changes: "offline" was our own vocabulary for what the rest of the CLI calls dry-run. * refactor(command): drop the partial-failure outcome from the contract Business commands now return Success only. Partial, OutcomeDefinition, PartialFailureDefinition and FailedItemDefinition leave the public surface along with Execution.Partial and the host adapter's receipt conversion. Result keeps its outcome field. It is no longer a choice -- Success is the only value -- but it is also how the host tells a returned Result apart from the zero value that accompanies an error, which is the check commandtest.Execute makes before reporting "returned both Result and error". Collapsing it to nothing would delete that signal. The exemplar commands that returned Partial keep their scenarios: a best-effort scope failure still marks every item failed and appends the snapshot, and the multi-call audit still records the owner it could not resolve. That information lives in the command's own Data (Items[].State plus Failures), not in the outcome, so the tests assert the same facts and only the outcome assertion is gone. The deep-copy test moved its nested JSON exemplar from FailedValues to InputDefault.Value, keeping cloneJSONValue covered. shortcuts/common still defines PartialFailure for built-in typed shortcuts. That is the imported framework, untouched here. * refactor(shortcuts): walk pages once for built-in and external commands Commit 4d0c6ea61 added internal/pagination, moved PaginateInto onto it, and then wrote a second caller for externally declared commands. Both assembled the same Walk options, cloned the same params, read the same cursor and mapped the same walk error; only the policy source, the call path and the accumulator ever differed. Those three now parameterize one pageWalk. PaginateInto keeps calling through the RuntimeContext and keeps its per-page progress line; external commands keep CallTypedAPI, the walker's context and their undecoded pages, which the public contract needs because it decodes them into its own Page[T]. Behavior is unchanged on both sides -- the external walk still leaves Wait nil, which internal/pagination fills with WaitContext, so --page-delay works exactly as before. pageWalk is deliberately generic-free so one struct serves both callers; the typed half of the built-in path moved to addDecodedPage. * refactor(shortcuts): make the external page walk PaginateInto's twin CollectCommandPages now differs from PaginateInto only where the context type forces it. It takes the same PageAccumulator, decodes each page into T through the same addDecodedPage, returns the same *output.PaginationMeta and reads the same state out of the same walk, in the same order. What is left is what the interface cannot supply. An externally declared command compiles in the business module, so it holds a CommandContext rather than a *RuntimeContext: the context arrives as a parameter because the interface carries none, the call goes through CallTypedAPI, and there is no progress line because deciding to print one needs StderrIsTerminal, JqExpr and Format, none of which the interface exposes. The all parameter stays. It is the complete-set policy CollectAllPages depends on -- collect to exhaustion under the hard page bound instead of obeying --page-all and --page-limit -- and PaginateInto has no way to express it, since resolvePaginationPolicy only ever reads flags. Dropping it would quietly turn a command that must see the whole set into one a user can truncate with --page-limit 1. CommandPageCollection is gone with it: pages accumulate in commandhost's own accumulator, the way every built-in shortcut already accumulates its own. One consequence of sharing the decode: a page whose response carries no data object is now an error on this path too, as it always was for built-ins. * fix(shortcuts): reject recursive Data and Args types during compilation shapeForType and compileStructShape called each other without recording the Go types already being walked, so a self-referential type recursed forever. The walk ran during command registration and ended in a stack overflow -- a fatal runtime error rather than a panic, so no recover boundary could contain it and one extension command took the whole CLI down before --help, schema, or any unrelated command could run. That also broke CompileErasedDefinition's documented promise to compile without panic. Thread the struct types open on the current recursion path through both functions and return a compile error on a repeat visit, pointing at the explicit Shape escape hatch. Membership is scoped to the path, not the whole walk, so a type reused as a sibling or at another depth stays legal. Covers self-reference through a slice and through a pointer, mutual recursion through two types, the JSON-encoded Args path, and the public CompileErasedDefinition contract. * fix(command): share one result protocol between the host and commandtest commandtest.Execute only checked that Data carried the expected type. Generic erasure leaves a correctly typed zero Data behind, so a business command that returned Result{} instead of Success(data) passed the type assertion and the test reported success. Production rejects the same result, which left extension authors with green tests and a command that failed on every real invocation -- exactly the guarantee commandtest exists to provide. Add ValidateHostResult in extension/command and call it from both commandtest.Execute and the host adapter's execute hook, so the two surfaces cannot drift. It rejects an empty or unsupported outcome and mirrors the pagination receipt checks the host already applies: declared Page output, pages of at least one, non-negative items, and next-token state consistent with completeness. RunWithFlags is covered because it delegates to Execute. * feat(command): expose reusable download capabilities * test(command): make the chat-brief example testable and cover its hooks The example declared both commands as inline Definition literals handed straight to Define. Define erases the type parameters and returns an opaque Command that cannot hand its Definition back, while commandtest.Execute takes the Definition -- so the shape the example demonstrated could not be unit tested at all. Neither shipped example had a test file, so nobody had walked the copy-the-example-then-add-a-test path. Lift both declarations into Definition-returning functions, the shape the repository's own commandtest suites already use, and keep the compiled Commands as package vars so main is unchanged. The configuration bodies are untouched. Add the tests that shape exists for: the single-read projection and its Validate rejection, plus the Page[T] contract for default single-page reads and a --page-all walk through RunWithFlags. All four run offline through the commandtest recorder. * test(commandtest): cover the ordered URL download script Recorder.ReplyURL shipped without a caller, so the incremental dead code gate flagged it as new unreachable code and blocked the branch. The existing URL download test uses the unordered RespondFile constructor, which never exercises the URL assertion ReplyURL exists for. Mirror the ReplyJSON pair: one test walks two scripted URLs in order and checks the recorded source URLs, content types, and artifacts; the other points DownloadURL at an unscripted URL and expects the mismatch error. * feat(command): accept @file input for external commands V1 rejected the file value source, leaving external commands with inline flags and stdin only. A process has one stdin, so a command whose body is too large or too quoted for the shell -- an XML document update is the case that surfaced this -- had no second way to receive it, and the caller had to fall back to shell escaping. Nothing downstream was missing: resolveInputFlags already resolves @path and the @@ escape through the invocation's FileIO, help renders the "@file" affordance, and legacyInputSources maps the source onto the compiled flag. The gap was the public constant and the host allow-list. Export SourceFile and let it through compilation. Unknown sources still fail the same way, which the rewritten host test now pins alongside the compiled flag actually carrying both extra sources -- silently dropping a declared source is the regression worth catching. Give the wrapper fixture a command whose content flag declares all three sources, and drive it end to end: @file and stdin both reach the request body, and the help text advertises them. * revert(content): drop the default content exports from the extension surface Exporting the repository's embedded skills and affordance trees turned two content directories into Go packages, because go:embed cannot reach up out of a package directory and the repository root is package main. That cost two things: a .go file living inside an authored-content tree, where a future content type is silently omitted until someone edits the glob, and an embed directive per tree where the root previously covered both in one. The need it served does not exist. The distribution driving this work ships its own skills and does not consume the official set, and a wrapper that does want them can supply a tree through cmd.SetEmbeddedSkillContent, which is what extension/platform already documents. Restore content_embed.go, the SkillsOverlay comments, and the platform README to their main state, and delete the two exporting packages. The example and fixture wrappers now ship no embedded content, which is what a wrapper that does not compile the repository root actually gets; the e2e assertion that depended on inheriting lark-doc goes with it. * fix(command): close the review findings on API surface and storage commit Five findings from the extension-v1 review, each verified by a test that fails against the previous implementation. Source compatibility of auth.LoginOptions. The shortcut snapshot was an unexported field on a struct that appears in the exported runF signature, which ends positional literals for every caller outside this module. It becomes a closure capture plus an explicit authLoginRun parameter, and the six domain helpers collapse into domainResolver methods, removing five xxxWithShortcuts twins that only tests reached. common.Shortcut.DryRunE goes too: it was a new exported field with no production caller. The unexported typed field stays, so Shortcut itself is still not positional-literal compatible -- that is a deliberate remaining gap, since relocating it would need a global mutable map or a wider signature change. One canonical wire projection. queryValues stringified and dropped nils for the live call while the dry-run preview and the pagination walk forwarded raw values, so a preview could describe a request the runtime would never send. canonicalQuery is now the only projection and all three consumers derive from it. Dry-run output for numeric parameters therefore reads "20" instead of 20, matching what the query string actually carries. No-clobber as a storage guarantee. IfExistsFail checked existence, downloaded, then committed with a rename that replaces unconditionally, so a target created during the transfer was silently overwritten. The commit step is now an optional ExclusiveFileIO capability: content lands in a temp file and is published with Link, which refuses an existing target and never exposes a partial file. A provider without the capability is refused rather than served a guarantee it cannot keep. V1 public surface. Removes NewDomain and its options (host compilation rejected them), HostDomain.IsNew, reservedRootNames, and the unproducible ResultMetaDefinition.Count; narrows Hooks.Renderers to a single PrettyRenderer, since pretty was the only key the compiler accepted; and demotes the generic authoring layer in shortcuts/common to unexported, as no production code outside that package used it. commandtest runs the production compiler. Execute, RunWithFlags and Preview now share compileForTest, so a wrong tag, Shape or relation fails in the unit test instead of at CLI startup. Applying this surfaced two long-standing contract violations in the package's own fixture. * refactor(command): keep a single authoring contract * revert(schema): keep the schema command blind to shortcuts The schema command serves the generated API catalog only, matching main. Drop the shortcut contract lookup and completion from cmd/schema and restore the constructor surface. ShortcutSchema stays on the sealed commandbridge surface, where the host compiler tests assert the contract; the CLI itself no longer consumes it. The surface scenario and wrapper e2e pin the boundary from the other side: schema resolution and completion must not see mounted shortcuts. --------- Co-authored-by: sang-neo03 <266690410+sang-neo03@users.noreply.github.com> Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>	2026-08-25 20:22:13 +08:00
sang-neo03	164d3ccd27	fix(registry): describe the attendance and mindnotes domains (#2210) ... Both are registered, reachable business domains — `lark-cli attendance user_tasks query` and `lark-cli mindnotes nodes create` run, and both appear in `auth login --domain` — but neither had an entry in service_descriptions.json. GetServiceTitle/GetServiceDescription returned "", so buildDomainMeta fell back to the typed service spec, which carries one string for both languages. The result was visible in `--help`: mindnotes rendered its Chinese description in the English domain list, and attendance rendered "attendance record query", a lowercase fragment shown in both locales. Both keep their own scope namespaces (attendance:task:readonly, mindnote:node:create/read) and stay independent auth domains, so no auth_domain is set. whiteboard remains the only domain folded into docs. TestGetDomainMetadata_HasTitleAndDescription could not catch this: it asserts on buildDomainMeta's output, which the fallback had already made non-empty. The new reconciliation test walks EmbeddedServicesTyped plus AllShortcuts and asserts both languages resolve from the config itself, before any fallback. EmbeddedServicesTyped is the overlay-free parse, so the test does not depend on what remote_meta.json happens to hold on the machine — a domain that only ever arrives via remote overlay stays out of its reach.	2026-08-06 19:02:21 +08:00
liangshuo-1	47c9741ce0	feat: profile selection from environment with source-aware errors (#2198)	2026-08-05 23:09:22 +08:00
evandance	09feefe96b	fix: make agent recovery and concealment reliable (#2189)	2026-08-05 19:44:11 +08:00
evandance	ebdeda854d	feat(extension): present restricted commands as absent and trim skills (#1837)	2026-08-05 01:44:50 +08:00
luozhixiong01	d8fb368ce4	test: isolate unit tests from user state (#1883)	2026-07-20 22:22:39 +08:00
leave330	fc8d212a4f	feat: add application domain with slash command management shortcuts (#1806)	2026-07-13 20:43:19 +08:00
evandance	c5b5aece33	refactor: retire legacy error envelopes and enforce typed contract (#1449) ... * refactor: retire legacy error envelopes and enforce typed contract Consolidate all command error reporting onto the typed errs.* contract, remove the legacy error surface that predated it, and tighten the lint guards so the contract holds across the whole repository going forward. Every failure now reaches stderr as one envelope shape: a category, an optional subtype, a human- and agent-readable message, and a recovery hint, with invalid parameters listed under `params`. The legacy ExitError envelope, its constructors, and the boundary bridge that promoted untyped config and authorization errors are deleted, leaving a single path from error to wire. Predicate commands keep their silent-exit behavior through a dedicated signal that carries only an exit code. Infrastructure paths that still emitted ad-hoc envelopes — flag parsing, unknown commands and subcommands, plugin and policy guards, confirmation prompts, and auth/config failures — now classify into the same taxonomy. Business, API, auth, and config exit codes are preserved; the one behavioral change is that Cobra usage failures (missing required flag, unknown command, bad arguments) now emit the typed validation envelope and exit 2, matching the explicit flag and subcommand guards, instead of Cobra's plain-text exit 1. Enforcement is repo-wide rather than per-path: - The errscontract guards run by default everywhere instead of through a migration allowlist, so legacy envelopes cannot be reintroduced anywhere. - errorlint runs across the whole repository: every error wrap must use %w and every comparison must use errors.Is/errors.As, so interior wraps stay legal but can no longer break the chain the typed boundary relies on. - The errs-no-bare-wrap guard is keyed by structural prefix instead of an explicit per-domain allowlist, so new shortcut domains are covered without editing a list. It runs where forbidigo is enabled (the shortcut domains and the auth/config/service command groups); repo-wide chain integrity for the remaining command paths is carried by errorlint above. * test: align cli_e2e success assertions to the ok envelope The api and service success path now emits the {"ok":true} envelope, so the cli_e2e workflow assertions that still expected the old {"code":0} shape via AssertStdoutStatus(t, 0) fail once they run with live credentials. Switch those workflow assertions to AssertStdoutStatus(t, true); the fake-payload helper test in core_test.go keeps its code-shape assertion.	2026-06-17 19:42:38 +08:00
liangshuo-1	deb0bd9dd6	refactor: converge command pipelines onto a typed metadata model + catalog (#1191)	2026-06-13 18:02:50 +08:00
JackZhao10086	d1a0926dd6	feat/revoke token (#1434)	2026-06-12 17:49:33 +08:00
max	7c64e63b9d	feat(note): clarify note ownership with dedicated detail and transcript flows (#1435) ... * feat: split note domain * fix: address note transcript review comments * fix: stabilize empty note detail detection	2026-06-12 16:30:41 +08:00
JackZhao10086	465c789f7c	feat: add --json flag support to auth subcommands (#1431) ... * feat: add --json flag support to auth subcommands * feat(auth/logout): add json output support for logout command * feat(auth/list): add json output support for auth list command	2026-06-12 15:04:14 +08:00
liangshuo-1	510545f1e5	refactor(vc): consolidate note handling back into the vc domain (#1417)	2026-06-12 00:44:35 +08:00
max	c11cf3b716	feat: split note domain (#1345) ... Add note shortcuts for note detail and unified transcript retrieval, route vc note detail parsing through the note domain, and update note/vc/minutes skill guidance for normal versus unified transcript handling. Includes dry-run E2E coverage for the new note shortcuts and documents the remaining live E2E fixture gap.	2026-06-11 22:38:29 +08:00
JackZhao10086	00d45f8fa2	feat: adjust agent timeout hint output conditions (#1328)	2026-06-09 10:05:11 +08:00
JackZhao10086	0bdd7de807	refactor(auth): update login hint and split-flow docs (#1201)	2026-06-01 16:47:18 +08:00
evandance	99e314fe0b	feat(errs): typed envelope contract for auth-domain errors (#1135) ... Every failure on the authentication, authorization, and configuration path now surfaces as a typed structured error instead of an ad-hoc envelope. Users and scripts that consume CLI output get: - a fixed nine-category taxonomy on the wire, each mapped to a stable shell exit code (authentication/authorization/config = 3, network = 4, internal = 5, policy = 6, confirmation = 10) - identity-aware detail fields (missing_scopes, requested_scopes, granted_scopes, console_url, log_id, retryable, hint) carried uniformly on the envelope - a single canonical policy envelope at exit 6; the legacy auth_error carve-out is retired - per-subtype canonical message + hint that preserves Lark's diagnostic phrasing and routes recovery to the right actor: app developer (app_scope_not_applied), user (missing_scope, token_scope_insufficient, user_unauthorized), or tenant admin (app_unavailable, app_disabled) - wrong app credentials classify as config/invalid_client whether surfaced by the Open API endpoint (99991543) or the tenant access-token mint endpoint (10003 / 10014), instead of collapsing to a transport error or api/unknown - local shortcut scope preflight emits the same authorization/missing_scope envelope (identity + deterministic missing-scope set) used by the post-call permission path, so AI consumers read the same structured shape from precheck and from server-returned permission denial - streaming download/upload failures keep the same network subtype split (timeout / TLS / DNS / transport) as the non-stream path instead of collapsing every cause to a generic transport failure - console_url is carried only on the bot-perspective app_scope_not_applied envelope (where the recovery action is "developer applies the scope at the developer console"); the user-perspective missing_scope envelope drops the field, since the only actionable user recovery is `lark-cli auth login --scope` and pointing an end user at a console they cannot modify is misleading - bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic Type tags to wire 'config' with the original module name kept as a metric label All 10 typed errors are cause-bearing, nil-safe on .Error() and .Unwrap(), and defensively clone slice setter inputs. Four lint rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry / CheckBuildAPIErrorArms) lock these invariants on migrated paths.	2026-05-30 19:08:41 +08:00
luozhixiong01	3b770558e5	feat: decouple --lang preference from TUI display language (#1132)	2026-05-28 18:55:40 +08:00
AlbertSun	17cbc13fcb	refactor(auth): drop duplicate top-level user fields in status (#1128) ... * opt: trim duplicate auth status info * fix: update signals of auth status workflow	2026-05-27 16:07:21 +08:00
evandance	fe72e41fb2	feat(errs): add structured CLI error contract (#984) ... Introduce a typed error contract framework for lark-cli so in-process Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts, AI agents, and protocol adapters can branch on stable JSON type/subtype fields instead of regex-parsing free-form messages. Adds: - Canonical taxonomy under errs/ (9 categories + typed Error structs embedding a shared Problem, RFC 7807-aligned) - Centralized Lark code metadata + identity-aware BuildAPIError dispatch - Typed JSON envelope writer alongside the legacy envelope writer - MCP / OAuth (RFC 6750 Bearer) projection adapters - Five CI lint guards preventing ad-hoc taxonomy drift Backward compatibility: legacy *output.ExitError producers (ErrAPI, ErrWithHint, Errorf, ErrBare) and business shortcuts that use them continue to render the legacy envelope unchanged. SecurityPolicyError wire format and exit code are preserved via a carve-out; taxonomy migration is deferred to PR 2. Domain-specific business migration is staged across PR 3+. Framework-direct paths now return typed *errs.*Error: ErrAuth / ErrValidation / ErrNetwork emit category literals on the wire (authentication / validation / network), *core.ConfigError is promoted at the cmd/root boundary with exit code aligned from 2 to 3, and Lark API permission denials classified by BuildAPIError exit 3. At the SDK boundary, WrapDoAPIError preserves any already-classified error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth from missing credentials surfaces with the auth category and exit 3 intact instead of being downgraded to a network error. Policy responses classified by BuildAPIError (codes 21000 / 21001) extract challenge_url and the canonical hint from the response body, matching what the auth transport already surfaces at the HTTP layer; non-https challenge URLs are dropped. First PR in the feat/error-contract-* series.	2026-05-26 11:42:33 +08:00
JackZhao10086	06a3921f40	optimize: remove fenced code block guidance from auth URL output hints (#1088)	2026-05-25 22:37:11 +08:00
JackZhao10086	cb5055eb46	feat(auth): add auth qrcode subcommand and update auth docs/hints (#968) ... * feat(auth): add auth qrcode subcommand and update auth docs/hints * refactor(auth/qrcode): improve qrcode command with validation and custom output	2026-05-25 15:34:00 +08:00
liangshuo-1	daba3c9afd	feat(apps): gate apps domain off on Lark brand (#1025) ... * feat(apps): gate apps domain off on Lark brand The Miaoda apps OpenAPI is Feishu-only. On Lark brand: - shortcut subtree is registered + hidden, RunE returns a structured brand-restriction error so users see a clear message instead of cobra's generic "unknown command" - auth login `--domain apps` is treated as unknown; `--domain all` skips apps; help text omits it - scope collection skips apps shortcuts so spark:* scopes are never requested The leaf-stub pattern mirrors internal/cmdpolicy/apply.go::installDenyStub (DisableFlagParsing + ArbitraryArgs + leaf-level PersistentPreRunE override) so cobra can't short-circuit the stub with a missing-flag or parent-PreRunE detour. Change-Id: I5817e87ae6fedabdb5faf05d0d32ea988f7effc9	2026-05-22 03:03:41 +08:00
raistlin042	6cea6c9af0	feat(apps): add miaoda apps domain (6 shortcuts + dry-run e2e) (#1002) ... Adds the apps domain to lark-cli for managing Miaoda (妙搭) applications: 6 shortcuts covering the full lifecycle (+create / +update / +list / +access-scope-set / +access-scope-get / +html-publish). Aligned with the OAPI v2 design — app_type enum (currently HTML), string scope enum (All / Tenant / Range), cursor pagination, in-memory tar.gz multipart publish flow. Namespace registered at /open-apis/spark/v1/ with spark:app.* scopes. --------- Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>	2026-05-21 20:30:42 +08:00
zed	94b103dbf6	fix(auth): return validation error when --scope is empty in auth check (#999) ... strings.Fields("") returns an empty slice, causing --scope "" to bypass validation and return ok: true. Replace the false-positive success path with an ErrValidation error so callers correctly detect the invalid input. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-21 11:52:05 +08:00
liangshuo-1	e6bc292575	fix(identitydiag): harden verify path and tighten status semantics (#961) ... * fix(identitydiag): harden verify path and tighten status semantics Follow-ups to #957: - bound bot/user verify calls with a 10s timeout (mirrors the doctor endpoint probe) so a hanging server cannot wedge `auth status --verify` or `doctor` - return StatusNotConfigured (not StatusMissing) when the user-identity path is blocked by missing app config, matching the bot side - surface the `{code, msg}` envelope on bot-info HTTP 4xx responses so callers see why bot auth was rejected, not just the bare HTTP code - introduce identity{User,Bot,None} constants in cmd/auth/status.go and use the exported StatusMessage() in the human-readable note instead of raw status codes like "not_configured" - collapse the duplicated verify-failed identity construction in the user path into a local helper - cover the new failure paths with unit tests (HTTP 4xx with envelope, business error code, user server-rejected, expired user token, strict-mode user-only, missing app config for user) Change-Id: I581348a65f15b1452a6f48a3e3245d09257314ac * fix(identitydiag): decode bot/v3/info from "bot" field, not "data" `/open-apis/bot/v3/info` returns `{code, msg, bot: {...}}` — the bot payload is under `bot`, not `data` as the newer Lark API convention would suggest. The decoder was reading from a non-existent `data` field, so `envelope.Data.OpenID` was always empty and every successful verify was reported as `Bot identity: verify failed: open_id is empty`. The pre-existing test mocks used `{"data": {...}}` matching the buggy decoder, so unit tests passed while production reads of every Lark account failed verification. Fix: - change the JSON tag on the envelope from `json:"data"` to `json:"bot"` - update mocks in identitydiag and cmd/auth/status tests to emit `bot` Verified locally: `lark-cli doctor` now reports `bot_identity: pass` for both a normal account and a bot-only profile, restoring the behavior that #957 set out to deliver. Change-Id: Ib26dfdd5a0cc37d2d62537ae2bf5e854e67cb83c * fix(shortcuts/common): decode bot/v3/info from "bot" field, not "data" Same schema bug as the one fixed in identitydiag — `RuntimeContext. fetchBotInfo` reads from a non-existent "data" key, so every successful call would report "open_id is empty" once a caller starts depending on it. There are no production callers of `RuntimeContext.BotInfo()` yet (only tests + the `TestNewRuntimeContextWithBotInfo` helper), so this bug is dormant — but the pre-existing tests pass with the same wrong schema in their mocks, so the first real consumer would silently break. Fix: tag `json:"data"` → `json:"bot"` plus aligning the four mock fixtures in runner_botinfo_test.go. The Go field name `Data` is kept to minimize the diff; only the JSON contract is corrected. Change-Id: I11e1e871603e5349f8df29b1d58e35d07b628dfd	2026-05-19 15:50:40 +08:00
RZERO	b8469d2dc6	fix(auth): split bot and user identity diagnostics (#957)	2026-05-19 13:46:57 +08:00
JackZhao10086	c8b9809f96	Revert "feat(auth): add QR code support for device auth flow (#942)" (#950) ... This reverts commit 7af616b9e5.	2026-05-18 22:12:03 +08:00
JackZhao10086	7af616b9e5	feat(auth): add QR code support for device auth flow (#942) ... * feat(auth): add QR code support for device auth flow * docs: update login QR code display hints for AI agent * feat(auth): add ASCII QR code support for auth flow * docs: add comments for login and auth helper functions * chore: remove unused qrCodeToBase64 helper function * fix(auth/login): clarify verification_url handling in login hint	2026-05-18 20:17:15 +08:00
sang-neo03	33c292c05e	feat(extension): Plugin / Hook framework with command pruning (#910) ... * feat(extension): introduce Plugin / Hook framework with command pruning Add a single public extension contract under extension/platform: integrators implement the Plugin interface and register Observers, Wrappers, Lifecycle handlers, and pruning Rules through the Registrar in one Install call. Command pruning: - Rule (Allow / Deny / MaxRisk / Identities) with doublestar globs - 4-axis AND evaluation, parent-group aggregation, unknown-risk allow - Sources: Plugin.Restrict (single-rule) and ~/.lark-cli/policy.yml - Plugin path is fail-closed (envelope on rule error / multiple Restrict); yaml path is fail-open (warning, CLI continues) - strict-mode stubs now also write the denial annotation so the hook layer's denial guard physically isolates Wrap chains on them - HOME path never leaked through policy_source label Hook framework: - Observer (panic-safe, Before/After), Wrapper (middleware, may short-circuit via AbortError), Lifecycle (Startup + Shutdown only) - Recover guards every plugin entry point: Capabilities(), Install(), Wrapper factory composition AND inner Handler, Lifecycle handlers - namespacedWrap copies AbortError so a plugin's package-level sentinel is never mutated across concurrent invocations - Selector unknown-risk uniform: ByExactRisk / ByWrite / ByReadOnly never match unannotated commands; safety-side hooks opt in via ByWrite().Or(ByUnknownRisk()) Bootstrap orchestration (cmd/build.go + cmd/policy.go): - InstallAll uses a staging Registrar + atomic commit - FailClosed plugin install / Plugin.Restrict conflict / Startup handler failure each install a structured envelope guard at every dispatch path - walkGuard neutralises every cobra bypass we know of (PersistentPreRunE first-wins, ValidateArgs, ParseFlags, legacyArgs, __complete / __completeNoDesc, non-runnable groups, required-arg subcommands) - cmd/root.go::Execute calls hook.Emit(Shutdown, runErr) after rootCmd.Execute; isCompletionCommand skips both __complete and __completeNoDesc so Tab completion never triggers Shutdown handlers Capabilities consistency: - Restricts=true must declare FailurePolicy=FailClosed - RequiredCLIVersion (semver constraint) is validated against build.Version; a malformed constraint is treated as untrusted-config and aborts unconditionally, regardless of FailurePolicy (DEV builds included) JSON envelope contract: - error.type closed enum: pruning / strict_mode / hook / plugin_install / plugin_conflict / plugin_lifecycle - reason_code closed enums per type, all referenced by structured tests Bootstrap surfaces (new user commands): - lark-cli config policy show -- JSON view of the active Rule + source - lark-cli config policy validate -- parse + schema + glob check, no apply Coverage: - extension/platform: every public type has a unit test - internal/{pruning,hook,platformhost,policydecision,cmdmeta}: full coverage of denial guard isolation, AbortError sentinel safety, observer panic safety, lifecycle error/panic typing, staging atomic rollback - cmd/plugin_integration_test.go: end-to-end through buildInternal with synthetic and real command trees - cmd/install_guard_test.go: walkGuard covers auth / config / __complete / __completeNoDesc / non-runnable parents * fix(pruning): deny stub must override Args + PersistentPreRunE The pruning denyStub and the strict-mode stub previously only swapped RunE plus Hidden + DisableFlagParsing. Cobra's dispatch order means several pre-RunE gates can fire BEFORE the stub's RunE ever runs: 1. Args validator: shortcut commands often declare cobra.NoArgs. With DisableFlagParsing=true the user's `--doc xxx --mode append` looks like positional args, so ValidateArgs surfaces a usage error instead of the pruning / strict_mode envelope. Observer hooks also miss the dispatch entirely. 2. Parent PersistentPreRunE: cmd/auth/auth.go declares a PersistentPreRunE that returns external_provider when env credentials are set. Cobra's "first PersistentPreRunE wins walking up from the leaf" then short-circuits with external_provider instead of the leaf's denial envelope. Both stubs now also set: - Args = cobra.ArbitraryArgs (bypass gate 1) - PersistentPreRunE = no-op leaf hook (bypass gate 2) - PreRunE / PreRun / PersistentPreRun = nil (defensive) Effect: dispatch reaches the wrapped RunE, observers fire, the real pruning / strict_mode envelope is emitted regardless of credential provider or flag count. Adds regression tests covering both gates on both stub paths. * fix(config): policy subcommand bypasses parent's credential check cmd/config/config.go::NewCmdConfig declares a PersistentPreRunE that calls f.RequireBuiltinCredentialProvider; with env credentials set, it returns external_provider for every config subcommand. `config policy show` and `config policy validate` are READ-ONLY diagnostic commands -- they inspect or parse the user-layer rule without touching credentials. They MUST work regardless of which credential provider is active, otherwise users on env-credential deployments cannot debug their policy. Same shape as the codex C11/C13 fix: install a no-op leaf-level PersistentPreRunE on the `policy` group so cobra's "first walking up from leaf" rule picks ours over the config parent's. Regression caught by divergent e2e (F1-F6 all returned external_provider before this fix; all pass after). Adds a unit test pinning the PersistentPreRunE override. * feat(shortcuts): tag service groups with cmdmeta.Domain RegisterShortcutsWithContext now calls cmdmeta.SetDomain on each service-level cobra.Command (im, docs, drive, calendar, ...) so the business-domain axis is actually populated on every shortcut leaf via parent-chain inheritance. Before this change, platform.ByDomain("docs") never matched any command: the domain annotation was unset across the entire shortcut tree, so the selector's d != "" guard always failed and risk-style selectors silently degraded to no-op. The SetDomain call is placed AFTER the create-or-reuse branch so it fires whether the service command was freshly created here or had already been added by cmd/service/service.go's OpenAPI auto- registration (which runs first and creates im, drive, calendar, etc.). Without this placement only pure-shortcut services like docs would have been tagged. Adds a regression test asserting: - service-group cobra.Command carries the cmdmeta.domain annotation - leaf shortcuts inherit the domain via parent-chain walk * feat(diagnostic): add unconditionally allowed command paths for introspection * feat(plugins): add diagnostic command to inspect installed plugins and their contributions * fix(cli): surface unknown_subcommand error instead of silent help fallback When a user passed an unknown subcommand or shortcut (e.g. `lark-cli drive +bogus`), cobra returned `flag.ErrHelp` for the non-runnable group command, printed the parent help, and exited 0. AI agents couldn't distinguish a typo from an intentional help request. Install a tree-wide guard that attaches a RunE to every group command without its own Run/RunE. The RunE forwards no-args invocations to help (preserving prior behavior) and emits a structured unknown_subcommand ExitError (exit 2) listing available subcommands when args are present. * refactor(envelope): rename error.type pruning/strict_mode to command_denied The envelope's `type` field was leaking implementation terms ("pruning", "strict_mode") that describe enforcement mechanism rather than the user- facing semantic. It also duplicated `detail.layer`, and forced consumers to branch on two values for the same conceptual error ("a command was denied by policy"). Collapse both into a single semantic type "command_denied". The enforcement layer ("pruning" / "strict_mode") is preserved in `detail.layer` so debugging and per-layer diagnostics still work. * feat(platform): fail closed on unannotated/invalid risk when a Rule is active The pruning engine used to treat any command without a risk annotation as ALLOW even when a Rule with MaxRisk was set, and would silently skip the MaxRisk comparison whenever the command's risk string was outside the closed taxonomy. Both gaps let an unannotated or typo'd write command slip past an "agent read-only" pruning rule. Engine now denies before any other axis when a Rule is registered: - reason_code "risk_not_annotated" for commands with no risk - reason_code "risk_invalid" for commands whose risk is outside the read | write | high-risk-write taxonomy (e.g. typo "wrtie") Main-flow is preserved: a nil Rule still returns Allowed=true unconditionally, so a CLI with no pruning plugin behaves identically to before. ByUnknownRisk() is removed from the public surface since the Unknown state is no longer reachable through risk-based selectors when any Rule is active; safety-side widening composition is no longer needed. * chore(config): hide diagnostic policy/plugins commands from --help `config policy show`, `config policy validate`, and `config plugins show` are local-introspection-only commands kept behind the pruning diagnostic whitelist so operators can always inspect why a command was denied. They do not need to surface in `--help` for AI agents and were contributing to help noise. Hide the `policy` and `plugins` parent groups and both `show` / `validate` leaves. Commands remain callable by exact name and continue to bypass user-layer pruning via diagnosticPaths. * style: gofmt * fix(platform): nil Selector honours None contract; reject multi-doc policy yaml - selector.go: And/Or/Not now treat nil Selector as None() per godoc, preventing runtime panic when composed selectors are invoked. - schema.go: Parse rejects multi-document YAML input so a stray '---' separator can't silently drop trailing policy constraints. * chore: go mod tidy * feat(extension/platform): plugin SDK with policy engine, hooks, and Builder Introduces extension/platform — the in-process plugin SDK external Go forks of lark-cli use to extend or restrict the command surface. Plugins compile in via blank import; there is no dynamic loading and no RPC isolation. Public SDK (extension/platform): - Plugin interface (Name / Version / Capabilities / Install). - Registrar verbs: Observe, Wrap, On, Restrict. - Hook types: Observer (side-effect, panic-safe, fires Before/After RunE), Wrapper (middleware, may short-circuit via AbortError), LifecycleHandler (Startup / Shutdown), Selector with nil-safe And/Or/Not composition. - Risk / Identity are defined string types with closed taxonomies; ParseRisk / ParseIdentity convert raw strings with the absent-vs-invalid distinction the engine relies on. - Builder ergonomic constructor (NewPlugin().Observer().Wrap() ...MustBuild()) that enforces name/hookName grammar, hookName uniqueness, and the Restrict ↔ FailClosed pairing regardless of call order. - Invocation is a read-only interface; the framework's concrete invocation type lives in internal/hook so plugins cannot fabricate denial / strict-mode / identity state. Args() returns a defensive copy on every call so hook mutation cannot leak into the original RunE. - CommandDeniedError + AbortError carry structured fields for the closed `command_denied` / `hook` envelope contract. - ResetForTesting gated behind //go:build testing. - README + godoc examples (Observer / Wrapper / Restrict) + two runnable example forks (audit-observer, readonly-policy). Host (internal/platform, internal/hook, internal/cmdpolicy): - InstallAll: staged plugin registration with atomic commit, panic isolation, FailOpen / FailClosed semantics, RequiredCLIVersion semver check, single-Restrict invariant, duplicate-plugin-name detection. - hook.Install wraps every runnable cmd.RunE with: Before observers (panic-safe) → denial guard → composed Wrap chain → original RunE → After observers (always fire, even on err). Denied commands physically bypass the Wrap chain so a plugin Wrapper cannot suppress or rewrite a denial; observers still see the attempt for audit. - Recover shim around plugin Wrappers converts panics (including the factory call) into a structured `hook` envelope with reason_code=panic; namespacing shim attributes AbortError to the namespaced hook name. - cmdpolicy (renamed from internal/pruning) is the user-layer command policy engine: walks the cobra tree, evaluates each runnable command against a Rule's four-axis filter (Allow / Deny / MaxRisk / Identities), produces parent-group aggregate denials, and installs denyStubs. Rule.AllowUnannotated opts out of the unannotated-deny gate for gradual adoption; risk_invalid typos always deny with an edit-distance "did you mean" suggestion. - Strict-mode stub in cmd/prune.go composes the shared detail.* / wrapped CommandDeniedError shape via cmdpolicy helpers (BuildDenialError / CommandDeniedFromDenial / DenialDetailMap), so command_denied envelopes from strict-mode and user-layer policy carry the same closed-enum fields (detail.layer / reason_code / policy_source). The historical short Message + independent Hint are preserved unchanged. - cmdpolicy/yaml: structural parsing of ~/.lark-cli/policy.yml with KnownFields strict mode, including allow_unannotated. - `config policy show` / `config policy validate` and the plugin inventory diagnostic surface the resolved Rule (allow, deny, max_risk, identities, allow_unannotated) and the hook contributions per plugin. Envelope contract (docs/extension/reason-codes.md): - error.type is a closed set: command_denied, hook, plugin_install, plugin_conflict, plugin_lifecycle. - reason_code is a closed enum per error.type, dispatched on by external agents and CI integrations. - detail.layer = "policy" | "strict_mode" attributes the rejection. Build / CI: - Makefile unit-test / vet / coverage and ci.yml fast-gate + unit-test + coverage now pass -tags testing so register_testing.go is visible; ./extension/... is in the package list so the SDK's own tests actually run. - fmt-check and examples-build Makefile targets. - bmatcuk/doublestar/v4 added as a direct dependency for `**` glob matching in Rule.Allow / Rule.Deny. Author-facing material: - docs/extension/ (quickstart, plugin-author-guide, reason-codes) is provided in the working tree but kept out of git tracking per repo convention (.gitignore covers docs/). Change-Id: I3b8ecc2923bd54c2dff19e5dce8a0855a6f9e703 * feat(extension/platform): plugin SDK with policy engine, hooks, and Builder Introduces extension/platform — the in-process plugin SDK external Go forks of lark-cli use to extend or restrict the command surface. Plugins compile in via blank import; there is no dynamic loading and no RPC isolation. Public SDK (extension/platform): - Plugin interface (Name / Version / Capabilities / Install). - Registrar verbs: Observe, Wrap, On, Restrict. - Hook types: Observer (side-effect, panic-safe, fires Before/After RunE), Wrapper (middleware, may short-circuit via AbortError), LifecycleHandler (Startup / Shutdown), Selector with nil-safe And/Or/Not composition. - Risk / Identity are defined string types with closed taxonomies; ParseRisk / ParseIdentity convert raw strings with the absent-vs-invalid distinction the engine relies on. - Builder ergonomic constructor (NewPlugin().Observer().Wrap() ...MustBuild()) that enforces name/hookName grammar, hookName uniqueness, and the Restrict ↔ FailClosed pairing regardless of call order. - Invocation is a read-only interface; the framework's concrete invocation type lives in internal/hook so plugins cannot fabricate denial / strict-mode / identity state. Args() returns a defensive copy on every call so hook mutation cannot leak into the original RunE. - CommandDeniedError + AbortError carry structured fields for the closed `command_denied` / `hook` envelope contract. - ResetForTesting gated behind //go:build testing. - README + godoc examples (Observer / Wrapper / Restrict) + two runnable example forks (audit-observer, readonly-policy). Host (internal/platform, internal/hook, internal/cmdpolicy): - InstallAll: staged plugin registration with atomic commit, panic isolation, FailOpen / FailClosed semantics, RequiredCLIVersion semver check, single-Restrict invariant, duplicate-plugin-name detection. - hook.Install wraps every runnable cmd.RunE with: Before observers (panic-safe) → denial guard → composed Wrap chain → original RunE → After observers (always fire, even on err). Denied commands physically bypass the Wrap chain so a plugin Wrapper cannot suppress or rewrite a denial; observers still see the attempt for audit. - Recover shim around plugin Wrappers converts panics (including the factory call) into a structured `hook` envelope with reason_code=panic; namespacing shim attributes AbortError to the namespaced hook name. - cmdpolicy (renamed from internal/pruning) is the user-layer command policy engine: walks the cobra tree, evaluates each runnable command against a Rule's four-axis filter (Allow / Deny / MaxRisk / Identities), produces parent-group aggregate denials, and installs denyStubs. Rule.AllowUnannotated opts out of the unannotated-deny gate for gradual adoption; risk_invalid typos always deny with an edit-distance "did you mean" suggestion. - Strict-mode stub in cmd/prune.go composes the shared detail.* / wrapped CommandDeniedError shape via cmdpolicy helpers (BuildDenialError / CommandDeniedFromDenial / DenialDetailMap), so command_denied envelopes from strict-mode and user-layer policy carry the same closed-enum fields (detail.layer / reason_code / policy_source). The historical short Message + independent Hint are preserved unchanged. - cmdpolicy/yaml: structural parsing of ~/.lark-cli/policy.yml with KnownFields strict mode, including allow_unannotated. - `config policy show` / `config policy validate` and the plugin inventory diagnostic surface the resolved Rule (allow, deny, max_risk, identities, allow_unannotated) and the hook contributions per plugin. Envelope contract (docs/extension/reason-codes.md): - error.type is a closed set: command_denied, hook, plugin_install, plugin_conflict, plugin_lifecycle. - reason_code is a closed enum per error.type, dispatched on by external agents and CI integrations. - detail.layer = "policy" | "strict_mode" attributes the rejection. Build / CI: - Makefile unit-test / vet / coverage and ci.yml fast-gate + unit-test + coverage now pass -tags testing so register_testing.go is visible; ./extension/... is in the package list so the SDK's own tests actually run. - fmt-check and examples-build Makefile targets. - bmatcuk/doublestar/v4 added as a direct dependency for `**` glob matching in Rule.Allow / Rule.Deny. Author-facing material: - docs/extension/ (quickstart, plugin-author-guide, reason-codes) is provided in the working tree but kept out of git tracking per repo convention (.gitignore covers docs/). Change-Id: I3b8ecc2923bd54c2dff19e5dce8a0855a6f9e703 * refactor(policy): remove validate command and update diagnostics * fix(extension/platform): address PR review must-fix items - cmdpolicy: skip AnnotationPureGroup commands in EvaluateAll, aggregateParents, and hasRunnableDescendant so user-layer policy no longer blocks `<group> --help` after the unknown-subcommand guard attaches RunE to every parent - cmd/root: tag guarded parent groups with AnnotationPureGroup - extension/platform: drop `//go:build testing` from register_testing.go so `go test ./...` works without an extra build tag - extension/platform/README: inline reason_code reference, fix plugin lifecycle diagram order (init/Register precede RegisteredPlugins) - cmd/platform_bootstrap: route userPolicyPath through core.GetBaseConfigDir so LARKSUITE_CLI_CONFIG_DIR is honoured - cmdpolicy: add RedactHomeDir helper, fold base config dir and $HOME prefixes for config policy show + resolver errors - internal/platform: reject unrecognised FailurePolicy values with invalid_capability instead of silently fail-open - cmd/config: surface diagnostic policy/plugins commands in `config --help` Long text - CHANGELOG: document command_denied error.type rename and unknown_subcommand exit-2 behavior change * fix(extension/platform): address CodeRabbit review comments + CI gofmt - hook/install: propagate wrapper-injected ctx to invokeOriginal so RunE/Run see context values added by upstream Wrappers - hook/testing: SetStderrForTesting returns a restore func; tests now defer it via t.Cleanup to avoid cross-test sink leakage - cmdpolicy/active: deep-copy ActivePolicy.Rule on SetActive/GetActive so callers can't mutate the stored global through shared slices - platform/inventory: deep-copy Inventory + nested Plugins / HookEntry / RuleView slices on SetActiveInventory / GetActiveInventory - platform/staging: Restrict clones the plugin-supplied Rule before retaining it so the plugin can't mutate it after Install returns - platform/version: reject RequiredCLIVersion with more than three numeric components instead of silently truncating 1.2.3.4 to 1.2.3 - cmd/platform_bootstrap: clear cmdpolicy.SetActive on yaml resolver error so config policy show doesn't surface a stale rule - cmd/platform_bootstrap_test: tmpHome pins LARKSUITE_CLI_CONFIG_DIR so host env can't bleed into the policy test fixtures - cmdpolicy/apply: installDenyStub returns bool; Apply count no longer over-reports when strict-mode short-circuits the install - cmdpolicy/engine: aggregateParents now returns the runnable hybrid's own denial status when all children are placeholder branches - cmdpolicy/resolver_test: use t.TempDir()-rooted missing path instead of hardcoded /nonexistent for hermetic missing-file assertion - cmd/config/plugins: empty-inventory branch emits total: 0 so the JSON schema stays stable across populated/empty cases - cmd/platform_guards_test: select leaf by RunE != nil (not Runnable) so the test doesn't nil-deref on Run-only commands - gofmt run on previously committed cmdpolicy/path*.go (CI fast-gate) * fix(cmdpolicy): replace filepath.Abs with filepath.Clean for lint policy The depguard / forbidigo rule blocks filepath.Abs in internal/ on the grounds that it accesses the filesystem (Getwd) directly. Switch RedactHomeDir + foldPrefix to operate on filepath.Clean strings; real callers pass already-absolute paths (resolver builds yamlPath via filepath.Join on the absolute config root), so the redaction outcome is unchanged for production inputs. Relative inputs fall through to the unchanged branch — filepath.Rel rejects the mixed-absoluteness case with an error, which the foldPrefix helper already treats as "not a hit". * refactor(cmdpolicy): pure Resolve + drop path redaction & verbose comments - Resolve becomes a pure function; I/O moves to LoadYAMLPolicy so precedence selection can be unit-tested without vfs mocks - ActivePolicy drops YAMLPath; config policy show JSON loses yaml_path and yaml_shadowed (and the TOCTOU stat that surfaced them) - RedactHomeDir and path_test.go removed: the home-dir folding was only earning its keep through the now-deleted yaml_path field - cmd/build.go bootstrap block trimmed from 71 to 39 lines by cutting PR-rationale comments; one note kept for the fail-CLOSED-vs-fail-OPEN business rule - cmd/config/config.go: parent Long no longer hard-codes hidden command hints, matching their Hidden:true intent Change-Id: Icfbb818ce3ef523c63286bfbed34c49be08ed6a2 * refactor(platform): drop StrictMode/Identity from Invocation interface These two accessors were documented in the public SDK as "After observers always see ok=true" but the framework never plumbed values to them, so they always returned ("", false). Zero internal/example/test callers; a plugin author trusting the doc would silently get wrong behaviour. Identity is also fundamentally unsuited for Before observers (per-command identity resolves inside RunE via f.AuthFor, after Before fires). StrictMode is a global value better placed on a Framework/Environment interface than per-Invocation. Removing is non-breaking now (no callers); adding later is non-breaking too. Change-Id: Ice200543e9bca3bda759ad98a6e34a56df69e915 * fix(prune): preserve original metadata on strict-mode denial stubs strictModeStubFrom built a fresh *cobra.Command from scratch, dropping the original command's annotations (risk_level, lark:supportedIdentities, cmdmeta.domain) and help text. cobraCommandView is a live proxy walking parent annotations, so after the Remove+Add replacement, audit observers firing on a strict-mode-denied command saw Cmd().Risk()=("",false) and Cmd().Identities()=nil -- breaking the first-class use case for audit/compliance plugins. Copy child.Annotations into the stub (stamping the denial annotations on top) and propagate Short/Long for help-text parity with cmdpolicy/apply.go::installDenyStub, which preserves these by virtue of mutating in place. Regression test asserts risk_level / supportedIdentities / Short / Long all survive replacement, alongside the denial annotations. Change-Id: I19810a34575996344b63e839066888c154d69335 * chore(platform): align docs with implementation; fold home in yaml warnings Followup cleanup to the previous three refactor commits, addressing review fallout where public docs / examples / contract notes still pointed at deleted symbols or unimplemented designs: - cmd/build.go: Build() docstring now mentions the plugin install + Startup emit side effects; Shutdown only fires on Execute path - extension/platform/doc.go, lifecycle.go, invocation.go: drop references to the deleted StrictMode/Identity methods, restore minimal Godoc on Cmd/Args/Started - extension/platform/view.go, cmd/platform_bootstrap.go, internal/hook/install.go: rewrite "snapshot before pruning" promise to match the actual contract (live view + strict-mode stub metadata preservation) - cmd/platform_guards_test.go: stubInvocation drops the two old methods - cmd/platform_bootstrap.go: redactHome() last-mile folds $HOME -> ~ in warnPolicyError so an os.PathError carrying the absolute policy path does not leak the user's home dir to stderr / agent / CI logs - examples/readonly-policy/README.md: drop yaml_path from the sample `config policy show` envelope (the field was removed in 52cbb92) Change-Id: I2874cc2cf9225dfa44a9c07b2449149181b387cb * chore(build): drop vestigial -tags testing from Makefile and CI The `testing` build tag was introduced in 461e3c6 to gate extension/platform/register_testing.go (ResetForTesting); PR review 0efee93 then dropped the //go:build testing directive from that file so downstream `go test ./...` would work without the tag, but never cleaned the matching tag references out of Makefile and ci.yml. The result: 8 places passing -tags testing for a tag that nothing in the repo actually gates, plus a Makefile comment that confidently claims a gate exists. Net behaviour is identical to omitting the flag; the only effect is misleading developers into believing there is a test-only surface separation. Drop the flag from vet / unit-test / lint / coverage / deadcode (head + base worktree) and remove the misleading comment. ResetForTesting's public-API exposure was the conscious trade-off taken in 0efee93 and is left untouched. Change-Id: If0cd78c87d4aec2a2533419fe75b01aae6b165fd * feat(cmdpolicy): enrich denial Reason with attempted value + rule constraint The envelope reason for command_denied previously told the caller WHAT axis failed but not the concrete values on each side, so an AI agent reading the envelope could not tell which command identity / risk / path was attempted vs. which the rule permits. The natural temptation was then to recommend modifying the rule -- exactly the wrong nudge, since policy exists to prevent the agent from rewriting its own limits. Each Reason now carries both the attempted value and the rule's constraint: identity_mismatch: "command supports identities [user]; rule allows [bot]" domain_not_allowed: "command path \"drive/+upload\" not in allow list [docs/** contact/**]" command_denylisted: "command path \"docs/+delete-doc\" matched deny pattern \"docs/+delete-*\"" risk_too_high / write_not_allowed: "command risk \"high-risk-write\" exceeds rule max_risk \"write\"" risk_not_annotated: "command has no risk_level annotation; rule denies unannotated commands" (drops the prescriptive "set allow_unannotated=true" hint -- that belongs in docs, not in the engine's denial path) Adds firstMatch() helper so command_denylisted can name the specific glob that fired; matchesAny() now wraps firstMatch. Regression test pins the substring contract per reason_code so future "comment cleanup" cannot silently strip the values out again. Change-Id: I17c7cc9411f58e3e43ade5e1ce875f3b7fe3e5ea * fix(cmdpolicy): gofmt engine_test.go CI fast-gate flagged the test added in 2eb0c2b as unformatted. Local make unit-test had it cached; should have run `make vet` (which runs gofmt-equivalent check via fmt-check) before pushing. Trivial 3-line indent fix. Change-Id: I42297ae59f607b97b32e976c9ec1c9ec4ab7de21 * feat(cmd): annotate risk_level on all hand-written cobra commands Without this, any non-empty user-layer policy.yml (default allow_unannotated=false) denies these commands with reason_code risk_not_annotated -- bricking auth login, config init, profile use etc. on first contact with a policy. cmdpolicy/engine evaluation now resolves to the intended axis (deny list / allow list / max_risk / identities) instead of failing closed on the unannotated gate. Policy authors can write `max_risk: write` or `allow: [auth/** config/** ...]` to express real intent. Classification: read auth status/check/list/scopes, config show / policy show / plugins show, doctor, completion, schema, profile list, event list/status/schema/ consume write auth login/logout, config init/bind/remove/ default-as/strict-mode, profile add/remove/ rename/use, event stop/_bus, api (raw transit) high-risk-write update (replaces the CLI binary; failure can leave the install broken) Notes: - api standalone is conservatively `write`; per-call risk is unknown at parse time (raw transit), so static gating only enforces the write-class minimum. - event _bus is the hidden IPC daemon forked by consume; standalone invocation by users is not expected, but the annotation keeps policy evaluation consistent with the other event subcommands. - The two diagnostic-allowlisted commands (config policy show / plugins show) still bypass the engine via diagnosticPaths; the read annotation is for consistency with surrounding leaves. --------- Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>	2026-05-18 15:25:02 +08:00
吕盈辉律师	7bad9f2656	fix: guide agents to yield during auth device flow (#933)	2026-05-18 11:48:09 +08:00
fangshuyu-768	52e0129078	feat(drive): add quick mode to status diff (#870)	2026-05-14 20:37:39 +08:00
JackZhao10086	37459b60ec	feat(auth): support --exclude flag and combine --scope with --domain/… (#844) ... * fix(auth/login): 增加exclude参数使用校验逻辑 当使用--exclude参数时，必须同时指定--scope、--domain或--recommend中的至少一个，避免非法参数调用 * feat(auth/login): add --exclude flag and support combining scope options 1. 新增--exclude命令行标志用于排除指定的授权范围 2. 移除--scope与--domain/--recommend的互斥限制，改为叠加使用 3. 重构范围合并与排除逻辑，增加校验和辅助工具函数 4. 更新--scope参数的帮助文档说明叠加行为 * fix(auth/login): 修复登录命令scope参数描述重复的问题 移除了重复的参数说明文本，整理冗余的注释内容，让帮助文档更清晰易读 * fix(auth/login): 修复exclude参数校验逻辑 添加--exclude参数必须配合其他可选参数使用的校验，避免无效的exclude参数调用 --------- Co-authored-by: cqc-a11y <chengqingchun@bytedance.com>	2026-05-14 14:12:29 +08:00
aj	b0c9a4d74e	fix(auth): support comma-separated --scope in auth login (#764) ... `lark-cli auth login --scope "a,b"` previously sent the raw comma-joined string to the device authorization endpoint, which treats it as a single malformed scope and fails with: device authorization failed: The provided scope list contains invalid or malformed scopes. OAuth 2.0 (RFC 6749 §3.3) requires space-delimited scopes on the wire, but commas are the more natural separator for users typing on a shell (quoting whitespace is awkward, especially for AI-agent generated commands). Accept both: split on commas/whitespace, trim, dedupe, then re-join with single spaces. Also adds unit tests covering single, comma, space, mixed, dedupe, and trailing-separator inputs. Co-authored-by: aj <2072584+meijing0114@users.noreply.github.com>	2026-05-13 14:27:55 +08:00
JackZhao10086	ddc24fec90	fix(auth): clarify URL handling in auth messages and docs (#856)	2026-05-13 14:09:53 +08:00
liangshuo-1	27a2f2758b	fix(config): make agent-binding hints workspace-aware and surface user-identity risks (#728) ... AI agents running inside OpenClaw / Hermes were routinely creating a parallel app via `config init --new` instead of binding to the agent's existing app, because every "not configured" hint and several deny errors hard-coded `config init` regardless of workspace. Once bound, the same agents could silently grant themselves user identity (impersonation) without the user ever seeing a risk message in chat. Changes: - Introduce `core.NotConfiguredError` / `NoActiveProfileError` / `reconfigureHint` helpers that branch on `CurrentWorkspace()`. In agent workspaces they point at `lark-cli config bind --help` (a help page, not a ready-to-run command) so AI must read the binding workflow and confirm identity preset with the user before acting. In local terminals they preserve the previous `config init --new` guidance. - Migrate every `config init` hint that should be workspace-aware: RequireConfigForProfile, default credential provider, credential provider fallback, secret-resolve mismatch, config show, strict-mode entry-point errors, default-as, profile use/rename/remove, auth list, doctor's config_file check (which now also wraps the OS-level "no such file" noise into the user-shaped "not configured" message). - Refuse `config init` when run inside an OpenClaw / Hermes workspace by default; add `--force-init` for the rare case the user genuinely wants a parallel app. Without this guard, hint fixes were undone the moment AI ignored them. - Rewrite the strict-mode deny errors in cmd/auth/login.go, cmd/prune.go, and internal/cmdutil/factory.go. The previous "AI agents are strictly prohibited from modifying this setting" terminated AI reasoning while providing no real gate. New errors point at `config strict-mode --help` with the legitimate confirmation flow and explicitly note that switching does NOT require re-bind. Integration test envelopes updated. - Tighten `config bind --help` and `config strict-mode --help` to encode the user-confirmation discipline directly: identity preset semantics (bot-only vs user-default), "DO NOT switch without explicit user confirmation", and a cross-reference clarifying that `config bind` is for changing the underlying app while `config strict-mode` is the policy-only switch (resolves an ambiguity an audit run found). - Surface user-identity (impersonation) risk at every config write that newly grants it, by reusing the canonical IdentityEscalationMessage string from bind_messages.go: - `noticeUserDefaultRisk` fires on flag-mode bind landing on user-default, including the first-time case `warnIdentityEscalation` misses (it requires a previous bot lock). - `setStrictMode` warns when transitioning bot → user or bot → off (newly permits user identity); stays quiet on narrowing changes and on off → user (off already permitted user). - Add tests: notconfigured_test.go (workspace branches), init_guard_test.go (refuse + --force-init bypass), bind_warning_test.go (user-default warning fires; bot-only does not), strict_mode_warning_test.go (5 transitions covering both warn and no-warn paths). Two follow-ups intentionally deferred: the keychain master-key hint at internal/keychain/keychain.go:42 still suggests `config init` because the keychain package can't import core (would be circular); fixing requires either parameterizing the hint via callback or extracting workspace into its own package. The lark-shared skill doc still tells AI to run `config init` for first-time setup; updating the skill is in scope for a follow-up PR. Change-Id: I02273e044d9e061d211ceaa4f3ed5a3fb28325b3	2026-05-06 19:27:24 +08:00
JackZhao10086	15ae1fabec	fix(auth): handle missing scopes and device flow improvements (#752) ... * fix(auth): handle missing scopes and device flow improvements * fix: remove redundant error return in login scope handler * test(auth): rename test for zero interval default case * fix: increase device code polling timeout from 180 to 600 seconds	2026-05-06 17:10:27 +08:00
wittam-01	f27b8fdf40	feat: add markdown shortcuts and skill docs (#704) ... Change-Id: Iced88525deb10b014b755ec68bd9a8ae6a935143	2026-04-30 15:47:36 +08:00
MaxHuang22	7d0ceb5d58	feat: block auth/config when external credential provider is active (#627) ... * feat(credential): add ActiveExtensionProviderName to detect external providers Change-Id: Ie17a4b714e5eca17ae574ac188d570721790107d * feat(cmdutil): add RequireBuiltinCredentialProvider guard for external credential providers Change-Id: I8f2ea0af6fe6506b29beb69264b04c21c0f75da1 * feat(config): block all config subcommands when external credential provider is active Change-Id: If215cb8f0a53cc92d623dd3d842e4465124af2be * feat(auth): block all auth subcommands when external credential provider is active Change-Id: Ia61184fb2daeb6a7a38d122c647b7cb67eaf8b1f * fix(auth,config): silence usage in PersistentPreRunE to match root command behaviour Change-Id: I6d4b3c7d9d9c7b10fc2482fdc80252bf051771ee * test(auth,config,credential): address CodeRabbit review comments - Use cmd.Find() to assert SilenceUsage on matched subcommand (not parent) - Add TestRequireBuiltinCredentialProvider_PropagatesProviderError for error path - Add 'external' fallback sentinel in ActiveExtensionProviderName Change-Id: Iba35779ad2ed9807556264ba23db7096541e2bf3	2026-04-24 18:45:31 +08:00
tuxedomm	11191df703	fix: skip flag-completion registration outside completion path (#598) ... * fix: skip flag-completion registration outside completion path Cobra keeps completion callbacks in a package-global map keyed by *pflag.Flag with no removal path, so registrations made during Build() outlive the command itself. Route all seven call sites through cmdutil.RegisterFlagCompletion and enable registration only when the invocation actually serves a __complete request. Measured over 30 dropped Builds: ~202 KB / 2180 retained objects per Build before, ~0 after. Change-Id: I734d598a4c91a92c33b02e0f292f640cc0e224c6	2026-04-22 11:55:11 +08:00
JackZhao10086	e15aef922e	refactor(auth): simplify scope reporting in login flow (#582)	2026-04-21 14:07:51 +08:00
JackZhao10086	d5784eac28	feat(auth): improve login scope handling and messages (#523) ... * feat(auth): improve login scope handling and messages - Add AuthorizedUser message to display current authorized account - Update scope mismatch message wording to be more accurate - Reorganize login success output to show scope issues first - Remove redundant success message when scope issues exist * fix(auth): update login success message wording from "login" to "authorization" Update both Chinese and English login success messages to use "authorization" instead of "login" for consistency with the authentication flow. Also update corresponding test cases to match the new wording. * test(auth): update login test for missing scope case Update test assertions to verify correct error messages when requested scopes are not granted. Remove checks for success message in this scenario.	2026-04-17 12:16:29 +08:00
mazhe-nerd	2a301246f9	feat: skip auth check (#451) ... The secondary confirmation step in the interactive login process has been removed (Phase 2: After the user selects the complete domain name, permission level, and scope, they no longer need to confirm "authorize" again and can directly proceed to the authorization process).	2026-04-14 11:38:39 +08:00
syh-cpdsss	46468a900c	feat: Add whiteboard +query shortcut and enhance +update with Mermaid/PlantUML support (#382) ... Change-Id: I719935bb8fee337908ec99d59f1dfaae0df74874	2026-04-10 19:40:29 +08:00
liangshuo-1	cdd9f9ab49	chore: add missing license headers (#352) ... Change-Id: Ic26bedcbb111331eb53d695fccdabd0907a6272f	2026-04-08 23:11:01 +08:00
JackZhao10086	db9ca5c2a4	feat: improve login scope validation and success output (#317) ... * feat(auth): improve scope handling and output in login flow - Add scope validation to check for missing requested scopes - Implement detailed scope breakdown in login success output - Add new message strings for scope-related output - Refactor login success output to handle both JSON and text formats - Add tests for scope validation and output scenarios * feat(auth): add requested scope caching for device code login Implement caching of requested scopes during device code login flow to ensure proper scope validation after authorization. The cache is stored in JSON files under config directory and automatically cleaned up after successful or failed authorization. Add tests for scope caching functionality and verify proper integration with existing login flow. * docs(auth): add function comments for login scope handling Add detailed doc comments to all functions in login scope cache and result handling files to improve code documentation and maintainability. * refactor(auth): remove pending scopes and improve json output stability - Remove PendingScopes field and related logic as it's no longer needed - Add emptyIfNil helper to ensure nil slices are normalized to empty slices in JSON output - Update tests to verify JSON output stability and fix expected text outputs * refactor(auth): extract device token polling function for testability Move device token polling to a package-level variable to enable mocking in tests Add test case for scope cleanup when token is nil * fix(auth): return JSON write errors instead of ignoring them Previously, JSON write errors were only logged to stderr but not returned, causing tests to pass when they should fail. Now properly propagate these errors to callers and update tests to verify error handling. * refactor(auth): simplify scope handling and improve user messaging remove redundant scope display and consolidate hint messages to focus on actionable guidance * refactor(auth): improve scope handling and messaging in login flow remove ShortHint field and simplify scope hint messages always display missing scopes section with consistent formatting add StatusHint for successful login with no missing scopes update tests to reflect new message structure and content	2026-04-08 21:06:58 +08:00
liangshuo-1	555722ac8e	fix: resolve concurrency races in RuntimeContext (#330) ... * fix: resolve concurrency races in RuntimeContext - getAPIClient: replace check-then-act with sync.OnceValues, matching the factory_default.go convention; use NewAPIClientWithConfig to avoid post-construction config override; fall back to direct construction for test contexts that bypass newRuntimeContext. - outputErr: guard first-error capture with sync.Once to prevent data races if Out() is ever called from concurrent goroutines. Change-Id: I99c94c3dcb7663fa61571c9720163e41a5fc0e36 * fix: use tenant token for auth scopes Change-Id: I83bb677e9a33e906e207679b2ba8d0364bc20fe3	2026-04-08 19:14:45 +08:00
liangshuo-1	8db4528269	feat: add strict mode identity filter, profile management and credential extension (#252) ... * feat: add strict mode identity filter, profile management and credential extension Port changes from feat/strict-mode-identity-filter_3 branch: - Add strict mode for identity filtering and configuration - Add profile management commands (add/list/remove/rename/use) - Add credential extension framework (registry, env provider) - Add VFS abstraction layer - Refactor factory default and client options - Update shortcuts to use new credential and validation patterns Change-Id: I8c104c6b147e1901d94aefcefe35a174932c742b Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: go mod tidy Change-Id: I0f610ccea6bc874248e84c24770944a3071dcc57 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: fix test failures from credential provider migration - Remove unused TAT stub registrations in api and service tests (CredentialProvider manages tokens, SDK no longer calls TAT endpoint) - Update strict mode integration test: +chat-create now supports user identity, so it should succeed under strict mode user Change-Id: Iab51c2e12a97995e0b95dcd71df212d2d1f76570 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: migrate remaining os calls to internal/vfs Replace direct os.Stat/Open/MkdirAll/OpenFile/Remove/ReadDir/UserHomeDir with vfs equivalents in shortcuts/minutes, shortcuts/drive, and internal/keychain. Add ReadDir to the vfs interface and OsFs implementation. Change-Id: I8f97e5fb3e1731b4684d276644fcb10fae823067 * fix: resolve gofmt and goimports formatting issues Change-Id: If61578631f5698f7ca2d9a946ca59753651463fb * feat: add Flag.Input support for @file and stdin input sources Add framework-level support for reading flag values from files (@path) or stdin (-), solving the fundamental problem of passing complex text (markdown, multi-line content) via CLI arguments where shell escaping breaks content. Closes #239, fixes #163. - Add File/Stdin constants and Input field to Flag struct - Add resolveInputFlags() in runner pipeline (pre-Validate) - Support @@ escape for literal @ prefix - Guard against multiple stdin consumers - Auto-append "(supports @file, - for stdin)" to help text - Apply to: docs +create/+update --markdown, im +messages-send/+reply --text/--markdown/--content, task +comment --content, drive +add-comment --content Change-Id: I305a326d972417542aeadd70f37b74ea456461ef Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: fix pre-existing test failures in task, minutes, and registry - task/minutes: remove unused tenant_access_token httpmock stubs (TestFactory's testDefaultToken provides tokens directly, so the HTTP stub was never consumed and failed verification) - registry: fix hasEmbeddedData() to check for actual services instead of just byte length (meta_data_default.json has empty services array) Change-Id: Ic7b5fc7f9de09137a7254fe1ddf47d24ade40587 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: suppress nilerr lint for intentional nil returns Both cases intentionally return nil on error for graceful degradation: - profile list: show friendly message when config is not initialized - service: skip scope check when token resolution fails Change-Id: I7285c37277c9b0361a421ab00359244c2cd150b3 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address CodeRabbit review feedback - runner.go: fail fast when Input is used on non-string flags - remote_test.go: rename hasEmbeddedData → hasEmbeddedServices - profile/list.go: add omitempty to optional JSON fields - service.go: surface context cancellation errors in scope check Change-Id: I7072d41f8c711b4b37c542e32dfd8150f42b13c0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: tighten credential resolution and profile flows Change-Id: I83f6d424540eab9b1708944b9b6e26e8477cc60d * refactor: centralize identity hint resolution Change-Id: I38d5f98160b92adb62dc929ae73697ae5b3d64f8 * fix: surface unverified extension identities Change-Id: Ia86d9bd19add9010176339ec4cc89deb033f5b4f * fix: honor runtime credential sources in config views Change-Id: I40b2ffedc5c1db5e08e86b9472ea2b84fa02bb29 * fix: prefer runtime values in config show commands Change-Id: I5663a53e147577f0f1f533f67d12bea504e6b839 * Revert "fix: prefer runtime values in config show commands" This reverts commit 4f9db3a227. * Revert "fix: honor runtime credential sources in config views" This reverts commit b3bfd526c5. * fix: harden profile flows and credential boundaries Change-Id: Ica61cd2730a639f71516cb1b237a639cb6511f7a * fix: optimize profile and config inspection for agents Change-Id: I19c368102f19654952638180ab947788a6971563 * refactor: unify credential env contracts Change-Id: I0ff2c0a650ea53589a0626333e8f6e628ef10a54 * docs: expand AGENTS guidance Change-Id: I289027dfd364c92205012feef6f05037066c035b * fix: resolve regression bugs found during PR #252 review - im: fix double SafeInputPath in resolveLocalMedia → uploadImageToIM/ uploadFileToIM chain that rejected all local image/file uploads - credential: stop writing plain-text warnings to stderr, preserving JSON envelope contract for AI agent consumers - profile add: reject duplicate app-id to prevent keychain credential collisions across profiles - profile rename: exclude self when checking name uniqueness so renaming to own appId works correctly - config: replace bare fmt.Errorf with output.Errorf in save-failure paths (default_as, strict_mode ×2, profile add) - factory: remove unused resolveDefaultAs method (lint) Change-Id: I6aa0d064414016f367f1edb08dd0604adf7bf13d Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove flaky TestColdStart_UsesEmbedded (race in registry) The test triggers a data race: resetInit() writes package globals while a background goroutine from a previous test may still be reading them. The embedded-data path is covered by other tests. Change-Id: I7a0c3bf85a9fb337b9279c9053697f40a0c0a0d4 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: type-strengthen Brand and DefaultAs across credential chain Replace raw string fields with typed enums for compile-time safety: - extension/credential: add Brand and Identity named types - internal/core: AppConfig.DefaultAs and CliConfig.DefaultAs → Identity - internal/credential: Account.DefaultAs and IdentityHint.DefaultAs → core.Identity The full data flow is now typed end-to-end: extcred.Brand → core.LarkBrand (named-type cast) extcred.Identity → core.Identity (named-type cast) No string intermediaries, no implicit conversions. Change-Id: I715b3b3f033fcb624010f1af9619e3562740ef08 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * style: fix gofmt alignment in extension/credential/types.go Change-Id: Ibfac0703a5a28f3c6ba4a47bf40696028d0f3b90 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove file/stdin input support from task comment content flag Change-Id: If49704ca4612465a23bd30b755d6e72a35fc2349 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(cmdutil): remove dead code autoDetectIdentity autoDetectIdentity() is only called from tests, never from production code. Remove it along with its 3 test cases to reduce surface area before the upcoming ctx propagation refactor. Change-Id: I35a188860f17656f3e1fe9874f87f284985ae196 * refactor(cmdutil): add ctx parameter to resolveIdentityHint Private method resolveIdentityHint now accepts context.Context and passes it to CredentialProvider.ResolveIdentityHint instead of using context.Background(). The caller (ResolveAs) still uses context.Background() temporarily until its own signature is updated. Change-Id: I14634a4e0dc1d657d56936ba61a7b7a206da8ac4 * refactor(cmdutil): add ctx parameter to ResolveStrictMode ResolveStrictMode now accepts context.Context and passes it to CredentialProvider.ResolveAccount instead of using context.Background(). Callers in cobra RunE pass cmd.Context(); callers outside RunE (cmd/root.go startup, tests) use context.Background() explicitly. Change-Id: I31be48e548ac5ac5640a65f3bfdde4a53ed1dc7e * refactor(cmdutil): add ctx parameter to CheckStrictMode CheckStrictMode now accepts context.Context and forwards it to ResolveStrictMode. Callers pass cmd.Context() (cobra RunE) or opts.Ctx (APIOptions/ServiceMethodOptions). Change-Id: I47888519d4cae8c94054771c32aff075565a8cdc * refactor(cmdutil): add ctx parameter to ResolveAs ResolveAs now accepts context.Context as first parameter and forwards it to ResolveStrictMode and resolveIdentityHint. This completes the ctx propagation chain: all Factory methods that call CredentialProvider now receive ctx from cobra cmd.Context(). No more context.Background() calls remain in factory.go for credential provider operations. Change-Id: I6d10b6350e3b149470660de3e7855614314e8b29 * test: fix gofmt in cmdutil factory tests Change-Id: I4a87d5a815b959f14cc4371b73dee4aae106932f * fix: remove file/stdin input support from im send/reply and drive comment The Input (file/stdin) feature is not yet ready for these flags: - im send/reply: --content, --text, --markdown - drive add-comment: --content Retained only in doc create/update where markdown from file is essential. Change-Id: I582b6349528fccb639ad9edc84650cca3b68535c Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: liushiyao <liushiyao.1206@bytedance.com>	2026-04-07 15:21:14 +08:00