@hasna/skills 0.1.72 → 0.2.0

package/dist/lib/app-home.d.ts

@@ -17,6 +17,15 @@
  * Nothing moves on disk in this phase — the package just resolves the new
  * paths.
  */
+export type PathKind = "config" | "data" | "state" | "cache";
+export interface PathsResolverOptions {
+    app: string;
+    internal?: boolean;
+    platform?: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+}
+export declare function dataDir(options: PathsResolverOptions): string;
 /** Env var that relocates the skills data directory (the shipped override). */
 export declare const DATA_DIR_ENV = "HASNA_SKILLS_DIR";
 /** Wave-convention exact-app home aliases, honoured after HASNA_SKILLS_DIR. */
@@ -41,8 +50,15 @@ export declare function legacyDataRoot(): string;
  * Support/Hasna/skills` on macOS. The home override mirrors the pre-existing
  * `$HOME`-first resolution so the resolver follows the same home the legacy
  * path does.
+ *
+ * `env` is forwarded to the resolver: an injected env (e.g. `{}` for a
+ * staged home mirror) suppresses the process-level `HASNA_*_HOME` overrides,
+ * which describe THIS machine's live store and must not relocate a mirror.
+ * `@hasna/paths` applies env overrides before the injected home, so without
+ * this the resolver would ignore the mirror home whenever `HASNA_DATA_HOME`
+ * is set.
  */
-export declare function resolverDataRoot(home?: string): string;
+export declare function resolverDataRoot(home?: string, env?: Record<string, string | undefined>): string;
 /**
  * Whether the resolver (XDG) data root should be adopted as the effective
  * data root. The resolver root is adopted only when the operator has set
@@ -81,5 +97,15 @@ export declare function getDataRoot(): string;
  * The skills app data root for an explicit home root, mirroring getDataRoot()
  * with the home injected. Used by the sync-home snapshot mapping to enumerate
  * the skills corpus under a staged home mirror (`homesRoot`) or the real home.
+ *
+ * Process-level overrides (`HASNA_SKILLS_DIR` / `HASNA_SKILLS_HOME` /
+ * `SKILLS_HOME`, and the data-kind `HASNA_DATA_HOME`) describe THIS machine's
+ * live store. They apply only when the requested home IS the process's own
+ * effective home; a staged mirror (a different home, e.g. an rsync'd
+ * remote-station `homesRoot`) must resolve its own layout — the mirror's XDG
+ * data root once the mirror itself carries a migrated store there, else the
+ * mirror's legacy `~/.hasna/skills` — never the local process's live data
+ * root. Snapshotting a staged home with the local `HASNA_DATA_HOME` set would
+ * otherwise read live local data instead of the supplied mirror.
  */
 export declare function skillsDataRootForHome(home: string): string;

package/dist/lib/feedback.d.ts

@@ -20,3 +20,9 @@ export interface FeedbackResult {
  */
 export declare function getFeedbackDbPath(): string;
 export declare function saveFeedback(input: FeedbackInput): FeedbackResult;
+/**
+ * True when this install is pointed at a Skills instance: the env var, its HASNA_-prefixed
+ * alias, or the config file written by `skills setup --api-url` / `skills login`. The check
+ * never throws - a broken config file means local mode, not a crash in `skills feedback`.
+ */
+export declare function isApiMode(env?: Record<string, string | undefined>): boolean;

package/dist/lib/installer.d.ts

@@ -16,6 +16,8 @@ export interface InstallResult {
     path?: string;
     mode?: InstallMode;
     source?: InstallSource;
+    /** Exact published version when the caller asked for name@version (hasna/apps#1630). */
+    version?: string;
 }
 export interface InstallOptions {
     targetDir?: string;

package/dist/lib/pull.d.ts

@@ -25,7 +25,15 @@ export interface SkillPullClient {
      * `Response` is the natural transport type here: verification reads the
      * X-Skill-Bundle-Sha256 / X-Skill-Bundle-Signature headers off it.
      */
-    getBundle(slug: string): Promise<Response | null>;
+    getBundle(slug: string, version?: string): Promise<Response | null>;
+    /**
+     * The registry's record of one published version (hasna/apps#1630), or null. Optional:
+     * an exact-version pull proves the received bytes against this digest; a client that
+     * cannot answer it falls back to the bundle's own digest header.
+     */
+    getSkillVersion?(slug: string, version: string): Promise<{
+        bundleSha256?: string;
+    } | null>;
 }
 export interface PullSkillsOptions extends PortableSkillOptions {
     /** Explicit skill names to pull. Ignored when `all` is set. */
@@ -136,3 +144,12 @@ export declare function writePullMarker(dir: string, record: {
     revisionId?: string;
     source?: "pull" | "sync";
 }): void;
+/**
+ * Split `name@version` into its parts. A name without `@` pulls the current revision; an
+ * empty version (`name@`) is an error the caller reports. Scoped-looking names are not a
+ * concern here: skill slugs never start with `@`.
+ */
+export declare function splitNameVersion(raw: string): {
+    name: string;
+    version?: string;
+};

package/dist/lib/remote-client.d.ts

@@ -22,6 +22,16 @@ export declare class RemoteRequestError extends Error {
  * (`{ slug, pinnedAt, metadata }`). `pinnedAt`/`metadata` are server-reported
  * and may be absent.
  */
+export interface RemoteSkillVersion {
+    slug: string;
+    version: string;
+    bundleSha256: string;
+    bundleByteSize: number;
+    storageKind?: string;
+    manifest?: Record<string, unknown>;
+    createdAt: string;
+    current?: boolean;
+}
 export interface RemotePin {
     slug: string;
     pinnedAt?: string;
@@ -109,8 +119,12 @@ export declare class RemoteSkillsClient {
      * read the X-Skill-Bundle-Sha256 / X-Skill-Bundle-Signature headers, or null when the
      * instance serves no bundle for this skill (the metadata-only fallback path).
      */
-    getBundle(slug: string): Promise<Response | null>;
+    getBundle(slug: string, version?: string): Promise<Response | null>;
     /** List the pins the instance holds for this principal. */
+    /** Every published version of a slug, newest first (hasna/apps#1630). */
+    listSkillVersions(slug: string): Promise<RemoteSkillVersion[]>;
+    /** One version's manifest, or null when the slug@version was never published. */
+    getSkillVersion(slug: string, version: string): Promise<RemoteSkillVersion | null>;
     listPins(): Promise<RemotePin[]>;
     /**
      * Pin a skill on the instance (upsert — pinning again refreshes it). The

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

@@ -0,0 +1,11 @@
+/**
+ * What a skill version string may look like (hasna/apps#1630).
+ *
+ * The version becomes a path segment in the version-addressed object key and in the
+ * `/versions/:version` routes, so it is a closed alphabet rather than "whatever the
+ * publisher sent": no separators, no dot-only names, bounded length. Semver fits; so do
+ * date stamps and package-style prereleases.
+ */
+export declare const SKILL_VERSION_PATTERN: RegExp;
+export declare function isValidSkillVersion(value: unknown): boolean;
+export declare const SKILL_VERSION_RULE = "1-128 characters: letters, digits, '.', '_', '+', '-'; must start with a letter or digit; no '..'";