App-karr

 view release on metacpan or  search on metacpan

lib/App/karr/Role/SkillFile.pm  view on Meta::CPAN

# above was split out of; left in place it would brief an agent twice, once
# with the old text.
sub _retired_skill_names { qw( kanban-issues-karr-cli ) }

# One bundled skill directory. Two places to look, in order: File::ShareDir,
# which is where share/ lands when the dist is installed, and -- when it is
# not, i.e. a checkout being run with -Ilib -- share/ in that checkout. A
# share dir that answers but holds no NAME/SKILL.md (an App::karr from before
# #285, which shipped one claude-skill.md, or one from before the split, which
# shipped only kanban-issues-karr-cli/, is exactly that) falls through to the
# checkout rather than counting as found. Looked up per skill, so every name
# answers from wherever it is actually found.
#
# The second half has to know where that checkout is, and the only thing that
# knows is a file of the dist Perl has already loaded. Cmd::Skill and Cmd::Init
# each asked %INC for their own ($INC{'App/karr/Cmd/Skill.pm'} against
# $INC{'App/karr/Cmd/Init.pm'}), and that one line was the whole difference
# between their two copies of this sub (ticket #146). Naming either command's
# file from here would be the wrong fix twice over: it answers for one caller
# and sends the other silently on to the die below, and since MooX::Cmd decides
# which command classes get loaded, whether the miss happens would depend on how
# karr was invoked rather than showing up the first time. This file is the
# honest anchor instead. It belongs to the same dist as the share/ being looked
# for, it cannot fail to be loaded while one of its own methods is running, and
# it sits at the same depth below lib/ as the two command classes, so the climb
# is the one both copies made.
sub _skill_source_dir {
  my ($self, $name) = @_;

  # Installed dist: File::ShareDir knows where share/ went.
  my $installed = eval {
    my $dir = Path::Tiny::path( File::ShareDir::dist_dir('App-karr') )
                        ->child($name);
    $dir->child('SKILL.md')->exists ? $dir : undef;
  };
  return $installed if $installed;

  # Not installed: the share/ of the tree this file came out of.
  my $own_path = $INC{$OWN_INC_KEY};
  if ($own_path) {
    my $share = Path::Tiny::path($own_path)->parent($DIST_ROOT_UP)
                                           ->child( 'share', $name );
    return $share if $share->child('SKILL.md')->exists;
  }

  die "Could not find $name/SKILL.md. Is App::karr properly installed?\n";
}

# One bundled skill's SKILL.md, as characters (slurp_utf8 is Path::Tiny's own
# character-level read, which is what the file edge is allowed to use; decoding
# on top of it would be the double decode App::karr::Encoding forbids). This is
# what `karr skill show` prints: the entry point, not the references behind it.
sub _skill_content {
  my ($self, $name) = @_;
  return $self->_skill_source_dir($name)->child('SKILL.md')->slurp_utf8;
}

# Every file one skill ships, as (relative path => characters) pairs in sorted
# path order: SKILL.md, then references/*.md. Walked from the directory rather
# than listed, so a reference file added under share/ ships without anyone
# touching this role; only *.md counts, so an editor backup next to them never
# lands in someone's .claude. The relative path is what the writers below
# rejoin to a target directory, so the layout under share/ IS the layout a
# target gets. Read with slurp_utf8 for the reason given on _skill_content.
sub _skill_files {
  my ($self, $name) = @_;
  my $dir = $self->_skill_source_dir($name);
  my @found;
  $dir->visit(
    sub { my ($p) = @_; push @found, $p if $p->is_file && $p->basename =~ /\.md\z/ },
    { recurse => 1 },
  );
  return map  { ( $_ => $dir->child($_)->slurp_utf8 ) }
         sort map { $_->relative($dir)->stringify } @found;
}

# The retired skill directories present under $base -- the directory that
# holds the skill directories (.claude/skills, ~/.codex/skills, ...) -- as
# Path::Tiny objects. This is what check reports as stale. A dangling symlink
# by that name counts too: it is a leftover all the same.
sub _retired_skill_dirs {
  my ($self, $base) = @_;
  return grep { -e "$_" || -l "$_" }
         map  { $base->child($_) } $self->_retired_skill_names;
}

# Removes every retired skill directory under $base and returns the ones it
# removed, for the caller to report. File::Path unlinks a symlink rather than
# following it, and a file that is one link of a hardlink chain loses only
# this project's link, so another project still sharing the old skill keeps
# its copy. A failure is the target's layout, not a karr bug: one clean line
# naming the directory, like the write (#77). remove_tree reports some
# failures only as warnings, so what counts is whether the path is gone.
sub _remove_retired_skills {
  my ($self, $base) = @_;
  my @removed;
  for my $dir ( $self->_retired_skill_dirs($base) ) {
    my $error;
    eval {
      local $SIG{__WARN__} = sub { $error //= $_[0] };
      $dir->remove_tree( { safe => 0 } );
      1;
    } or $error = $@;
    App::karr::Error::user_error( "Could not remove $dir: ",
                                  App::karr::Error::clean_error( $error // 'still there' ) )
      if -e "$dir" || -l "$dir";
    push @removed, $dir;
  }
  return @removed;
}

# Written in place, on purpose. Path::Tiny's spew_utf8 writes a temp file and
# renames it over the target, so the path it wrote comes back on a *new* inode.
# For a SKILL.md that is the wrong move: skill files are kept as hardlink
# chains (manage-skills), one inode behind the same relative path in dozens of
# projects, so the rename silently breaks the updated path out of its chain --
# that one path gets the new text, every other project keeps the old inode with
# the old text, and the link count drops with nothing said (ticket #142, found
# in kubernetes-ocp, where the workaround was `karr skill show` into a shell
# redirect; ticket #145 for the same call left standing in `karr init
# --claude-skill`, which is why this lives in a role instead of in one command).



( run in 1.003 second using v1.01-cache-2.11-cpan-99fa8243a42 )