{"record":{"id":"8fa09feb5c3d9c3a","repo":"larksuite/cli","slug":"max-sheets-must-be-at-least-1","errorCode":null,"errorMessage":"--max-sheets must be at least 1","messagePattern":"--max-sheets must be at least 1","errorType":"validation","errorClass":"LarkCliError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_inspect_workbook.py","lineNumber":88,"sourceCode":"    workbook = envelope_data(\n        run_sheets(\n            \"+workbook-info\",\n            url=args.url,\n            spreadsheet_token=args.spreadsheet_token,\n            timeout=args.timeout,\n        )\n    )\n    # An explicit selector must resolve: without require_one a typo'd\n    # --sheet-id/--sheet-name silently yields sheet_count 0, which reads as\n    # \"empty workbook\" instead of a locator error.\n    target_sheets = resolve_target_sheets(\n        workbook,\n        sheet_id=args.sheet_id,\n        sheet_name=args.sheet_name,\n        require_one=bool(args.sheet_id or args.sheet_name),\n    )\n    if args.max_sheets < 1:\n        raise LarkCliError(\"--max-sheets must be at least 1\")\n    inspect_count = len(target_sheets)\n    if not args.sheet_id and not args.sheet_name:\n        inspect_count = min(len(target_sheets), args.max_sheets)\n        if inspect_count < len(target_sheets):\n            warnings.append(\n                f\"layout and preview skipped for {len(target_sheets) - inspect_count} sheets; \"\n                f\"pass --sheet-id or --sheet-name to inspect one\"\n            )\n\n    profiles = []\n    for position, sheet in enumerate(target_sheets):\n        sid = sheet_identifier(sheet)\n        title = sheet_title(sheet)\n        profile = _sheet_summary(sheet)\n        if position >= inspect_count:\n            profiles.append(profile)\n            continue\n        locator = sheet_locator(sheet)","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_inspect_workbook.py#L70-L106","documentation":"prepareSuite inspects the staged suite archive by listing direct subdirectories under suitePath/references via listDirectSubdirs. If that read fails (directory missing or unreadable), the error is wrapped as 'inspect suite archive'. This happens before the archive's child-skill list is validated against the official skill names.","triggerScenarios":"A suite-mode skills sync where the staged archive does not contain the expected .agents/skills/lark-suite/references directory (wrong archive layout, empty/corrupt staging result, or a StageSuite implementation that unpacked to an unexpected path).","commonSituations":"Upstream suite archive format changed so references/ moved or was renamed; StageSuite silently succeeded but unpacked nothing due to a path mismatch; a mocked runner staging an incomplete tree in tests; corrupt archive extraction.","solutions":["Inspect the wrapped cause to see whether references/ is missing vs unreadable, then check the staged path .agents/skills/lark-suite/references exists.","Verify the suite archive layout matches the expected .agents/skills/lark-suite structure; re-download a fresh archive.","Update the CLI if the upstream suite archive format changed (version mismatch between runner and archive layout).","Clear the staging/cache area and retry the sync to rule out a corrupt extraction."],"exampleFix":"// before: suite archive missing references/ (old layout)\narchive: {skills: {lark-suite: {SKILL.md}}}\n// after: expected layout\narchive: {.agents: {skills: {lark-suite: {SKILL.md, references: {auth/, docs/}}}}}","handlingStrategy":"type-guard","validationCode":"// Verify the expected suite layout before syncing\nif _, err := os.Stat(filepath.Join(staging, \".agents\", \"skills\", \"lark-suite\", \"references\")); err != nil {\n    return fmt.Errorf(\"suite archive missing references/: %w\", err)\n}","typeGuard":"func hasSuiteLayout(root string) bool {\n    st, err := os.Stat(filepath.Join(root, \".agents\", \"skills\", \"lark-suite\", \"references\"))\n    return err == nil && st.IsDir()\n}","tryCatchPattern":"if err := syncLayout(...); err != nil && strings.Contains(err.Error(), \"inspect suite archive\") {\n    // staged tree lacks .agents/skills/lark-suite/references: re-download or upgrade CLI\n}","preventionTips":["Pin the suite archive version to a CLI-compatible release.","Verify archive layout (references/ present) after staging and before install.","Refresh downloaded archives if the upstream format changed."],"tags":["go","filesystem","archive","skills-sync"],"backgroundTag":"archive-layout-mismatch","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}