Class: AgentsSkillVault::Resource

Inherits:
Object
  • Object
show all
Defined in:
lib/agents_skill_vault/resource.rb

Overview

Represents a GitHub resource tracked in the vault.

A Resource can be a full repository, a folder within a repository, or a single file. It tracks metadata like the source URL, local path, and sync timestamps.

Examples:

Create a repository resource

resource = Resource.new(
  label: "user/repo",
  url: "https://github.com/user/repo",
  username: "user",
  repo: "repo",
  type: :repo,
  storage_path: "/path/to/vault"
)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(label:, url:, username:, repo:, type:, storage_path:, folder: nil, branch: nil, relative_path: nil, added_at: nil, synced_at: nil, **validation_attrs) ⇒ Resource

Creates a new Resource instance.

Parameters:

  • label (String) —

    Unique identifier for this resource

  • url (String) —

    GitHub URL of the repository

  • username (String) —

    GitHub username/organization

  • repo (String) —

    Repository name

  • type (Symbol) —

    Resource type (:repo, :folder, or :file)

  • storage_path (String, nil) —

    Base path for local storage

  • folder (String, nil) (defaults to: nil) —

    Folder name for non-repo resources

  • branch (String, nil) (defaults to: nil) —

    Git branch (defaults to "main")

  • relative_path (String, nil) (defaults to: nil) —

    Path relative to repository root

  • added_at (Time, nil) (defaults to: nil) —

    When added (defaults to now)

  • synced_at (Time, nil) (defaults to: nil) —

    When last synced (defaults to now)

  • validation_attrs (Hash) —

    Validation-related attributes

Options Hash (**validation_attrs):

  • :validation_status (Symbol) —

    Validation status (default: :unvalidated)

  • :validation_errors (Array) —

    Validation errors (default: [])

  • :skill_name (String) —

    The name of the skill (default: nil)

  • :is_skill (Boolean) —

    Whether this is a skill (default: derived from skill_name)



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/agents_skill_vault/resource.rb', line 87

def initialize(label:, url:, username:, repo:, type:, storage_path:, folder: nil, branch: nil,
               relative_path: nil, added_at: nil, synced_at: nil, **validation_attrs)
  @label = label
  @url = url
  @username = username
  @repo = repo
  @folder = folder
  @type = type
  @branch = branch || "main"
  @relative_path = relative_path
  @added_at = added_at || Time.now
  @synced_at = synced_at || Time.now
  @storage_path = storage_path
  @validation_status = validation_attrs.fetch(:validation_status, :unvalidated)
  @validation_errors = validation_attrs.fetch(:validation_errors, [])
  @skill_name = validation_attrs[:skill_name]
  @is_skill = validation_attrs.fetch(:is_skill, !@skill_name.nil?)
end

Instance Attribute Details

#added_at ⇒ Time (readonly)

Returns When the resource was added to the vault.

Returns:

  • (Time) —

    When the resource was added to the vault



48
49
50
 
# File 'lib/agents_skill_vault/resource.rb', line 48

def added_at
  @added_at
end

#branch ⇒ String (readonly)

Returns Git branch name.

Returns:

  • (String) —

    Git branch name



42
43
44
 
# File 'lib/agents_skill_vault/resource.rb', line 42

def branch
  @branch
end

#folder ⇒ String? (readonly)

Returns Folder name for folder/file resources.

Returns:

  • (String, nil) —

    Folder name for folder/file resources



36
37
38
 
# File 'lib/agents_skill_vault/resource.rb', line 36

def folder
  @folder
end

#is_skill ⇒ Boolean (readonly)

Returns Whether this resource is a skill.

Returns:

  • (Boolean) —

    Whether this resource is a skill



66
67
68
 
# File 'lib/agents_skill_vault/resource.rb', line 66

def is_skill
  @is_skill
end

#label ⇒ String (readonly)

Returns Unique identifier for this resource in the vault.

Returns:

  • (String) —

    Unique identifier for this resource in the vault



24
25
26
 
# File 'lib/agents_skill_vault/resource.rb', line 24

def label
  @label
end

#relative_path ⇒ String? (readonly)

Returns Path relative to repository root (for folder/file resources).

Returns:

  • (String, nil) —

    Path relative to repository root (for folder/file resources)



45
46
47
 
# File 'lib/agents_skill_vault/resource.rb', line 45

def relative_path
  @relative_path
end

#repo ⇒ String (readonly)

Returns Name of the repository.

Returns:

  • (String) —

    Name of the repository



33
34
35
 
# File 'lib/agents_skill_vault/resource.rb', line 33

def repo
  @repo
end

#skill_name ⇒ String? (readonly)

Returns The name of the skill (nil for non-skill resources).

Returns:

  • (String, nil) —

    The name of the skill (nil for non-skill resources)



63
64
65
 
# File 'lib/agents_skill_vault/resource.rb', line 63

def skill_name
  @skill_name
end

#storage_path ⇒ String? (readonly)

Returns Base path where resources are stored.

Returns:

  • (String, nil) —

    Base path where resources are stored



54
55
56
 
# File 'lib/agents_skill_vault/resource.rb', line 54

def storage_path
  @storage_path
end

#synced_at ⇒ Time (readonly)

Returns When the resource was last synced.

Returns:

  • (Time) —

    When the resource was last synced



51
52
53
 
# File 'lib/agents_skill_vault/resource.rb', line 51

def synced_at
  @synced_at
end

#type ⇒ Symbol (readonly)

Returns Type of resource (:repo, :folder, or :file).

Returns:

  • (Symbol) —

    Type of resource (:repo, :folder, or :file)



39
40
41
 
# File 'lib/agents_skill_vault/resource.rb', line 39

def type
  @type
end

#url ⇒ String (readonly)

Returns GitHub URL of the repository.

Returns:

  • (String) —

    GitHub URL of the repository



27
28
29
 
# File 'lib/agents_skill_vault/resource.rb', line 27

def url
  @url
end

#username ⇒ String (readonly)

Returns GitHub username/organization that owns the repository.

Returns:

  • (String) —

    GitHub username/organization that owns the repository



30
31
32
 
# File 'lib/agents_skill_vault/resource.rb', line 30

def username
  @username
end

#validation_errors ⇒ Array<String> (readonly)

Returns Validation errors (for invalid skills).

Returns:

  • (Array<String>) —

    Validation errors (for invalid skills)



60
61
62
 
# File 'lib/agents_skill_vault/resource.rb', line 60

def validation_errors
  @validation_errors
end

#validation_status ⇒ Symbol (readonly)

Returns Validation status (:valid_skill, :invalid_skill, :not_a_skill, :unvalidated).

Returns:

  • (Symbol) —

    Validation status (:valid_skill, :invalid_skill, :not_a_skill, :unvalidated)



57
58
59
 
# File 'lib/agents_skill_vault/resource.rb', line 57

def validation_status
  @validation_status
end

Class Method Details

.from_h(hash, storage_path: nil) ⇒ Resource

Creates a Resource from a hash.

Supports both symbol and string keys for compatibility with different JSON parsing options.

Examples:

Resource.from_h({ label: "user/repo", ... }, storage_path: "/vault")

Parameters:

  • hash (Hash) —

    Resource attributes as a hash

  • storage_path (String, nil) (defaults to: nil) —

    Base path for local storage

Returns:

  • (Resource) —

    A new Resource instance



182
183
184
 
# File 'lib/agents_skill_vault/resource.rb', line 182

def self.from_h(hash, storage_path: nil)
  new(**extract_core_attrs(hash), **extract_validation_attrs(hash), storage_path:)
end

.parse_time(time_value) ⇒ Time?

Parses a time value from various formats.

Parameters:

  • time_value (String, Time, nil) —

    The time value to parse

Returns:

  • (Time, nil) —

    Parsed Time object, or nil if input was nil

Raises:

  • (ArgumentError) —

    if time_value is not a valid type



239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/agents_skill_vault/resource.rb', line 239

def self.parse_time(time_value)
  case time_value
  when nil
    nil
  when String
    Time.iso8601(time_value)
  when Time
    time_value
  else
    raise ArgumentError, "Invalid time value: #{time_value.inspect}"
  end
end

Instance Method Details

#==(other) ⇒ Boolean

Compares two resources for equality.

Two resources are equal if they have the same label, URL, username, repo, folder, type, branch, and relative_path.

Parameters:

  • other (Object) —

    The object to compare with

Returns:

  • (Boolean) —

    true if resources are equal



155
156
157
158
159
 
# File 'lib/agents_skill_vault/resource.rb', line 155

def ==(other)
  return false unless other.is_a?(Resource)

  equality_attributes.all? { |attr| public_send(attr) == other.public_send(attr) }
end

#equality_attributes ⇒ Array<Symbol>

Returns list of attributes used for equality comparison.

Returns:

  • (Array<Symbol>) —

    Attribute names to compare



165
166
167
168
 
# File 'lib/agents_skill_vault/resource.rb', line 165

def equality_attributes
  i[label url username repo folder type branch relative_path
     validation_status validation_errors skill_name is_skill]
end

#local_path ⇒ String?

Returns the local filesystem path where the resource is stored.

Examples:

resource.local_path
# => "/path/to/vault/user/repo"

Returns:

  • (String, nil) —

    Absolute path to the resource, or nil if no storage_path



114
115
116
117
118
119
120
121
122
 
# File 'lib/agents_skill_vault/resource.rb', line 114

def local_path
  return nil unless storage_path

  if type == :repo
    File.join(storage_path, username, repo)
  else
    File.join(storage_path, username, repo, relative_path || folder || "")
  end
end

#to_h ⇒ Hash

Converts the resource to a hash for serialization.

Returns:

  • (Hash) —

    Resource attributes as a hash



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/agents_skill_vault/resource.rb', line 128

def to_h
  {
    label: label,
    url: url,
    username: username,
    repo: repo,
    folder: folder,
    type: type,
    branch: branch,
    relative_path: relative_path,
    added_at: added_at.iso8601,
    synced_at: synced_at.iso8601,
    validation_status: validation_status,
    validation_errors: validation_errors,
    skill_name: skill_name,
    is_skill: is_skill
  }
end