capsium 0.1.1 → 0.2.0

data/lib/capsium.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "capsium/version"
-require "shale"
-require "shale/adapter/nokogiri"
-Shale.xml_adapter = Shale::Adapter::Nokogiri
-
 module Capsium
   class Error < StandardError; end
 
-  # Your code goes here...
+  autoload :VERSION, "capsium/version"
+  autoload :Cli, "capsium/cli"
+  autoload :Converters, "capsium/converters"
+  autoload :Package, "capsium/package"
+  autoload :Packager, "capsium/packager"
+  autoload :Reactor, "capsium/reactor"
+  autoload :ThorExt, "capsium/thor_ext"
 end
-
-require_relative "capsium/package"
-require_relative "capsium/packager"

data/sig/capsium/package/dataset.rbs

@@ -0,0 +1,28 @@
+module Capsium
+  class Package
+    # A loaded dataset. "source"/"schemaFile"/"databaseFile" are
+    # package-relative paths resolved against the package directory.
+    class Dataset
+      attr_reader name: String
+      attr_reader config: DatasetConfig
+      attr_reader data: untyped
+      attr_reader package_path: String
+
+      def initialize: (name: String name, config: DatasetConfig config,
+                       package_path: String package_path) -> void
+
+      def source_path: () -> String
+
+      def schema_path: () -> String?
+
+      def load_data: () -> untyped
+
+      def validate: () -> bool
+
+      # File-existence and schema validations; empty when valid.
+      def validation_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+    end
+  end
+end

data/sig/capsium/package/manifest.rbs

@@ -0,0 +1,34 @@
+module Capsium
+  class Package
+    # Loads, generates and writes manifest.json (ARCHITECTURE.md
+    # section 3).
+    class Manifest
+      attr_reader path: String
+      attr_reader content_path: String
+      attr_reader config: ManifestConfig
+
+      def initialize: (String path) -> void
+
+      # Auto-generation: scan content/ recursively, detect MIME types,
+      # default visibility "exported", deterministic (sorted) output.
+      def generate_manifest: () -> Hash[String, Resource]
+
+      def resources: () -> Hash[String, Resource]
+
+      def lookup: (String path) -> Resource?
+
+      def type_for: (String path) -> String?
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      def path_to_content_file: (String path) -> Pathname
+
+      def content_file_exists?: (String path) -> bool
+
+      def relative_path: (String path) -> String
+    end
+  end
+end

data/sig/capsium/package/manifest_config.rbs

@@ -0,0 +1,38 @@
+module Capsium
+  class Package
+    # A single manifest resource entry (ARCHITECTURE.md section 3).
+    class Resource
+      VISIBILITIES: Array[String]
+
+      attr_accessor type: String?
+      attr_accessor visibility: String
+      attr_accessor version: String?
+
+      def initialize: (?type: String? type, ?visibility: String? visibility,
+                       ?version: String? version) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical manifest.json model: an object keyed by package-relative
+    # resource path. The legacy array form is normalized on read;
+    # writers emit only the object form.
+    class ManifestConfig
+      attr_accessor resources: Hash[String, Resource]
+
+      def initialize: (?resources: Hash[String, Resource] resources) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def resources_from_json: (ManifestConfig model, untyped value) -> void
+
+      def resources_to_json: (ManifestConfig model, Hash[String, untyped] doc) -> void
+
+      def sort!: () -> ManifestConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/metadata.rbs

@@ -0,0 +1,26 @@
+module Capsium
+  class Package
+    # Loads and writes metadata.json; field access is delegated to the
+    # wrapped MetadataData config (ARCHITECTURE.md section 2).
+    class Metadata
+      attr_reader path: String
+      attr_reader config: MetadataData
+
+      def initialize: (String path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+      def name: () -> String?
+      def version: () -> String?
+      def description: () -> String?
+      def guid: () -> String?
+      def uuid: () -> String?
+      def author: () -> String?
+      def license: () -> String?
+      def repository: () -> Repository?
+      def dependencies: () -> Hash[String, String]
+    end
+  end
+end

data/sig/capsium/package/metadata_config.rbs

@@ -0,0 +1,49 @@
+module Capsium
+  class Package
+    # The repository object of metadata.json.
+    class Repository
+      attr_accessor type: String?
+      attr_accessor url: String?
+
+      def initialize: (?type: String? type, ?url: String? url) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical metadata.json model (ARCHITECTURE.md section 2). The
+    # legacy array form of "dependencies" is normalized on read; writers
+    # emit only the object form.
+    class MetadataData
+      KEBAB_CASE_PATTERN: Regexp
+      SEMVER_PATTERN: Regexp
+      UUID_PATTERN: Regexp
+
+      attr_accessor name: String?
+      attr_accessor version: String?
+      attr_accessor description: String?
+      attr_accessor guid: String?
+      attr_accessor uuid: String?
+      attr_accessor author: String?
+      attr_accessor license: String?
+      attr_accessor repository: Repository?
+      attr_accessor dependencies: Hash[String, String]
+      attr_accessor read_only: bool?
+
+      def initialize: (?name: String? name, ?version: String? version,
+                       ?description: String? description, ?guid: String? guid,
+                       ?uuid: String? uuid, ?author: String? author,
+                       ?license: String? license, ?repository: Repository? repository,
+                       ?dependencies: Hash[String, String] dependencies,
+                       ?read_only: bool? read_only) -> void
+
+      def self.from_json: (String json) -> instance
+
+      # Field-level format validations; empty when valid.
+      def format_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/routes.rbs

@@ -0,0 +1,37 @@
+module Capsium
+  class Package
+    # Loads, generates and writes routes.json (ARCHITECTURE.md
+    # section 4).
+    class Routes
+      INDEX_ROUTE: String
+      INDEX_RESOURCE: String
+      DATASET_ROUTE_PREFIX: String
+
+      attr_reader path: String
+      attr_reader config: RoutesConfig
+      attr_reader manifest: Manifest
+      attr_reader storage: Storage
+
+      def initialize: (String path, Manifest manifest, Storage storage) -> void
+
+      def resolve: (String url_path) -> Route?
+
+      def add_route: (String route, String target) -> Route
+
+      def update_route: (String route, String updated_route, String updated_target) -> Route
+
+      def remove_route: (String route) -> Array[Route]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      # Auto-generation (ARCHITECTURE.md section 4): every manifest
+      # resource gets a route at its path relative to content/; HTML
+      # files get two routes; the index HTML additionally gets "/";
+      # every dataset gets /api/v1/data/<id>. Deterministic output.
+      def generate_routes: () -> RoutesConfig
+    end
+  end
+end

data/sig/capsium/package/routes_config.rbs

@@ -0,0 +1,74 @@
+module Capsium
+  class Package
+    # A single route entry (ARCHITECTURE.md section 4). Kinds are
+    # discriminated by key, MECE: static file, dataset route, or dynamic
+    # handler (accepted-and-ignored; reactors respond 501).
+    class Route
+      DATASET_PATH_PREFIX: String
+
+      attr_accessor path: String?
+      attr_accessor resource: String?
+      attr_accessor headers: Hash[String, String]?
+      attr_accessor headers_file: String?
+      attr_accessor visibility: String
+      attr_accessor dataset: String?
+      attr_accessor access_control: Hash[String, untyped]?
+      attr_accessor http_method: String?
+      attr_accessor handler: String?
+
+      def initialize: (?path: String? path, ?resource: String? resource,
+                       ?headers: Hash[String, String]? headers,
+                       ?headers_file: String? headers_file,
+                       ?visibility: String? visibility, ?dataset: String? dataset,
+                       ?access_control: Hash[String, untyped]? access_control,
+                       ?http_method: String? http_method,
+                       ?handler: String? handler) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def kind: () -> (:resource | :dataset | :handler)
+
+      def dataset_route?: () -> bool
+
+      def handler_route?: () -> bool
+
+      def fs_path: (String package_path) -> String?
+
+      def mime: (Manifest manifest) -> String?
+
+      def validate_target: (String package_path, Storage storage) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical routes.json model: optional top-level "index" plus a
+    # "routes" array. The legacy object/target form is normalized on
+    # read; writers emit only the canonical form.
+    class RoutesConfig
+      attr_accessor index: String?
+      attr_accessor routes: Array[Route]
+
+      def initialize: (?index: String? index, ?routes: Array[Route] routes) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def routes_from_json: (RoutesConfig model, untyped value) -> void
+
+      def routes_to_json: (RoutesConfig model, Hash[String, untyped] doc) -> void
+
+      def resolve: (String path) -> Route?
+
+      def add: (String path, String target) -> Route
+
+      def update: (String path, String updated_path, String updated_target) -> Route
+
+      def remove: (String path) -> Array[Route]
+
+      def sort!: () -> RoutesConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/security.rbs

@@ -0,0 +1,65 @@
+module Capsium
+  class Package
+    # Loads, generates and verifies security.json (ARCHITECTURE.md
+    # section 6). Checksums cover every file in the package except
+    # security.json itself.
+    class Security
+      class IntegrityError < Capsium::Error
+      end
+
+      # A file whose SHA-256 does not match the recorded checksum.
+      class ChecksumMismatch
+        attr_reader path: String
+        attr_reader expected: String
+        attr_reader actual: String
+
+        def initialize: (path: String path, expected: String expected, actual: String actual) -> void
+
+        def message: () -> String
+      end
+
+      # A checksum listed for a file that is missing on disk.
+      class MissingFile
+        attr_reader path: String
+        attr_reader expected: String
+
+        def initialize: (path: String path, expected: String expected) -> void
+
+        def message: () -> String
+      end
+
+      # A file on disk not covered by any checksum.
+      class UncheckedFile
+        attr_reader path: String
+
+        def initialize: (path: String path) -> void
+
+        def message: () -> String
+      end
+
+      attr_reader path: String
+      attr_reader config: SecurityConfig?
+
+      def initialize: (String path, ?SecurityConfig? config) -> void
+
+      def self.generate: (String package_path) -> Security
+
+      def self.checksums_for: (String package_path) -> Hash[String, String]
+
+      def self.package_files: (String package_path) -> Array[String]
+
+      def present?: () -> bool
+
+      def checksums: () -> Hash[String, String]
+
+      def verify: (String package_path) -> Array[ChecksumMismatch | MissingFile | UncheckedFile]
+
+      def verify!: (String package_path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/security_config.rbs

@@ -0,0 +1,57 @@
+module Capsium
+  class Package
+    # The "integrityChecks" object of security.json: SHA-256 checksums
+    # keyed by package-relative path.
+    class IntegrityChecks
+      ALGORITHMS: Array[String]
+
+      attr_accessor checksum_algorithm: String
+      attr_accessor checksums: Hash[String, String]
+
+      def initialize: (?checksum_algorithm: String? checksum_algorithm,
+                       ?checksums: Hash[String, String] checksums) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "digitalSignatures" object of security.json (parsed only;
+    # signing is a later phase).
+    class DigitalSignatures
+      attr_accessor public_key: String?
+      attr_accessor signature_file: String?
+
+      def initialize: (?public_key: String? public_key,
+                       ?signature_file: String? signature_file) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "security" object of security.json.
+    class SecurityData
+      attr_accessor integrity_checks: IntegrityChecks?
+      attr_accessor digital_signatures: DigitalSignatures?
+
+      def initialize: (?integrity_checks: IntegrityChecks? integrity_checks,
+                       ?digital_signatures: DigitalSignatures? digital_signatures) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical security.json model (generated at pack time).
+    class SecurityConfig
+      attr_accessor security: SecurityData?
+
+      def initialize: (?security: SecurityData? security) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def checksums: () -> Hash[String, String]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/storage.rbs

@@ -0,0 +1,28 @@
+module Capsium
+  class Package
+    # Loads and writes storage.json and instantiates its datasets
+    # (ARCHITECTURE.md section 5).
+    class Storage
+      attr_reader path: String
+      attr_reader config: StorageConfig
+      attr_reader datasets: Array[Dataset]
+
+      def initialize: (String path) -> void
+
+      def data_sets: () -> Hash[String, DatasetConfig]
+
+      def load_datasets: () -> Array[Dataset]
+
+      def dataset: (String name) -> Dataset?
+
+      def dataset_names: () -> Array[String]
+
+      def empty?: () -> bool
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/storage_config.rbs

@@ -0,0 +1,61 @@
+module Capsium
+  class Package
+    # A single dataset entry (ARCHITECTURE.md section 5): schema-backed
+    # file (via "source") or SQLite ("databaseFile" + "table").
+    class DatasetConfig
+      FORMATS: Hash[String, String]
+      SCHEMA_TYPES: Array[String]
+
+      attr_accessor source: String?
+      attr_accessor schema_file: String?
+      attr_accessor schema_type: String?
+      attr_accessor database_file: String?
+      attr_accessor table: String?
+
+      def initialize: (?source: String? source, ?schema_file: String? schema_file,
+                       ?schema_type: String? schema_type,
+                       ?database_file: String? database_file,
+                       ?table: String? table) -> void
+
+      def format: () -> String
+
+      def sqlite?: () -> bool
+
+      def backing_file: () -> String
+
+      def to_dataset: (String name, String package_path) -> Dataset
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "storage" object holding the dataSets map.
+    class StorageData
+      attr_accessor data_sets: Hash[String, DatasetConfig]
+
+      def initialize: (?data_sets: Hash[String, DatasetConfig] data_sets) -> void
+
+      def data_sets_from_json: (StorageData model, untyped value) -> void
+
+      def data_sets_to_json: (StorageData model, Hash[String, untyped] doc) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical storage.json model. The legacy array form is normalized
+    # on read; writers emit only the canonical form.
+    class StorageConfig
+      attr_accessor storage: StorageData?
+
+      def initialize: (?storage: StorageData? storage) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def data_sets: () -> Hash[String, DatasetConfig]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/validator.rbs

@@ -0,0 +1,29 @@
+module Capsium
+  class Package
+    # Validates a package directory or .cap file against the canonical
+    # schemas (ARCHITECTURE.md sections 2-6) and reports one result per
+    # check. Used by `capsium package validate`.
+    class Validator
+      EXTERNAL_REFERENCE_PATTERN: Regexp
+      TEXT_CONTENT_MIME: Regexp
+
+      # One named validation check with its problems; ok when messages
+      # is empty.
+      class CheckResult
+        attr_reader name: String
+        attr_reader ok: bool
+        attr_reader messages: Array[String]
+
+        def initialize: (name: String name, ok: bool ok, messages: Array[String] messages) -> void
+
+        def ok?: () -> bool
+      end
+
+      def initialize: (String package_path) -> void
+
+      def run: () -> Array[CheckResult]
+
+      def valid?: () -> bool
+    end
+  end
+end

data/sig/capsium/package.rbs

@@ -0,0 +1,53 @@
+module Capsium
+  # A Capsium package loaded from a directory or a .cap file
+  # (ARCHITECTURE.md section 1).
+  class Package
+    MANIFEST_FILE: String
+    METADATA_FILE: String
+    STORAGE_FILE: String
+    ROUTES_FILE: String
+    SECURITY_FILE: String
+    CONTENT_DIR: String
+    DATA_DIR: String
+
+    attr_reader name: String
+    attr_reader path: String
+    attr_reader manifest: Manifest
+    attr_reader metadata: Metadata
+    attr_reader routes: Routes
+    attr_reader storage: Storage
+    attr_reader security: Security
+    attr_reader load_type: Symbol
+
+    def initialize: (String | Pathname path, ?load_type: Symbol? load_type) -> void
+
+    def prepare_package: (Pathname path) -> (String | Pathname)
+
+    def solidify: () -> void
+
+    def decompress_cap_file: (String | Pathname file_path) -> String
+
+    def load_package: () -> void
+
+    # Removes the temporary extraction directory of a .cap-loaded
+    # package; a no-op for directory loads.
+    def cleanup: () -> void
+
+    def datasets: () -> Array[Dataset]
+
+    # The .cap file this package was loaded from, or nil when loaded
+    # from a directory.
+    def cap_file_path: () -> String?
+
+    def content_files: () -> Array[String]
+
+    def determine_load_type: (String | Pathname path) -> Symbol
+
+    # Verifies the package against security.json (ARCHITECTURE.md
+    # section 6). Returns a list of typed errors; empty when no
+    # security.json is present or all checksums match.
+    def verify_integrity: () -> Array[Security::ChecksumMismatch | Security::MissingFile | Security::UncheckedFile]
+
+    def verify_integrity!: () -> void
+  end
+end

data/sig/capsium/packager.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  # Packs a package directory into a .cap file (generating
+  # security.json) and unpacks .cap files with zip-slip protection.
+  class Packager
+    class FileAlreadyExistsError < StandardError
+    end
+
+    # Raised when a .cap archive contains an entry whose name would be
+    # written outside the destination directory (zip-slip).
+    class UnsafeEntryError < Capsium::Error
+    end
+
+    DRIVE_LETTER_PATTERN: Regexp
+
+    def pack: (Package package, ?Hash[Symbol, untyped] options) -> String
+
+    def unpack: (String cap_file_path, String destination) -> void
+
+    def compress_package: (Package package, String cap_file) -> void
+
+    def relative_path_current: (String absolute_path) -> String
+  end
+end

data/sig/capsium/reactor/introspection.rbs

@@ -0,0 +1,31 @@
+module Capsium
+  class Reactor
+    # Monitoring HTTP API reports for the package this reactor serves
+    # (ARCHITECTURE.md section 7).
+    class Introspection
+      METADATA_PATH: String
+      ROUTES_PATH: String
+      CONTENT_HASHES_PATH: String
+      CONTENT_VALIDITY_PATH: String
+      PATHS: Array[String]
+
+      attr_reader package: Package
+
+      def initialize: (Package package) -> void
+
+      def endpoint?: (String path) -> bool
+
+      # The report body for an introspection endpoint, or nil when the
+      # path is not an introspection endpoint.
+      def report_for: (String path) -> Hash[Symbol, untyped]?
+
+      def metadata_report: () -> Hash[Symbol, untyped]
+
+      def routes_report: () -> Hash[Symbol, untyped]
+
+      def content_hashes_report: () -> Hash[Symbol, untyped]
+
+      def content_validity_report: () -> Hash[Symbol, untyped]
+    end
+  end
+end