@hasna/skills 0.1.43 → 0.1.45

package/dist/lib/cli-mcp-parity.d.ts

@@ -0,0 +1,14 @@
+export type SkillsCliMcpParityDomain = "discovery" | "portable-skills" | "runtime" | "validation";
+export interface SkillsCliMcpParityEntry {
+    domain: SkillsCliMcpParityDomain;
+    operation: string;
+    cliCommands: string[];
+    mcpTools: string[];
+    jsonContracts: string[];
+    status: "matched" | "intentional-gap";
+    notes?: string;
+}
+export declare const SKILLS_CLI_MCP_PARITY: SkillsCliMcpParityEntry[];
+export declare function validateSkillsCliMcpParity(): string[];
+export declare function findSkillsParityForCliCommand(command: string): SkillsCliMcpParityEntry | undefined;
+export declare function findSkillsParityForMcpTool(tool: string): SkillsCliMcpParityEntry | undefined;

package/dist/lib/mcp-contracts.d.ts

@@ -15,7 +15,7 @@ export interface JsonSchemaObject {
     additionalProperties?: boolean | JsonSchemaObject;
     oneOf?: JsonSchemaObject[];
 }
-export type McpToolCategory = "agent-session" | "discovery" | "execution" | "feedback" | "metadata" | "pinning" | "scheduling" | "validation";
+export type McpToolCategory = "agent-session" | "discovery" | "execution" | "feedback" | "metadata" | "pinning" | "scaffolding" | "scheduling" | "storage" | "validation";
 export type McpToolSideEffect = "filesystem" | "local-process-or-remote-run" | "none" | "schedule-state";
 export interface McpToolContract {
     name: string;

package/dist/lib/native-storage.d.ts

@@ -0,0 +1,251 @@
+export type SkillsStorageMode = "local" | "remote" | "hybrid";
+export declare const SKILLS_STORAGE_TABLES: readonly ["skills_sync_records", "skills_sync_cursors"];
+export declare const STORAGE_TABLES: readonly ["skills_sync_records", "skills_sync_cursors"];
+export type SkillsStorageTable = typeof SKILLS_STORAGE_TABLES[number];
+export interface SkillsNativeStorageConfig {
+    mode: SkillsStorageMode;
+    databaseUrl?: string;
+    databaseSsl?: boolean;
+    databaseSchema?: string;
+    s3Bucket?: string;
+    s3Prefix?: string;
+    awsRegion?: string;
+    s3Endpoint?: string;
+    s3ForcePathStyle?: boolean;
+    syncBatchSize: number;
+    dryRun: boolean;
+}
+export declare const SKILLS_NATIVE_STORAGE_ENV: {
+    readonly mode: "HASNA_SKILLS_STORAGE_MODE";
+    readonly databaseUrl: "HASNA_SKILLS_DATABASE_URL";
+    readonly databaseSsl: "HASNA_SKILLS_DATABASE_SSL";
+    readonly databaseSchema: "HASNA_SKILLS_DATABASE_SCHEMA";
+    readonly s3Bucket: "HASNA_SKILLS_S3_BUCKET";
+    readonly s3Prefix: "HASNA_SKILLS_S3_PREFIX";
+    readonly awsRegion: "HASNA_SKILLS_AWS_REGION";
+    readonly s3Endpoint: "HASNA_SKILLS_S3_ENDPOINT";
+    readonly s3ForcePathStyle: "HASNA_SKILLS_S3_FORCE_PATH_STYLE";
+    readonly s3AccessKeyId: "HASNA_SKILLS_S3_ACCESS_KEY_ID";
+    readonly s3SecretAccessKey: "HASNA_SKILLS_S3_SECRET_ACCESS_KEY";
+    readonly s3SessionToken: "HASNA_SKILLS_S3_SESSION_TOKEN";
+    readonly syncBatchSize: "HASNA_SKILLS_SYNC_BATCH_SIZE";
+    readonly dryRun: "HASNA_SKILLS_SYNC_DRY_RUN";
+};
+export declare const SKILLS_NATIVE_STORAGE_FALLBACK_ENV: {
+    readonly mode: "SKILLS_STORAGE_MODE";
+    readonly databaseUrl: "SKILLS_DATABASE_URL";
+    readonly databaseSsl: "SKILLS_DATABASE_SSL";
+    readonly databaseSchema: "SKILLS_DATABASE_SCHEMA";
+    readonly s3Bucket: "SKILLS_S3_BUCKET";
+    readonly s3Prefix: "SKILLS_S3_PREFIX";
+    readonly awsRegion: "SKILLS_AWS_REGION";
+    readonly s3Endpoint: "SKILLS_S3_ENDPOINT";
+    readonly s3ForcePathStyle: "SKILLS_S3_FORCE_PATH_STYLE";
+    readonly s3AccessKeyId: "SKILLS_S3_ACCESS_KEY_ID";
+    readonly s3SecretAccessKey: "SKILLS_S3_SECRET_ACCESS_KEY";
+    readonly s3SessionToken: "SKILLS_S3_SESSION_TOKEN";
+    readonly syncBatchSize: "SKILLS_SYNC_BATCH_SIZE";
+    readonly dryRun: "SKILLS_SYNC_DRY_RUN";
+};
+export declare const SKILLS_STORAGE_ENV: {
+    readonly mode: "HASNA_SKILLS_STORAGE_MODE";
+    readonly databaseUrl: "HASNA_SKILLS_DATABASE_URL";
+    readonly databaseSsl: "HASNA_SKILLS_DATABASE_SSL";
+    readonly databaseSchema: "HASNA_SKILLS_DATABASE_SCHEMA";
+    readonly s3Bucket: "HASNA_SKILLS_S3_BUCKET";
+    readonly s3Prefix: "HASNA_SKILLS_S3_PREFIX";
+    readonly awsRegion: "HASNA_SKILLS_AWS_REGION";
+    readonly s3Endpoint: "HASNA_SKILLS_S3_ENDPOINT";
+    readonly s3ForcePathStyle: "HASNA_SKILLS_S3_FORCE_PATH_STYLE";
+    readonly s3AccessKeyId: "HASNA_SKILLS_S3_ACCESS_KEY_ID";
+    readonly s3SecretAccessKey: "HASNA_SKILLS_S3_SECRET_ACCESS_KEY";
+    readonly s3SessionToken: "HASNA_SKILLS_S3_SESSION_TOKEN";
+    readonly syncBatchSize: "HASNA_SKILLS_SYNC_BATCH_SIZE";
+    readonly dryRun: "HASNA_SKILLS_SYNC_DRY_RUN";
+};
+export declare const SKILLS_STORAGE_FALLBACK_ENV: {
+    readonly mode: "SKILLS_STORAGE_MODE";
+    readonly databaseUrl: "SKILLS_DATABASE_URL";
+    readonly databaseSsl: "SKILLS_DATABASE_SSL";
+    readonly databaseSchema: "SKILLS_DATABASE_SCHEMA";
+    readonly s3Bucket: "SKILLS_S3_BUCKET";
+    readonly s3Prefix: "SKILLS_S3_PREFIX";
+    readonly awsRegion: "SKILLS_AWS_REGION";
+    readonly s3Endpoint: "SKILLS_S3_ENDPOINT";
+    readonly s3ForcePathStyle: "SKILLS_S3_FORCE_PATH_STYLE";
+    readonly s3AccessKeyId: "SKILLS_S3_ACCESS_KEY_ID";
+    readonly s3SecretAccessKey: "SKILLS_S3_SECRET_ACCESS_KEY";
+    readonly s3SessionToken: "SKILLS_S3_SESSION_TOKEN";
+    readonly syncBatchSize: "SKILLS_SYNC_BATCH_SIZE";
+    readonly dryRun: "SKILLS_SYNC_DRY_RUN";
+};
+export declare function resolveSkillsNativeStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
+export declare function resolveStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
+export declare function getSkillsStorageMode(env?: Record<string, string | undefined>): SkillsStorageMode;
+export declare function getStorageMode(env?: Record<string, string | undefined>): SkillsStorageMode;
+export declare function getSkillsStorageDatabaseEnv(env?: Record<string, string | undefined>): string;
+export declare function getStorageDatabaseEnv(env?: Record<string, string | undefined>): string;
+export declare function getSkillsStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
+export declare function getStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
+export interface SkillsNativeStorageStatus {
+    package: "open-skills";
+    mode: SkillsStorageMode;
+    tables: readonly SkillsStorageTable[];
+    env: {
+        mode: string;
+        databaseUrl: string;
+        s3Bucket: string;
+    };
+    local: {
+        dataDir: string;
+        projectStateDir: string;
+        feedbackDbPath: string;
+    };
+    remote: {
+        databaseConfigured: boolean;
+        s3Configured: boolean;
+        databaseEnv: string;
+        s3BucketEnv: string;
+        activeModeEnv: string;
+        activeDatabaseEnv: string;
+        activeS3BucketEnv: string;
+        region: string;
+        dryRun: boolean;
+    };
+}
+export declare function getSkillsNativeStorageStatus(options?: {
+    targetDir?: string;
+    env?: Record<string, string | undefined>;
+}): SkillsNativeStorageStatus;
+export declare function getSkillsStorageStatus(options?: {
+    targetDir?: string;
+    env?: Record<string, string | undefined>;
+}): SkillsNativeStorageStatus;
+export declare function getStorageStatus(options?: {
+    targetDir?: string;
+    env?: Record<string, string | undefined>;
+}): SkillsNativeStorageStatus;
+export interface SkillsSnapshotFile {
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+    contentBase64?: string;
+}
+export interface SkillsLocalSnapshot {
+    schemaVersion: 1;
+    exportedAt: string;
+    files: SkillsSnapshotFile[];
+}
+export declare function exportSkillsLocalSnapshot(targetDir?: string, options?: {
+    includeFileContents?: boolean;
+}): SkillsLocalSnapshot;
+export declare function importSkillsLocalSnapshot(snapshot: SkillsLocalSnapshot, targetDir?: string, options?: {
+    overwrite?: boolean;
+}): {
+    written: number;
+    skipped: number;
+};
+export interface SkillsPostgresQueryClient {
+    query<T = unknown>(sql: string, values?: readonly unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export interface SkillsSyncRecord {
+    scope: string;
+    kind: string;
+    id: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    source?: string | null;
+    payload: Record<string, unknown>;
+}
+export declare const skillsPostgresSyncSchemaSql: string;
+export declare class SkillsPostgresSyncStore {
+    private readonly client;
+    constructor(client: SkillsPostgresQueryClient);
+    ensureSchema(): Promise<void>;
+    upsertRecords(records: readonly SkillsSyncRecord[]): Promise<number>;
+    pullUpdatedSince(params: {
+        scope: string;
+        since?: string;
+        limit?: number;
+    }): Promise<SkillsSyncRecord[]>;
+    getCursor(scope: string, cursorName: string): Promise<string | null>;
+    setCursor(scope: string, cursorName: string, value: string): Promise<void>;
+}
+export declare function createSkillsPostgresSyncStore(client: SkillsPostgresQueryClient): SkillsPostgresSyncStore;
+export declare function createSkillsSnapshotSyncRecord(snapshot: SkillsLocalSnapshot, options?: {
+    scope?: string;
+    id?: string;
+    source?: string;
+}): SkillsSyncRecord;
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SkillsS3ObjectStoreOptions {
+    bucket: string;
+    region?: string;
+    prefix?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    credentials: AwsCredentials;
+    fetch?: SkillsFetch;
+}
+export interface SkillsS3PutObjectOptions {
+    key: string;
+    body: Uint8Array | string;
+    contentType?: string;
+}
+export interface SkillsS3StoredObject {
+    key: string;
+    url: string;
+    etag?: string | null;
+    sizeBytes: number;
+}
+export type SkillsFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare class SkillsS3ObjectStore {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly region;
+    private readonly prefix;
+    constructor(options: SkillsS3ObjectStoreOptions);
+    objectKey(path: string): string;
+    objectUrl(key: string): string;
+    putObject(params: SkillsS3PutObjectOptions): Promise<SkillsS3StoredObject>;
+    getObject(key: string): Promise<Uint8Array>;
+}
+export declare function createSkillsS3ObjectStore(options: SkillsS3ObjectStoreOptions): SkillsS3ObjectStore;
+export interface SkillsS3SnapshotPlanEntry {
+    path: string;
+    key: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export declare function planSkillsS3SnapshotUpload(snapshot: SkillsLocalSnapshot, options?: {
+    prefix?: string;
+}): SkillsS3SnapshotPlanEntry[];
+export declare function uploadSkillsSnapshotFilesToS3(snapshot: SkillsLocalSnapshot, store: SkillsS3ObjectStore): Promise<SkillsS3StoredObject[]>;
+export interface SignSkillsAwsV4RequestOptions {
+    method: string;
+    url: string;
+    region: string;
+    service: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array | string;
+    credentials: AwsCredentials;
+    now?: Date;
+}
+export declare function signSkillsAwsV4Request(options: SignSkillsAwsV4RequestOptions): {
+    headers: Record<string, string>;
+    canonicalRequest: string;
+    stringToSign: string;
+};
+export declare function buildSkillsS3ObjectUrl(params: {
+    bucket: string;
+    key: string;
+    region?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}): string;

package/dist/lib/portable-skills.d.ts

@@ -0,0 +1,79 @@
+import type { SkillMeta } from "./registry-types.js";
+import { type SkillValidationResult } from "./skill-validation.js";
+export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
+export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
+export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+export interface PortableSkillInput {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+export interface PortableSkillCommand {
+    name: string;
+    description?: string;
+    entry?: string;
+    command?: string;
+    args?: string[];
+}
+export interface PortableSkillManifest {
+    $schema?: string;
+    standard: typeof PORTABLE_SKILL_STANDARD | string;
+    name: string;
+    description: string;
+    version: string;
+    displayName?: string;
+    category?: string;
+    tags?: string[];
+    inputs: PortableSkillInput[];
+    commands: PortableSkillCommand[];
+}
+export interface PortableSkillSummary {
+    name: string;
+    displayName: string;
+    description: string;
+    version: string;
+    path: string;
+    commands: PortableSkillCommand[];
+    source: "custom";
+    standard: string;
+}
+export interface PortableSkillOptions {
+    rootDir?: string;
+    homeDir?: string;
+}
+export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
+    description?: string;
+    overwrite?: boolean;
+}
+export interface PortPortableSkillOptions extends PortableSkillOptions {
+    name?: string;
+    overwrite?: boolean;
+}
+export interface PortableSkillWriteResult {
+    name: string;
+    path: string;
+    manifest: PortableSkillManifest;
+    created: boolean;
+}
+export interface PortableSkillRunOptions extends PortableSkillOptions {
+    stdio?: "inherit" | "pipe";
+    env?: Record<string, string>;
+}
+export interface PortableSkillRunResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+}
+export declare function normalizePortableSkillName(name: string): string;
+export declare function getPortableSkillsRoot(options?: PortableSkillOptions): string;
+export declare function getPortableSkillPath(name: string, options?: PortableSkillOptions): string;
+export declare function findPortableSkill(name: string, options?: PortableSkillOptions): PortableSkillSummary | null;
+export declare function listPortableSkills(options?: PortableSkillOptions): PortableSkillSummary[];
+export declare function listPortableSkillMetas(options?: PortableSkillOptions): SkillMeta[];
+export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
+export declare function scaffoldPortableSkill(name: string, options?: ScaffoldPortableSkillOptions): PortableSkillWriteResult;
+export declare function portPortableSkill(sourcePath: string, options?: PortPortableSkillOptions): PortableSkillWriteResult;
+export declare function validatePortableSkillDirectory(name: string, skillPath: string): SkillValidationResult;
+export declare function runPortableSkill(name: string, args: string[], options?: PortableSkillRunOptions): Promise<PortableSkillRunResult>;

package/dist/lib/registry.d.ts

@@ -8,7 +8,7 @@ export type { Category, SkillMeta, SkillRegistryProfile };
 export declare function isBasicSkillName(name: string): boolean;
 /**
  * Load the full registry: official skills merged with global custom skills
- * from ~/.hasna/skills/custom/.
+ * from ~/.hasna/skills/<name>/ and the legacy ~/.hasna/skills/custom/<name>/ path.
  *
  * Custom skills with the same name as official skills take precedence.
  * Results are cached for 5 seconds.

package/dist/lib/skill-validation.d.ts

@@ -1,4 +1,5 @@
 import type { SkillMeta } from "./registry.js";
+import type { PortableSkillManifest } from "./portable-skills.js";
 export interface SkillValidationMessage {
     code: string;
     message: string;
@@ -15,6 +16,7 @@ export interface SkillValidationResult {
         binCommands: string[];
         docFiles: string[];
         skillMdFrontmatter?: SkillFrontmatter;
+        portableManifest?: PortableSkillManifest;
         provenance?: SkillValidationProvenance;
         runtime?: "local" | "hosted";
     };

package/dist/mcp/storage-tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStorageTools(server: McpServer): void;

package/dist/storage.d.ts

@@ -0,0 +1 @@
+export { SKILLS_NATIVE_STORAGE_ENV, SKILLS_NATIVE_STORAGE_FALLBACK_ENV, SKILLS_STORAGE_ENV, SKILLS_STORAGE_FALLBACK_ENV, SKILLS_STORAGE_TABLES, STORAGE_TABLES, SkillsPostgresSyncStore, SkillsS3ObjectStore, buildSkillsS3ObjectUrl, createSkillsPostgresSyncStore, createSkillsS3ObjectStore, createSkillsSnapshotSyncRecord, exportSkillsLocalSnapshot, getSkillsNativeStorageStatus, getSkillsStorageDatabaseEnv, getSkillsStorageDatabaseUrl, getSkillsStorageMode, getSkillsStorageStatus, getStorageDatabaseEnv, getStorageDatabaseUrl, getStorageMode, getStorageStatus, importSkillsLocalSnapshot, planSkillsS3SnapshotUpload, resolveSkillsNativeStorageConfig, resolveStorageConfig, signSkillsAwsV4Request, skillsPostgresSyncSchemaSql, uploadSkillsSnapshotFilesToS3, type AwsCredentials, type SignSkillsAwsV4RequestOptions, type SkillsFetch, type SkillsLocalSnapshot, type SkillsNativeStorageConfig, type SkillsNativeStorageStatus, type SkillsPostgresQueryClient, type SkillsS3ObjectStoreOptions, type SkillsS3PutObjectOptions, type SkillsS3SnapshotPlanEntry, type SkillsS3StoredObject, type SkillsSnapshotFile, type SkillsStorageMode, type SkillsStorageTable, type SkillsSyncRecord, } from "./lib/native-storage.js";