pack.plan

Co by zabalil profil share/archive.yaml: nesené soubory a jejich bajty a tokeny o200k_base, každý vynechaný soubor podle důvodu (worktree, link, artifact, binary, derived, excluded; derived se počítá, ostatní se vypisují), shardy, na které se řeže v rámci tokenového rozpočtu a počtu souborů profilu, a každé zjištění, které build odmítne — soubor nad rozpočet, příliš mnoho shardů, strojová cesta nebo přihlašovací údaj ve vybraném souboru, prázdný výběr, profil bez limitů. Čte jen index a bloby gitu; nic nezapisuje.

query
behaviorally_verified
module pack
#pack
#archive
#review
#privacy

Zpřístupnění

Kde je tato jedna definice dosažitelná. Absence je explicitní: povrch, který není uveden, ji nenese.

povrch	jako
MCP	nástroj majordomus_pack_plan
HTTP	GET /api/v1/pack/plan operationId pack.plan
příkazová řádka	majordomus pack plan

Schémata

Kanonický vstup a výstup z typů Rustu; schéma nástroje MCP a parametry a odpovědi OpenAPI se odvozují z nich.

vstup · PackPlanInput

Vstup pack.plan: který profil share/archive.yaml plánovat, nebo výchozí profil distribuce, když žádný není pojmenován.

use majordomus_cli::capability::builtin::pack::PackPlanInput;
let input = PackPlanInput { profile: Some("chatgpt".into()) };
assert_eq!(input.profile.as_deref(), Some("chatgpt"));

vlastnost	typ	povinné	popis
profil	string \| null	ne	Profil `share/archive.yaml`; `default`, když chybí. výchozí null

JSON Schema

{
  "additionalProperties": false,
  "description": "The input of `pack.plan`: which profile of `share/archive.yaml` to plan, or the\ndistribution's default one when none is named.\n\n```\nuse majordomus_cli::capability::builtin::pack::PackPlanInput;\nlet input = PackPlanInput { profile: Some(\"chatgpt\".into()) };\nassert_eq!(input.profile.as_deref(), Some(\"chatgpt\"));\n```",
  "properties": {
    "profile": {
      "default": null,
      "description": "A profile of `share/archive.yaml`; its `default` when absent.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PackPlanInput",
  "type": "object"
}

output · PackPlan

Plán jednoho balíčku: co nese, co vynechává a proč, jak je rozřezán na shardy a zda může být sestaven.

Níže uvedené příklady plánují repozitář obsahující main.rs a logo.png, jejíž obsah je binární, s distribucí, jejíž profil chat má limity a profil bare žádné.

use majordomus_cli::pack::{plan, PackPlan};
#### use std::process::Command;
#### let dir = tempfile::tempdir().unwrap();
#### let (root, share) = (dir.path().join("repo"), dir.path().join("share"));
#### std::fs::create_dir_all(&root).unwrap();
#### std::fs::create_dir_all(&share).unwrap();
#### std::fs::write(share.join("archive.yaml"), "default: chat\nprofiles:\n  - id: chat\n    binary: drop\n    artifacts: drop\n    shards:\n      max_count: 5\n      max_tokens: 4000\n  - id: bare\n    binary: drop\n").unwrap();
#### let git = |a: &[&str]| assert!(Command::new("git").arg("-C").arg(&root)
####     .args(["-c", "user.email=t@example.com", "-c", "user.name=t"]).args(a)
####     .status().unwrap().success());
#### git(&["init", "-q"]);
#### std::fs::write(root.join("main.rs"), "fn main() {}\n").unwrap();
#### std::fs::write(root.join("logo.png"), b"\x89PNG\0\x01").unwrap();
#### git(&["add", "-A"]);
#### git(&["commit", "-q", "-m", "one"]);
let p: PackPlan = plan(&root, &share, None).plan;
assert!(p.measured && p.passes && p.index_matches_head);
assert_eq!((p.tracked, p.selected), (2, 1));
assert_eq!(p.dropped["binary"], 1);
// an unknown profile is not measured, and not measured is never a pass
let p: PackPlan = plan(&root, &share, Some("nope")).plan;
assert!(!p.measured && !p.passes);

vlastnost	typ	povinné	popis
bajty	integer	ano	Bajty nesoucího obsahu.
commit	string \| null	ne	Commit, který jmenuje `HEAD`; obsah je obsahem indexu, který se mu rovná, když je `index_matches_head` pravda.
zahozeno	object	ano	Kolik souborů bylo vynecháno, podle důvodu.
dropped_files	array	ano	Každý soubor vynechaný z jiného důvodu než `derived`.
zjištění	array	ano	Každý důvod, proč balík nelze sestavit. Prázdný výpis je úspěšná odpověď.
index_matches_head	boolean	ano	Zda index drží přesně to, co drží `HEAD`. `false` znamená, že připravené změny cestují s balíčkem pod id commitu, který je neobsahuje.
limity	jedno ze 2	ne	Uplatněné limity.
naměřeno	boolean	ano	Zda šlo strom vůbec přečíst. `false` není úspěch.
průchody	boolean	ano	`true`, když byl strom změřen a nic se nenašlo.
profil	string	ano	Plánovaný profil.
důvod	string \| null	ne	Proč to nešlo, když to nešlo.
vybráno	integer	ano	Kolik jich pack nese.
shardy	array	ano	Shardy v pořadí; index mezi ně nepatří.
tokenizér	string	ano	Tokenizér, ve kterém jsou počty vyjádřeny.
tokeny	integer	ano	Tokeny přeneseného obsahu v `o200k_base`.
sledováno	integer	ano	Kolik souborů index sleduje.

JSON Schema

{
  "$defs": {
    "DropReason": {
      "description": "Why a tracked file is not in the pack. Every reason but `derived` and `excluded` is\nfinal: no `include` of a profile re-admits a link, a gitlink, an artifact or a binary.\n\n```\nuse majordomus_cli::pack::DropReason;\nassert_eq!(DropReason::Binary.as_str(), \"binary\");\nlet json = serde_json::to_string(&DropReason::Artifact).unwrap();\nassert_eq!(json, \"\\\"artifact\\\"\");\n```",
      "oneOf": [
        {
          "const": "worktree",
          "description": "A gitlink: a nested repository or worktree whose content is not in this index.",
          "type": "string"
        },
        {
          "const": "link",
          "description": "A symbolic link, whose content is a path on the machine that committed it.",
          "type": "string"
        },
        {
          "const": "artifact",
          "description": "A path the distribution names as build output, a cache or a worktree container.",
          "type": "string"
        },
        {
          "const": "binary",
          "description": "Not text: a NUL byte, content that is not UTF-8, or an extension on the binary list.",
          "type": "string"
        },
        {
          "const": "derived",
          "description": "Marked `merge=derived` in `.gitattributes`: a projection of a file that is here.",
          "type": "string"
        },
        {
          "const": "excluded",
          "description": "Matched by the profile's `exclude`.",
          "type": "string"
        }
      ]
    },
    "DroppedFile": {
      "description": "One dropped file the report names. Derived files are counted, not listed: they are a\nfunction of files that are in the pack.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, DropReason, DroppedFile};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet dropped = plan(&root, &share, None).plan.dropped_files;\nlet want = DroppedFile { path: \"logo.png\".into(), reason: DropReason::Binary };\nassert_eq!(dropped, [want]);\n```",
      "properties": {
        "path": {
          "description": "The path.",
          "type": "string"
        },
        "reason": {
          "$ref": "#/$defs/DropReason",
          "description": "Why."
        }
      },
      "required": [
        "path",
        "reason"
      ],
      "type": "object"
    },
    "PackFinding": {
      "description": "A reason the pack cannot be built as planned, or a written pack is not what its\nmanifest says: a stable code, the path when there is one, and the remedy.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, PackFinding};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet findings: Vec<PackFinding> = plan(&root, &share, Some(\"bare\")).plan.findings;\nassert_eq!(findings[0].code, \"pack.no_limits\");\nassert!(findings[0].path.is_none() && !findings[0].remedy.is_empty());\n```",
      "properties": {
        "code": {
          "description": "A stable code: `pack.file_too_large`, `pack.too_many_shards`, `pack.index_too_large`, `pack.leak`,\n`pack.empty`, `pack.no_limits`, and from verification `pack.tampered`,\n`pack.not_text`, `pack.forbidden_path`, `pack.missing`, `pack.stray`,\n`pack.over_budget`, `pack.manifest`.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong.",
          "type": "string"
        },
        "path": {
          "description": "The path the finding is about, when it is about one.",
          "type": [
            "string",
            "null"
          ]
        },
        "remedy": {
          "description": "What settles it.",
          "type": "string"
        }
      },
      "required": [
        "code",
        "message",
        "remedy"
      ],
      "type": "object"
    },
    "ShardLimits": {
      "description": "The shard limits of a profile: the reader's own limits on what it can index, the file\ncount of a project and the tokens one file of it may hold.\n\n```\nuse majordomus_cli::pack::{Profiles, ShardLimits};\nlet p = Profiles::parse(\n    \"default: a\\nprofiles:\\n  - id: a\\n    shards:\\n      max_count: 20\\n      max_tokens: 900\\n\",\n)\n.unwrap();\nlet want = ShardLimits { max_count: 20, max_tokens: 900 };\nassert_eq!(p.profile(None).unwrap().shards, Some(want));\n```",
      "properties": {
        "max_count": {
          "description": "The most files the pack may hold, the index included.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "max_tokens": {
          "description": "The most tokens one file of the pack may hold, counted with `o200k_base`.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "max_count",
        "max_tokens"
      ],
      "type": "object"
    },
    "ShardPlan": {
      "description": "One planned shard: a Markdown file of the pack, the paths it carries from first to last,\nand what it weighs in bytes and in tokens.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, ShardPlan};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet planned = plan(&root, &share, None);\nlet first: &ShardPlan = &planned.plan.shards[0];\nassert_eq!((first.files, first.first.as_str(), first.last.as_str()), (1, \"main.rs\", \"main.rs\"));\nassert!(first.file.ends_with(\".md\") && first.tokens > 0);\n```",
      "properties": {
        "bytes": {
          "description": "The bytes of the content it carries.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "file": {
          "description": "The file name inside the pack.",
          "type": "string"
        },
        "files": {
          "description": "How many files it carries.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "first": {
          "description": "The first path it carries.",
          "type": "string"
        },
        "last": {
          "description": "The last path it carries.",
          "type": "string"
        },
        "tokens": {
          "description": "The tokens of the blocks it carries.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "file",
        "files",
        "first",
        "last",
        "bytes",
        "tokens"
      ],
      "type": "object"
    }
  },
  "description": "The plan of one pack: what it carries, what it leaves out and why, how it is cut into\nshards, and whether it may be built.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, PackPlan};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet p: PackPlan = plan(&root, &share, None).plan;\nassert!(p.measured && p.passes && p.index_matches_head);\nassert_eq!((p.tracked, p.selected), (2, 1));\nassert_eq!(p.dropped[\"binary\"], 1);\n// an unknown profile is not measured, and not measured is never a pass\nlet p: PackPlan = plan(&root, &share, Some(\"nope\")).plan;\nassert!(!p.measured && !p.passes);\n```",
  "properties": {
    "bytes": {
      "description": "The bytes of the content carried.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "commit": {
      "description": "The commit `HEAD` names; the content is the index's, which equals it when\n`index_matches_head` is true.",
      "type": [
        "string",
        "null"
      ]
    },
    "dropped": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "How many files were left out, by reason.",
      "type": "object"
    },
    "dropped_files": {
      "description": "Every file left out for a reason other than `derived`.",
      "items": {
        "$ref": "#/$defs/DroppedFile"
      },
      "type": "array"
    },
    "findings": {
      "description": "Every reason the pack cannot be built. Empty is the passing answer.",
      "items": {
        "$ref": "#/$defs/PackFinding"
      },
      "type": "array"
    },
    "index_matches_head": {
      "description": "Whether the index holds exactly what `HEAD` holds. `false` means staged changes\ntravel with the pack under a commit id that does not contain them.",
      "type": "boolean"
    },
    "limits": {
      "anyOf": [
        {
          "$ref": "#/$defs/ShardLimits"
        },
        {
          "type": "null"
        }
      ],
      "description": "The limits applied."
    },
    "measured": {
      "description": "Whether the tree could be read at all. `false` is not a pass.",
      "type": "boolean"
    },
    "passes": {
      "description": "`true` when the tree was measured and nothing was found.",
      "type": "boolean"
    },
    "profile": {
      "description": "The profile planned.",
      "type": "string"
    },
    "reason": {
      "description": "Why it could not, when it could not.",
      "type": [
        "string",
        "null"
      ]
    },
    "selected": {
      "description": "How many the pack carries.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "shards": {
      "description": "The shards, in order; the index is not one of them.",
      "items": {
        "$ref": "#/$defs/ShardPlan"
      },
      "type": "array"
    },
    "tokenizer": {
      "description": "The tokenizer the counts are in.",
      "type": "string"
    },
    "tokens": {
      "description": "The tokens of the content carried, in `o200k_base`.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "tracked": {
      "description": "How many files the index tracks.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "measured",
    "profile",
    "index_matches_head",
    "tracked",
    "selected",
    "bytes",
    "tokens",
    "tokenizer",
    "dropped",
    "dropped_files",
    "shards",
    "findings",
    "passes"
  ],
  "title": "PackPlan",
  "type": "object"
}

Politiky

benchmark: povinné — cíl na každém transportu, který expozice deklaruje; případy jsou ty ze vstupního typu
cache: vypnuto — každé volání spustí handler

Cíle benchmarku

Odvozeno z registru pro tento repozitář: jeden požadavek na transport a případy, které poskytuje typ vstupu. Celá matice je na stránce měření výkonu.

transport	state	případy	targets
direct	pokryto	2	default-profile chatgpt
mcp	pokryto	2	default-profile chatgpt
http	pokryto	2	default-profile chatgpt