jAh,dZddlZddlZddlZddlZddlZddlmZmZddlm Z m Z ddl m Z m Z mZddlmZddlmZmZmZddlmZejeZe Zed z Zed z Zd e fd Zd e fd Zd eeeffdZ deeeffdZ!de ded efdZ"de d eeee ffdZ#de de d e fdZ$de d efdZ%de de d efdZ&de d eefdZ'de d efdZ(d eeeeee fffdZ)de d e d efd!Z*d"d#d$ed%e+d e,fd&Z-dBd'e+d eefd(Z.dBd'e+d e,fd)Z/dBd$ed%e+d e,fd*Z0ed+krWe1d,e/d"-Z2e3e2d.d/e3e2d0d1e2d2d3gZ4e2d4rne2d4Z5d5Z6d67e5de6Z8e3e5e6kre8d7e3e5e6z d8z Z8e49e3e5d9e8e2d:r'e49e3e2d:d;e2:d<r'e49e3e2d<d=e1d>d67e4d?e2d@dAdSdS)Cu Skills Sync -- Manifest-based seeding and updating of bundled skills. Copies bundled skills from the repo's skills/ directory into ~/.hermes/skills/ and uses a manifest to track which skills have been synced and their origin hash. Manifest format (v2): each line is "skill_name:origin_hash" where origin_hash is the MD5 of the bundled skill at the time it was last synced to the user dir. Old v1 manifests (plain names without hashes) are auto-migrated. Update logic: - NEW skills (not in manifest): copied to user dir, origin hash recorded. - EXISTING skills (in manifest, present in user dir): * If user copy matches origin hash: user hasn't modified it → safe to update from bundled if bundled changed. New origin hash recorded. * If user copy differs from origin hash: user customized it → SKIP. - DELETED by user (in manifest, absent from user dir): respected, not re-added. - REMOVED from bundled (in manifest, gone from repo): cleaned from manifest. The manifest lives at ~/.hermes/skills/.bundled_manifest. N)datetimetimezone)Path PurePosixPath)get_bundled_skills_dirget_hermes_homeget_optional_skills_dir)is_excluded_skill_path)DictListTuple)atomic_replaceskillsz.bundled_manifestreturnc^tttjjdz S)zLocate the bundled skills/ directory. Checks HERMES_BUNDLED_SKILLS env var first (set by Nix wrapper), then a wheel-installed data dir, then falls back to the relative path from this source file. r)rr__file__parent0/usr/local/lib/hermes-agent/tools/skills_sync.py_get_bundled_dirr,s# "$x.."7">"I J JJrc^tttjjdz S)z/Locate the official optional-skills/ directory.optional-skills)r rrrrrr_get_optional_dirr6s" "4>>#8#?BS#S T TTrctsiS i}tdD]e}|}|sd|vrC|d\}}}|||<`d||<f|S#t tf$ricYSwxYw)z Read the manifest as a dict of {skill_name: origin_hash}. Handles both v1 (plain names) and v2 (name:hash) formats. v1 entries get an empty hash string which triggers migration on next sync. utf-8encoding:) MANIFEST_FILEexists read_text splitlinesstrip partitionOSErrorIOError)resultlinename_hash_vals r_read_manifestr.;s    ! ! !++W+==HHJJ " "D::<z"_write_manifest.._s4XXndH))x))XXXXXXrz.bundled_manifest_.tmpdirprefixsuffixwrrz&Failed to write skills manifest %s: %s)exc_info)tempfiler!rmkdirjoinsorteditemsmkstempstrosfdopenwriteflushfsyncfilenor BaseExceptionunlinkr' Exceptionloggerdebug)r/r?datafdtmp_pathfes r_write_manifestrVVs OOOtd;;; 99XXw}}@W@WXXX X X[_ _D`''M())'(  H 2sW555 %  $$$ % % % % % % % % % % % % % % % 8] 3 3 3 3 3     (####        ``` =}aZ^ _________`ss(2E%D02AD D0DD0DD00 E";EE" EE"EE""E%% F/#FFskill_mdfallbackc |dddd}n#t$r|cYSwxYwd}|dD]}|}|dkr|rnbd }#|r\|d rG|d d d d }|r|cS|S)zORead the name field from SKILL.md YAML frontmatter, falling back to *fallback*.rreplace)rerrorsNiFr4z---Tzname:rz"')r#r'splitr% startswith)rWrXcontentin_frontmatterr*strippedvalues r_read_skill_namercws$$gi$HH$O N d##  ::<< u   !N   h11':: NN3**1-3355;;EBBE  Os " 11 bundled_dircg}|s|S|dD]E}t|r|j}t ||j}|||fF|S)zz Find all SKILL.md files in the bundled directory. Returns list of (skill_name, skill_directory_path) tuples. SKILL.md)r"rglobr rrcr+append)rdrrW skill_dir skill_names r_discover_bundled_skillsrks F      %%j11// !( + +  O %h ??  z9-.... Mrric@||}t|z S)z Compute the destination path in SKILLS_DIR preserving the category structure. e.g., bundled/skills/mlops/axolotl -> ~/.hermes/skills/mlops/axolotl ) relative_to SKILLS_DIR)rirdrels r_compute_relative_destrps"    , ,C  r directoryctj} t|dD]}|rq||}|t|d|| n#ttf$rYnwxYw| S)zHCompute a hash of all file contents in a directory for change detection.*r) hashlibmd5rBrgis_filermupdaterEencode read_bytesr'r( hexdigest)rqhasherfpathros r _dir_hashr}s []]F IOOC0011 2 2E}} 2'' 22 c#hhoog66777 e..00111  2 W          sB*CCCpathbasec@||}|}t|}d|jD}|s|rt d|Drt d|d|S)zLReturn a normalized relative POSIX path, rejecting traversal/absolute paths.cg|]}|dv| S)>r .rr6parts r z*_safe_rel_install_path..s" B B BdD ,A,AT,A,A,Arc3"K|] }|dkV dS)z..Nrrs rr7z)_safe_rel_install_path..s&-M-Mtddl-M-M-M-M-M-MrzUnsafe optional skill path: /)rmas_posixrparts is_absoluteany ValueErrorrA)r~rroposixpurers r_safe_rel_install_pathrs   4 C LLNNE   D B Bdj B B BE AA#-M-Mu-M-M-M*M*MA???@@@ 88E??rcg}t|dD]P}|r:|||Q|S)z8List files inside a skill directory in lock-file format.rs)rBrgrvrhrmr)rifilesr|s r_skill_file_listrsoE ,,--BB ==?? B LL**955>>@@ A A A Lrcd ddlm}||S#t$rt|cYSwxYw)zJReturn the same hash style the skills hub lock uses, falling back locally.r) content_hash)tools.skills_guardrrNr})rqrs r _content_hashrsZ$333333|I&&& $$$#####$s //cZt}i}|s|St|dD]a}t |r|j} t ||}n#t$rY7wxYw|j}t||}|||f}|||<|||<b|S)a%Return official optional skills keyed by folder name and frontmatter name. Values are ``(folder_name, install_path, source_dir)``. Multiple keys may point to the same skill so callers can accept either the folder slug used by the hub lock or the user-facing frontmatter name. rf) rr"rBrgr rrrr+rc) optional_dirindexrWsrc install_path folder_namefrontmatter_namerbs r_optional_skill_indexrs%&&L.0E     <--j99:: ( ( !( + +  o 1#|DDLL    H h +HkBBlC0"k"' Ls#A44 BB backup_rootc6|t}||z }|jdd|rd}||jd|r6|dz }||jd|6||jd|}tjt|t|| S)zLMove an existing skill directory into a restore backup, preserving rel path.Tr1r\-) rmrnrr@r" with_namer+shutilmoverEr)r~rrotargetr<s r_move_to_restore_backuprs    : & &C 3 F Mt444 }}=&+888899@@BB  aKF&+888899@@BB !!V[";";6";";<< KD 3v;;''' <<>>rF)restorer+rct}|sddgggdS|dvr1tt|dng}|s%||}| dd|gggdS|g}g}g}t jtj d }td z d |z }|D]\} } } tt| d z } t| } | ot| | k}t| d z | }g}trttd D]}t#|r|j} |tn#t($rYAwxYwt||j}|| kra|j| ks|| |hvr|||r|D]9}|r#|t/||:| r%|s#|t/| || sF| jddt3j| | || |st7d}dd||||rt9|nddS)a3Restore one or all official optional skills from repo source. ``restore=False`` only performs exact-match provenance backfill. ``restore=True`` repairs already-mutated/reorganized skills by backing up matching active copies and copying the official optional source into its canonical path. Fz,No official optional skills directory found.)okmessagerestored backfilled backed_up>rsallc|dS)Nr\r)items rz1restore_official_optional_skill.. s 47r)keyNz#Official optional skill not found: z %Y%m%d-%H%M%Sz.restore-backupszofficial-optional-rrfTr1quietz(Official optional skill repair complete.r )rrrrr backup_dir)rrBsetvaluesgetrnowrutcstrftimernrr]r}r"rcrgr rrmrr+rhrr@rcopytree_backfill_optional_provenancerE)r+rrtargetsrrr timestamprrrrdestsrc_hash canonical_oksrc_frontmattermatchesrW candidatecandidate_namematchrs rrestore_official_optional_skillrs " # #E K(VdfvxHJKK KGK|G[G[fS((.B.BCCCCacG 4 >,XRV,X,XfhxzJLMM M(HI X\**33ODDI114T4T4TTK*1##& \3D,"4"4S"9"9::S>>{{}}D4H)D +3+;[II       .":#3#3J#?#?@@ . .)(33$O ))*5555!H!1(IN!K!K$$>[00N{TcFd4d4dNN9---    R R<<>>R$$%>>T*** ,,,   /T:::J= *3;c+&&&   sF)) F65F6rc <t}|sgStdz dz } |r&tj|ndid}n!#tjtf$rdid}YnwxYw|di}d| D}g}d}t| dD]}}t|r|j } t| |} n3#t$r&} t d | | Yd } ~ Wd } ~ wwxYwtt%| d z } | r| st+| t+| kr| j} | |vs| |vrt/jt2j}d d | ddt9| | t;| ddi||d || <|| || d}|stAd| d|r,|j !dddd l"}tj#|dddz}|$tK|j dd\}} tMj'|dd 5}|(||)tMj*|+d d d n #1swxYwYtY||n5#tZ$r( tMj.|n#t$rYnwxYwwxYw|S)!aMark already-present official optional skills as hub-installed. This covers the migration case where a skill used to be bundled (or was manually copied into the active skills tree) and later lives under optional-skills/. If the active copy is byte-identical to the official optional source, record official hub provenance without copying or reinstalling anything. Modified/local skills are left alone. z.hubz lock.jsonr\)version installedrcbh|],}t|t|d-S)r) isinstancedictr)r6entrys r z0_backfill_optional_provenance..YsD  eT " " .!!rFrfz/Skipping optional skill with unsafe path %s: %sNrofficialz official/builtinrbackfilled_fromr) source identifier trust_level scan_verdictrrrmetadata installed_at updated_atTz = z* (official optional provenance backfilled)r1r)indent ensure_asciir4z.lock_r8r9r=rr)/rr"rnjsonloadsr#JSONDecodeErrorr' setdefaultrrBrgr rrrrOrPrr]is_dirr}r+rrrr isoformatrraddrhprintr@r?dumpsrDrErFrGrHrIrJrKrrLrM)rr lock_pathrQrexisting_pathsrchangedrWrrrUr lock_namerr?payloadrRrSrTs rrrFsZ%&&L     V#k1I/4=4D4D4F4Fktz)--//000XYhjLkLk  ' *///2../ R00I%%''N JG<--j99::$P$P !( + +  o 1#|DDLL    LLJCQR S S S HHHH D,"4"4S"9"9::{{}} DKKMM   T??inn , , H  ! !\^%C%C L..88::  4l44$()$//(%d++*,=>%# ) <((()$$$ P NNNN O O Otd;;; *T!%@@@4G''I$%%(  H 2sW555 %    $$$ % % % % % % % % % % % % % % % 8Y / / / /     (####        s~?A33BB D E $EE M'/AM ? M' MM'MM'' N2NN NNNNc t}|s ggdggdgdStddt }t |}d|D}g}g}g}d}|D]\} } t | |} t| } | |vr | r7|dz }t| | kr| || <nx|std| d| d n_| j ddtj | | | | | || <|std | #ttf$r"} |std | d | Yd } ~ d } ~ wwxYw| r|| d}t| }|s||| <|| kr|dz }n|dz }_||kr,| | |std| d| |krF | d}tjt%| t%| tj | | | || <| | |std| dtj|dnm#ttf$rY|rC| s/tjt%|t%| wxYw#ttf$r"} |std| d | Yd } ~ d } ~ wwxYw|dz }|dz }t)t+||z }|D]}||=|dD]}||}t|z }|sm |j ddtj||h#ttf$r&} t4d|| Yd } ~ d } ~ wwxYwt9|t;|}|||||t=||dS)z Sync bundled skills into ~/.hermes/skills/ using the manifest. Returns: dict with keys: copied (list), updated (list), skipped (int), user_modified (list), cleaned (list), total_bundled (int) r)copiedupdatedskipped user_modifiedcleaned total_bundledoptional_provenance_backfilledTr1ch|]\}}|Srr)r6r+r,s rrzsync_skills..s888gdAT888rr\u ⚠ uw: bundled version shipped but you already have a local skill by this name — yours was kept. Run `hermes skills reset z)` to replace it with the bundled version.z + z ! Failed to copy : Nr z ~ z (user-modified, skipping)z.baku ↑ z (updated)) ignore_errorsz ! Failed to update zDESCRIPTION.mdzCould not copy %s: %sr)rr"rnr@r.rkrpr}rrrrrhr'r(r with_suffixrrErmtreerBrkeysrgrmcopy2rOrPrVrlen)rrdmanifestbundled_skills bundled_namesrrrrrj skill_srcr bundled_hashrU origin_hash user_hashbackuprr+desc_mdro dest_descrs r sync_skillsrs#$$K      RAB.0   TD111H-k::N88888M FGMG!/YY I%i== ++ X % % C;;==3qLG ,66/;,,"GZGGBLGGGK%%dT%BBBOIt444MM*---+7HZ( 31Z11222W% C C CCA AAaAABBB C [[]]2 ",,z266K!$I (1$ ,,qLGGqLGK''$$Z000IGGGGHHH{**I!--f55FKD 3v;;777  4888/;,z222$C!"A:"A"A"ABBB fDAAAAA#W-!==??@4;;==@"KF SYY??? B  )III IGjGGAGGHHHI1  qLGGS))M9::G TNN$$%566BB!!+..$ !! B B &&td&CCC Wi0000W% B B B 4gqAAAAAAAA B  BH%B%O%O%O"&^,,*H  sd&B*EF"E??FAL$AJ54L$5A*LL$$M5MM,1PQ/QQc <t}t}t|}t|}||v}||v}|s |s ddd|dddS|r||=t |d}|r}|s ddd|dddSt |||} | rF tj| d }n.#ttf$r} dd d |d | d | ddcYd} ~ Sd} ~ wwxYwtd } |r |r d} d|d} n|r d} d|d} nd } d |d} d | | | dS)u; Reset a bundled skill's manifest tracking so future syncs work normally. When a user edits a bundled skill, subsequent syncs mark it as ``user_modified`` and skip it forever — even if the user later copies the bundled version back into place, because the manifest still holds the *old* origin hash. This function breaks that loop. Args: name: The skill name (matches the manifest key / skill frontmatter name). restore: If True, also delete the user's copy in SKILLS_DIR and let the next sync re-copy the current bundled version. If False (default), only clear the manifest entry — the user's current copy is preserved but future updates work again. Returns: dict with keys: - ok: bool, whether the reset succeeded - action: one of "manifest_cleared", "restored", "not_in_manifest", "bundled_missing" - message: human-readable description - synced: dict from sync_skills() if a sync was triggered, else None Fnot_in_manifest'zi' is not a tracked bundled skill. Nothing to reset. (Hub-installed skills use `hermes skills uninstall`.)N)ractionrsyncedbundled_missingup' has no bundled source — manifest entry cleared but cannot restore from bundled (skill was removed upstream).Tmanifest_clearedzCleared manifest entry for 'z$' but could not delete user copy at rrrz Restored 'z' from bundled source.z/' (no prior user copy, re-copied from bundled).zf'. Future `hermes update` runs will re-baseline against your current copy and accept upstream changes.) r.rrkrrVrpr"rrr'r(r)r+rrrdrbundled_by_name in_manifest is_bundleddeleted_user_copyrrUr r rs rreset_bundled_skillr6sL0H"$$K-k::N>**O("K(J   z  'IDIII   " TN!!! +UUUU &od&;[II ;;==   d###$(!!W%   0;t;;/3;;78;;# t $ $ $F  $  ;t;;;   TtTTT# W4 W W W  &W O OOs"B99C$ CC$C$__main__z1Syncing bundled skills into ~/.hermes/skills/ ...rrz newrz updatedrz unchangedrz, z, +z morez user-modified (kept): rz cleaned from manifestrz official optional backfilledz Done: z. rz total bundled.)F);__doc__rtrloggingrFrrrpathlibrrhermes_constantsrrr agent.skill_utilsr typingr r r utilsr getLogger__name__rO HERMES_HOMErnr!rrrEr.rVrcrkrpr}rrrrrboolrrrrrrr)rrnamesMAX_SHOWrAshownrhrrrrr#s,  '''''''''''''''']]]]]]]]]]444444$$$$$$$$$$  8 $ $o 8 # 00 K$KKKKU4UUUU S#X6`T#s(^````Btss*$4c4i8H3I&d$  #    Tcc $T $c $ $ $ $tCsC~)>$>?6 $ T c    CHDDD#D4DDDDDDNZZZ$s)ZZZZzPPtPPPPPf_P_Pc_PD_PT_P_P_P_PD z E =>>> [u % % %F 3vh &&& 3vi ! !+++ ) ((( E oD' %  *++ 3u:: 733u::0777 7E E BB5BBCCC iH F9-..FFFGGG zz233f F#CDEEdddeee E QTYYu%% Q Q)@ Q Q QRRRRR'r