@hasna/skills 0.1.71 → 0.2.0

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

@@ -0,0 +1,111 @@
+/**
+ * Skills app-home resolution through the @hasna/paths resolver.
+ *
+ * Skills keeps its global config (`config.json`), auth (`auth.json`), the
+ * default SQLite database (`server.db`), the corpus cache (`skills/`), and the
+ * portable-skill tree (`installed/`, `custom/`) under one data root.
+ * Historically that root was `~/.hasna/skills`. This module resolves the root
+ * through `@hasna/paths` (XDG / macOS home layout) with a gated legacy
+ * adoption: the legacy `~/.hasna/skills` stays the effective data root until
+ * the store is physically migrated to the XDG data home (`server.db` or
+ * `config.json` present there) or the operator sets the data-kind override
+ * `HASNA_DATA_HOME`. An existing live store never becomes invisible on
+ * upgrade. The exact-app overrides win unconditionally, in this order:
+ * `HASNA_SKILLS_DIR` (the shipped override), then the wave-convention aliases
+ * `HASNA_SKILLS_HOME` and `SKILLS_HOME`.
+ *
+ * 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. */
+export declare const HASNA_SKILLS_HOME_ENV = "HASNA_SKILLS_HOME";
+export declare const SKILLS_HOME_ENV = "SKILLS_HOME";
+/** Filename of the default SQLite database inside the skills data directory. */
+export declare const DEFAULT_SQLITE_FILENAME = "server.db";
+/** Filename of the global config file inside the skills data directory. */
+export declare const GLOBAL_CONFIG_FILENAME = "config.json";
+/**
+ * The effective user home, mirroring the pre-existing skills resolution
+ * (`HOME` || `USERPROFILE` || `os.homedir()`). Read at call time so a runtime
+ * `HOME` reassignment (e.g. a test temp home) is honoured — `os.homedir()`
+ * snapshots `HOME` at process start and, under Bun, ignores later changes.
+ */
+export declare function effectiveHome(): string;
+/** The legacy (pre-XDG) data root: `~/.hasna/skills`. */
+export declare function legacyDataRoot(): string;
+/**
+ * The @hasna/paths-resolved (XDG / macOS home layout) data root for skills:
+ * `~/.local/share/hasna/skills` on Linux, `~/Library/Application
+ * 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, 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
+ * `HASNA_DATA_HOME` (the data-kind override — a deliberate opt-in to the XDG
+ * layout) or the store has already been physically migrated there (`server.db`
+ * — the default SQLite store — or `config.json` exists). A machine that only
+ * redirects another kind (e.g. cache to tmpfs) must NOT have its data home
+ * moved, and a live store at the legacy home must never become invisible on
+ * upgrade.
+ */
+export declare function adoptResolverDataRoot(resolved: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The exact-app override root, when set: the shipped `HASNA_SKILLS_DIR` wins,
+ * then the wave-convention aliases `HASNA_SKILLS_HOME` and `SKILLS_HOME`.
+ * First non-blank override wins; a blank or whitespace-only primary must not
+ * shadow a valid secondary (nullish `??` does not fall through on `""`).
+ */
+export declare function exactDataRoot(): string | undefined;
+/** Whether an exact-app override root is set (used to skip legacy migration). */
+export declare function hasExactOverride(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the operator named a data root at all — an exact-app override or the
+ * data-kind `HASNA_DATA_HOME`. Used to decide when the legacy `~/.skills` /
+ * `~/.skillsrc` migration must be skipped: copying a stray legacy tree into an
+ * operator-chosen directory would be a surprising write.
+ */
+export declare function hasOperatorOverride(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The effective data root: an exact-app override (`HASNA_SKILLS_DIR`, then
+ * `HASNA_SKILLS_HOME` / `SKILLS_HOME`) wins unconditionally; otherwise the
+ * resolver (XDG) data root once adopted; otherwise the legacy `~/.hasna/skills`
+ * default. Write-free: callers that need the directory to exist create it.
+ */
+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/config.d.ts

@@ -8,6 +8,13 @@
  *
  * Values from the project config override global config.
  */
+/**
+ * Environment variable that relocates the skills data directory.
+ *
+ * Owned by the @hasna/paths-based app-home resolver (app-home.ts), re-exported
+ * here so every existing reader keeps agreeing on the name.
+ */
+export { DATA_DIR_ENV } from "./app-home.js";
 /**
  * There is no deployment "mode" key.
  *
@@ -35,14 +42,6 @@ export interface SkillsConfig {
     extensionsDir?: string;
 }
 export type ConfigScope = "global" | "project";
-/**
- * Environment variable that relocates the skills data directory.
- *
- * Exported so that every reader agrees on the name: previously the literal was
- * duplicated in portable-skills.ts and honoured there but *not* in getDataDir(),
- * which is what made the override only half work (see getDataDir below).
- */
-export declare const DATA_DIR_ENV = "HASNA_SKILLS_DIR";
 /**
  * Subfolder of the data directory holding the installed skill corpus.
  *
@@ -92,8 +91,8 @@ export declare function getDataDir(): string;
  *
  * getDataDir() itself writes: it mkdirs the app folder, merges legacy ~/.skills
  * content and copies the legacy config file. A dry run must resolve the SAME
- * directory a real run would use without performing any of that — mirror the path
- * logic only, reading $HASNA_SKILLS_DIR and $HOME exactly the way getDataDir does.
+ * directory a real run would use without performing any of that — the app-home
+ * resolver (getDataRoot) is already write-free, so this mirrors it directly.
  */
 export declare function getDataDirReadOnly(): 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 '..'";

package/dist/lib/station-hydrate.d.ts

@@ -20,6 +20,8 @@ export interface HydrationCandidate {
     mtimeMs: number;
     /** The manifest's recorded sha256 for (agent, home-relative path), if any. */
     manifestHash: string | null;
+    /** True when the candidate's bytes hash to the manifest record (verified match). */
+    verified: boolean;
 }
 export interface HydrationWinnerFile {
     withinIdent: string;

package/dist/lib/station-snapshot.d.ts

@@ -11,7 +11,7 @@ export declare const STATION_SNAPSHOT_PRODUCER: {
     name: string;
     version: string;
 };
-export type StationSnapshotErrorCode = "INVALID_STATION" | "SYMLINKS_REFUSED" | "CONFLICT" | "DESTINATION_ESCAPE" | "MANIFEST_UNREADABLE";
+export type StationSnapshotErrorCode = "INVALID_STATION" | "SYMLINKS_REFUSED" | "CONFLICT" | "DESTINATION_ESCAPE" | "MANIFEST_UNREADABLE" | "MANIFEST_HASH_MISMATCH";
 export declare class StationSnapshotError extends Error {
     readonly code: StationSnapshotErrorCode;
     /** Per-item lines for the CONFLICT class (printed before the summary). */