@skillctl/registry 0.2.0

package/dist/registry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Registry Manager + Sources for PR4.
+ *
+ * Supports: github, local (file:), skills.sh (shorthand alias), basic npm.
+ * Full resolution, materialize to canonical store, integrity (sha256 tree).
+ * Integrates with manifest/lock from PR3 (load/save, makeLockEntry).
+ *
+ * npm resolution algorithm (per design Issue 4 / appendix):
+ * 1. Parse spec → pkg, versionRange (supports npm:pkg, npm:pkg@ver, npm:@scope/pkg@^range).
+ * 2. Resolve best version: query registry.npmjs.org for versions, use semver to pick maxSatisfying (or 'latest' if no range).
+ * 3. Fetch package metadata for the version; get dist.tarball and dist.shasum (or integrity).
+ * 4. Download tarball (https), verify npm tarball shasum (sha1 for shasum field; note modern npm uses sha512 in integrity, we support both for basic).
+ * 5. Extract tarball to temp dir (using 'tar' pkg).
+ * 6. Locate skill dir inside extracted:
+ *    - package.json "agentSkills" field? (string | string[] paths) or "skills" field.
+ *    - or conventional ./skills/ subdir (if contains SKILL.md)
+ *    - or root if SKILL.md present at top
+ *    - fallback: glob ** /SKILL.md limited depth (1-2), pick first containing one.
+ * 7. From located skill dir: parse SKILL.md frontmatter for 'name' (canonicalize to lower-hyphen), validate basic.
+ * 8. Materialize: atomic copy of the skill dir contents to canonical/<name>/ (or the dir itself), compute tree sha256 integrity via core.
+ * 9. Record provenance: {type: 'npm', tarballHash: 'sha1:xxx' or npm integrity, subpath? }
+ *    Also store resolved tarball info in resolved string.
+ * 10. Update lock with makeLockEntry + save; optionally update manifest.
+ *
+ * GitHub/local/skills.sh similar: resolve to (url/ref/subpath), fetch/extract/copy to temp, locate skill (prefer subpath or find SKILL.md), materialize, sha256 tree.
+ * Shorthands in resolve (e.g. owner/repo mapped to github:).
+ *
+ * Checksum (integrity) always written to lock entry.
+ *
+ * Uses core: loadConfig (for store), computeDirIntegrity, ensureDir, writeFileAtomic (indirect).
+ * No adapters. Basic add only.
+ *
+ * Sources implement (extend core RegistrySource for MVP):
+ */
+import type { RegistrySource, ResolvedSource, LockfileEntry } from '@skillctl/core';
+export interface ResolvedSourceInternal extends ResolvedSource {
+    tarballUrl?: string;
+    tarballHash?: string;
+    gitUrl?: string;
+    ref?: string;
+    subpath?: string;
+    localPath?: string;
+    originalSpec: string;
+}
+export declare function parseSkillFrontmatter(skillDir: string): {
+    name?: string;
+    description?: string;
+};
+export declare function parseSkillFrontmatterAsync(skillDir: string): Promise<{
+    name?: string;
+    description?: string;
+}>;
+export declare function canonicalizeName(raw: string): string;
+export declare class LocalSource implements RegistrySource {
+    readonly id = "local";
+    match(spec: string): boolean;
+    resolve(spec: string, options?: {
+        ref?: string;
+    }): Promise<ResolvedSource>;
+    fetch(resolved: ResolvedSource, dest: string): Promise<{
+        integrity: string;
+    }>;
+}
+export declare class GitHubSource implements RegistrySource {
+    readonly id = "github";
+    match(spec: string): boolean;
+    resolve(spec: string, options?: {
+        ref?: string;
+    }): Promise<ResolvedSource>;
+    fetch(resolved: ResolvedSource, dest: string): Promise<{
+        integrity: string;
+    }>;
+    private locateSkillDir;
+}
+export declare class SkillsShSource implements RegistrySource {
+    readonly id = "skills.sh";
+    match(spec: string): boolean;
+    resolve(spec: string, options?: {
+        ref?: string;
+    }): Promise<ResolvedSource>;
+    fetch(resolved: ResolvedSource, dest: string): Promise<{
+        integrity: string;
+    }>;
+}
+/**
+ * NpmSource - basic npm support.
+ * See class comments for full documented algorithm.
+ */
+export declare class NpmSource implements RegistrySource {
+    readonly id = "npm";
+    match(spec: string): boolean;
+    resolve(spec: string, options?: {
+        ref?: string;
+    }): Promise<ResolvedSource>;
+    fetch(resolved: ResolvedSource, dest: string): Promise<{
+        integrity: string;
+    }>;
+    /**
+     * Locate skill dir logic per design:
+     * 1. package.json "agentSkills" or "skills" field (string or array of paths relative)
+     * 2. conventional ./skills/<name> or root ./skills/
+     * 3. root if SKILL.md
+     * 4. limited glob ** /SKILL.md (depth limited)
+     */
+    private locateNpmSkillDir;
+}
+export declare class RegistryManager {
+    private sources;
+    constructor();
+    register(source: RegistrySource): void;
+    private registerDefaultSources;
+    resolve(spec: string, options?: {
+        ref?: string;
+    }): Promise<ResolvedSourceInternal>;
+    /**
+     * Materialize resolved source to canonical store.
+     * Returns final canonicalPath + tree integrity.
+     * Uses atomic-ish: copy to .tmp then rename.
+     */
+    materialize(resolved: ResolvedSourceInternal, options?: {
+        name?: string;
+    }): Promise<{
+        canonicalPath: string;
+        integrity: string;
+        sourceType: string;
+    }>;
+    /**
+     * Basic `add` : parse spec, resolve, materialize to canonical, update lock (and manifest if present).
+     * Returns the created/updated LockfileEntry.
+     * Integrates manifest/lock per PR3/4 spec.
+     */
+    add(spec: string, opts?: {
+        cwd?: string;
+        updateManifest?: boolean;
+    }): Promise<LockfileEntry>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}