1use std::collections::BTreeSet;
10use std::path::Path;
11
12use include_dir::{Dir, include_dir};
13
14pub use crate::payload_roots::PAYLOAD_ROOTS;
15
16pub static SPECS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/_docs/specs");
21pub static TEMPLATES: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/templates");
23pub static INSTANCE: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/instance");
30pub static METHOD: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/method");
32pub static SKILLS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skills");
34pub static SKILL_SHARED: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skill-shared");
36pub static COMPARISON_DOCS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/comparison-docs");
38pub static PRIOR_ART: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/reference/prior-art");
40pub static TRACKER_MARKUP: Dir<'static> =
42 include_dir!("$CARGO_MANIFEST_DIR/reference/tracker-markup");
43
44pub static LICENSE: &str = include_str!("../LICENSE");
46pub static LICENSE_MIT: &str = include_str!("../LICENSE-MIT");
48pub static LICENSE_CC_BY: &str = include_str!("../LICENSE-CC-BY-4.0");
50pub static THIRD_PARTY_NOTICES: &str = include_str!("../THIRD_PARTY_NOTICES.md");
52pub static CHANGELOG: &str = include_str!("../CHANGELOG.md");
54
55const EMBEDDED_ROOTS: &[(&str, &Dir<'static>)] = &[
61 ("_docs/specs", &SPECS),
62 ("templates", &TEMPLATES),
63 ("instance", &INSTANCE),
64 ("method", &METHOD),
65 ("skills", &SKILLS),
66 ("skill-shared", &SKILL_SHARED),
67 ("comparison-docs", &COMPARISON_DOCS),
68 ("reference/prior-art", &PRIOR_ART),
69 ("reference/tracker-markup", &TRACKER_MARKUP),
70];
71
72const EMBEDDED_FILES: &[(&str, &[u8])] = &[];
78
79pub const PAYLOAD_DIR: &str = "instance/payload";
83
84static EMPTY: Dir<'static> = Dir::new("", &[]);
86
87#[must_use]
89pub fn payload_specs() -> &'static Dir<'static> {
90 INSTANCE.get_dir("payload/_docs/specs").unwrap_or(&EMPTY)
91}
92
93#[must_use]
96pub fn spec_files() -> Vec<(&'static str, &'static include_dir::File<'static>)> {
97 let named = |dir: &'static Dir<'static>| {
98 dir.files()
99 .filter_map(|file| {
100 let name = file.path().file_name()?.to_str()?;
101 Some((name, file))
102 })
103 .collect::<Vec<_>>()
104 };
105 let mut files = named(payload_specs());
106 for (name, file) in named(&SPECS) {
107 if !files.iter().any(|(held, _)| *held == name) {
108 files.push((name, file));
109 }
110 }
111 files.sort_by(|left, right| left.0.cmp(right.0));
112 files
113}
114
115#[must_use]
120pub const fn roots() -> &'static [(&'static str, &'static Dir<'static>)] {
121 EMBEDDED_ROOTS
122}
123
124#[must_use]
126pub fn skill_names() -> Vec<&'static str> {
127 let mut names: Vec<&'static str> = SKILLS
128 .dirs()
129 .filter_map(|dir| dir.path().as_os_str().to_str())
130 .collect();
131 names.sort_unstable();
132 names
133}
134
135#[must_use]
137pub fn skill(name: &str) -> Option<&'static str> {
138 SKILLS
139 .get_file(format!("{name}/SKILL.md"))
140 .and_then(include_dir::File::contents_utf8)
141}
142
143#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
145pub enum PackageError {
146 #[error("the payload carries no skill named {0}")]
148 Unknown(String),
149 #[error(
151 "{skill}: {path} is claimed by the skill and by the shared source; author it once (skill-format:shared-content-is-authored-once)"
152 )]
153 Collision {
154 skill: String,
156 path: String,
158 },
159 #[error(
161 "{skill}: {path} is neither SKILL.md nor a file under references/ (skill-format:a-package-holds-the-manual-and-its-references)"
162 )]
163 Unlisted {
164 skill: String,
166 path: String,
168 },
169}
170
171pub fn skill_package(name: &str) -> Result<Vec<(String, &'static [u8])>, PackageError> {
186 let dir = SKILLS
187 .get_dir(name)
188 .ok_or_else(|| PackageError::Unknown(name.to_string()))?;
189 compose_package(name, dir, &SKILL_SHARED)
190}
191
192#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct SkillFile {
195 pub source: String,
197 pub destination: String,
199 pub bytes: &'static [u8],
201}
202
203pub fn skill_inventory() -> Result<Vec<SkillFile>, PackageError> {
216 use crate::domain::paths::SKILL_REFERENCES_DIR;
217
218 let mut out = Vec::new();
219 for root in SKILL_ROOTS {
220 for name in skill_names() {
221 for (relative, bytes) in skill_package(name)? {
222 let own = format!("skills/{name}/{relative}");
223 let source = if asset(&own).is_some() {
224 own
225 } else {
226 let shared = relative
227 .strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
228 .unwrap_or(&relative);
229 format!("skill-shared/{shared}")
230 };
231 out.push(SkillFile {
232 source,
233 destination: format!("{root}/{name}/{relative}"),
234 bytes,
235 });
236 }
237 }
238 }
239 Ok(out)
240}
241
242pub const SKILL_ROOTS: [&str; 2] = [
244 crate::domain::paths::CLAUDE_ROOT,
245 crate::domain::paths::AGENTS_ROOT,
246];
247
248#[must_use]
250pub fn skill_package_folders() -> Vec<String> {
251 SKILL_ROOTS
252 .iter()
253 .flat_map(|root| {
254 skill_names()
255 .into_iter()
256 .map(move |name| format!("{root}/{name}"))
257 })
258 .collect()
259}
260
261pub fn compose_package(
275 name: &str,
276 skill: &'static Dir<'static>,
277 shared: &'static Dir<'static>,
278) -> Result<Vec<(String, &'static [u8])>, PackageError> {
279 use crate::domain::paths::{SKILL_FILE, SKILL_REFERENCES_DIR};
280
281 let mut files = Vec::new();
282 for (relative, bytes) in files_relative_to(skill) {
283 let allowed = relative == SKILL_FILE
284 || relative
285 .strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
286 .is_some_and(|file| !file.is_empty() && !file.contains('/'));
287 if !allowed {
288 return Err(PackageError::Unlisted {
289 skill: name.to_string(),
290 path: relative,
291 });
292 }
293 files.push((relative, bytes));
294 }
295 if !files.iter().any(|(path, _)| path == SKILL_FILE) {
296 return Err(PackageError::Unknown(name.to_string()));
297 }
298 for (path, bytes) in files_relative_to(shared) {
299 let relative = format!("{SKILL_REFERENCES_DIR}/{path}");
300 if files.iter().any(|(claimed, _)| *claimed == relative) {
301 return Err(PackageError::Collision {
302 skill: name.to_string(),
303 path: relative,
304 });
305 }
306 files.push((relative, bytes));
307 }
308 files.sort_by(|left, right| left.0.cmp(&right.0));
309 Ok(files)
310}
311
312fn files_relative_to(dir: &'static Dir<'static>) -> Vec<(String, &'static [u8])> {
314 fn walk(base: &Path, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
315 for file in dir.files() {
316 let relative = file
317 .path()
318 .strip_prefix(base)
319 .unwrap_or_else(|_| file.path());
320 if let Some(relative) = relative.to_str() {
321 out.push((relative.to_string(), file.contents()));
322 }
323 }
324 for sub in dir.dirs() {
325 walk(base, sub, out);
326 }
327 }
328 let mut out = Vec::new();
329 walk(dir.path(), dir, &mut out);
330 out
331}
332
333#[must_use]
340pub fn shared_artifacts() -> Vec<(String, &'static [u8])> {
341 let mut out = files_relative_to(&SKILL_SHARED);
342 out.sort_by(|a, b| a.0.cmp(&b.0));
343 out
344}
345
346#[must_use]
349pub fn asset(source: &str) -> Option<&'static [u8]> {
350 EMBEDDED_FILES
351 .iter()
352 .find_map(|(path, bytes)| (*path == source).then_some(*bytes))
353 .or_else(|| {
354 EMBEDDED_ROOTS.iter().find_map(|(root, dir)| {
355 let rest = source.strip_prefix(root)?.strip_prefix('/')?;
356 dir.get_file(rest).map(include_dir::File::contents)
357 })
358 })
359}
360
361#[must_use]
366pub fn assets_under(root: &str) -> Vec<(String, &'static [u8])> {
367 if let Some((path, bytes)) = EMBEDDED_FILES.iter().find(|(path, _)| *path == root) {
368 return vec![((*path).to_string(), *bytes)];
369 }
370 let Some((name, dir)) = EMBEDDED_ROOTS.iter().find(|(name, _)| *name == root) else {
371 return Vec::new();
372 };
373 let mut out = Vec::new();
374 collect_under(name, dir, &mut out);
375 out.sort_by(|a, b| a.0.cmp(&b.0));
376 out
377}
378
379fn collect_under(root: &str, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
380 for file in dir.files() {
381 if let Some(rest) = file.path().to_str() {
382 out.push((format!("{root}/{rest}"), file.contents()));
383 }
384 }
385 for sub in dir.dirs() {
386 collect_under(root, sub, out);
387 }
388}
389
390#[must_use]
392pub fn spec_rule_ids() -> BTreeSet<String> {
393 let mut ids = BTreeSet::new();
394 for (_, file) in spec_files() {
395 let Some(text) = file.contents_utf8() else {
396 continue;
397 };
398 ids.extend(rule_ids_in(text));
399 }
400 ids
401}
402
403pub fn spec_texts() -> impl Iterator<Item = &'static str> {
405 spec_files()
406 .into_iter()
407 .filter_map(|(_, file)| file.contents_utf8())
408}
409
410pub fn rule_ids_in(text: &str) -> impl Iterator<Item = String> + '_ {
412 text.lines().filter_map(|line| {
413 let candidate = line.strip_prefix("### `")?;
414 let (id, _) = candidate.split_once('`')?;
415 let (domain, rule) = id.split_once(':')?;
416 let is_slug = |part: &str| {
417 !part.is_empty()
418 && part
419 .bytes()
420 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
421 };
422 (is_slug(domain) && is_slug(rule)).then(|| id.to_string())
423 })
424}
425
426#[cfg(test)]
427mod tests {
428 use super::*;
429 use crate::domain::profile::ProfileId;
430 use crate::domain::rule_id::RuleId;
431
432 #[test]
433 fn rule_id_enum_matches_the_embedded_specs() {
434 let from_specs = spec_rule_ids();
435 let from_enum: BTreeSet<String> = RuleId::ALL
436 .iter()
437 .map(|rule| rule.as_str().to_string())
438 .collect();
439 assert_eq!(
440 from_specs, from_enum,
441 "RuleId and the specs disagree; update the enum and the specs together"
442 );
443 }
444
445 #[test]
446 fn the_embedded_roots_are_the_declared_payload_roots() {
447 let mut embedded: Vec<&str> = EMBEDDED_ROOTS
448 .iter()
449 .map(|(root, _)| *root)
450 .chain(EMBEDDED_FILES.iter().map(|(path, _)| *path))
451 .collect();
452 embedded.sort_unstable();
453 let mut declared = PAYLOAD_ROOTS.to_vec();
454 declared.sort_unstable();
455 assert_eq!(
456 embedded, declared,
457 "payload_roots.rs and the embedded statics disagree; a root missing from the declaration ships unscanned"
458 );
459 }
460
461 #[test]
462 fn a_single_file_root_resolves_through_both_readers() {
463 for (path, bytes) in EMBEDDED_FILES {
464 assert_eq!(asset(path), Some(*bytes), "{path}");
465 assert_eq!(assets_under(path), vec![((*path).to_string(), *bytes)]);
466 }
467 assert!(asset("instance/payload/_docs/.markdownlint-cli2.jsonc/x").is_none());
468 }
469
470 #[test]
471 fn every_profile_projection_resolves_to_an_embedded_asset() {
472 for id in [ProfileId::Codebase, ProfileId::KnowledgeBase] {
473 let profile = id.profile();
474 for entry in profile.managed.iter().chain(profile.adopted) {
475 assert!(
476 asset(&entry.source).is_some(),
477 "{id}: {} is not embedded",
478 entry.source
479 );
480 }
481 }
482 }
483
484 #[test]
485 fn the_method_and_licenses_are_carried() {
486 assert!(METHOD.get_file("glossary.md").is_some());
487 assert!(METHOD.files().count() >= 15);
488 assert!(LICENSE.contains("LICENSE-MIT") && LICENSE.contains("LICENSE-CC-BY-4.0"));
489 }
490
491 use include_dir::{DirEntry, File};
492
493 static SHARED: Dir<'static> = Dir::new(
494 "",
495 &[DirEntry::File(File::new("plan-gate.md", b"shared gate"))],
496 );
497 static OWN_REFERENCE: Dir<'static> = Dir::new(
498 "demo",
499 &[
500 DirEntry::File(File::new("demo/SKILL.md", b"manual")),
501 DirEntry::Dir(Dir::new(
502 "demo/references",
503 &[DirEntry::File(File::new(
504 "demo/references/land.md",
505 b"task",
506 ))],
507 )),
508 ],
509 );
510 static CLAIMED_TWICE: Dir<'static> = Dir::new(
511 "demo",
512 &[
513 DirEntry::File(File::new("demo/SKILL.md", b"manual")),
514 DirEntry::Dir(Dir::new(
515 "demo/references",
516 &[DirEntry::File(File::new(
517 "demo/references/plan-gate.md",
518 b"a copy",
519 ))],
520 )),
521 ],
522 );
523 static UNLISTED: Dir<'static> = Dir::new(
524 "demo",
525 &[
526 DirEntry::File(File::new("demo/SKILL.md", b"manual")),
527 DirEntry::Dir(Dir::new(
528 "demo/scripts",
529 &[DirEntry::File(File::new("demo/scripts/check.sh", b"echo"))],
530 )),
531 ],
532 );
533
534 #[test]
536 fn a_skill_reference_lands_beside_the_shared_artifacts() {
537 let package = compose_package("demo", &OWN_REFERENCE, &SHARED).unwrap();
538 let paths: Vec<&str> = package.iter().map(|(path, _)| path.as_str()).collect();
539 assert_eq!(
540 paths,
541 ["SKILL.md", "references/land.md", "references/plan-gate.md"]
542 );
543 }
544
545 #[test]
547 fn a_name_both_sources_claim_fails_the_package() {
548 let error = compose_package("demo", &CLAIMED_TWICE, &SHARED).unwrap_err();
549 assert_eq!(
550 error,
551 PackageError::Collision {
552 skill: "demo".to_string(),
553 path: "references/plan-gate.md".to_string(),
554 }
555 );
556 assert!(
557 error
558 .to_string()
559 .contains("skill-format:shared-content-is-authored-once")
560 );
561 }
562
563 #[test]
565 fn a_file_outside_the_allowlist_fails_the_package() {
566 let error = compose_package("demo", &UNLISTED, &SHARED).unwrap_err();
567 assert_eq!(
568 error,
569 PackageError::Unlisted {
570 skill: "demo".to_string(),
571 path: "scripts/check.sh".to_string(),
572 }
573 );
574 }
575
576 #[test]
577 fn a_name_the_payload_lacks_is_unknown() {
578 assert_eq!(
579 skill_package("no-such-skill"),
580 Err(PackageError::Unknown("no-such-skill".to_string()))
581 );
582 }
583
584 #[test]
585 fn rule_id_parser_matches_heading_shape_only() {
586 let text = "### `a-b:c-d` — Title\n### `Bad:Id`\nplain ### `x:y`\n### `no-colon`\n";
587 let ids: Vec<String> = rule_ids_in(text).collect();
588 assert_eq!(ids, vec!["a-b:c-d".to_string()]);
589 }
590}