@hasna/skills 0.1.71 → 0.1.72

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

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+/** 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.
+ */
+export declare function resolverDataRoot(home?: string): 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.
+ */
+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/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). */