@hasna/skills 0.1.70 → 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/portable-snapshot-filter.d.ts

@@ -0,0 +1,48 @@
+import type { SyncAgent } from "./agent-sync.js";
+/** A snapshot source: one directory of installed skills. */
+export interface SyncHomeDefinition {
+    /** Directory name used in the snapshot destination and reporting. */
+    name: string;
+    /** Snapshot category: the standalone stores, or one of the agent homes. */
+    subClass: "skills" | "custom" | "agent-homes";
+    /** The coding agent whose home this is, when subClass is agent-homes. */
+    agent: SyncAgent | null;
+}
+/** The seven installed skill homes the per-station snapshot covers. */
+export declare const SYNC_HOMES: readonly SyncHomeDefinition[];
+/**
+ * Scanner-flagged portable files the fleet conformance gate refuses. They are
+ * absent from the snapshots by construction; the check stays as defense in
+ * depth. See the header comment for the provenance and retirement path.
+ */
+export declare const REFUSED_SCANNER_FLAGGED: Set<string>;
+export declare function isExcludedSkillFileName(fileName: string): boolean;
+/**
+ * The portable filter: only files at `<ident>/SKILL.md`, `<ident>/skill.json`,
+ * and `<ident>/scripts|assets|references/*` may reach a snapshot or the cache.
+ */
+export declare function isPortableWithinSkill(relativeParts: string[]): boolean;
+/**
+ * The on-disk location of one of the seven snapshot homes. `homesRoot` stages
+ * a copy of the homes (e.g. an rsync'd mirror of a remote station); when
+ * absent, this machine's real `$HOME` is the root. The staged layout mirrors
+ * the home mapping: `<dir>/skills`, `<dir>/<agent>/skills`,
+ * `<dir>/opencode/skills`.
+ */
+export declare function homePathFor(definition: SyncHomeDefinition, homesRoot?: string): string;
+/** Snapshot destination inside the repo, relative to the repo root. */
+export declare function destinationFor(definition: SyncHomeDefinition, stationId: string, relativePath: string): string;
+export interface WalkEntry {
+    kind: "file" | "symlink";
+    relativePath: string;
+    fullPath: string;
+}
+/**
+ * Recursive walk that records symlinks instead of following them, and skips
+ * the excluded directory names/patterns. A missing root reads as empty — the
+ * same contract as the source script, where an absent home is a zero-file
+ * home, not an error.
+ */
+export declare function walkEntries(absoluteRoot: string): WalkEntry[];
+/** True when a path exists and is a regular file. */
+export declare function isRegularFile(filePath: string): boolean;

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

@@ -0,0 +1,105 @@
+import { type SyncAgent } from "./agent-sync.js";
+/**
+ * The wire schema of the per-station hydration manifest; keeps the
+ * fleet-resources spelling for the same wire-compat reason as the
+ * sync-manifest.
+ */
+export declare const STATION_HYDRATION_MANIFEST_SCHEMA = "hasna.fleet-resources.skills-hydration-manifest/v1";
+/** Package identity recorded in the manifest's producer field. */
+export declare const STATION_HYDRATION_PRODUCER: {
+    name: string;
+    version: string;
+};
+export interface HydrationCandidate {
+    ident: string;
+    agent: SyncAgent;
+    /** Ident-relative portable path, e.g. `scripts/run.sh`. */
+    withinIdent: string;
+    fullPath: string;
+    size: number;
+    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;
+    winner: HydrationCandidate;
+    /** The losing copies' agents, for reporting. */
+    alternates: SyncAgent[];
+}
+export interface HydrationWinnerSkill {
+    ident: string;
+    files: HydrationWinnerFile[];
+}
+export interface StationHydrationOptions {
+    stationId: string;
+    /** Repo root holding resources/<stationId>/skills and its sync-manifest. */
+    repoRoot?: string;
+    /** Destination corpus cache; defaults to the canonical corpus root. */
+    cacheRoot?: string;
+    /** Report without writing anything (the default, as in the source script). */
+    dryRun?: boolean;
+}
+export interface StationHydrationResult {
+    stationId: string;
+    mode: "dry-run" | "apply";
+    cacheRoot: string;
+    snapshotRoot: string;
+    sourceSnapshotSha: string;
+    stats: {
+        idents: number;
+        files: number;
+        bytes: number;
+        written?: number;
+        unchanged?: number;
+    };
+    /** The full winner plan, for reporting (never written to the manifest). */
+    winners: HydrationWinnerSkill[];
+    /** The manifest payload shape: per-skill files plus the skill's sha256. */
+    skills: Array<{
+        ident: string;
+        files: Array<{
+            relativePath: string;
+            sourceAgent: SyncAgent;
+            sourceMtimeMs: number;
+            size: number;
+        }>;
+        sha256: string | null;
+    }>;
+    manifestPath?: string;
+}
+interface SnapshotManifestFile {
+    relativePath: string;
+    agent: string | null;
+    sha256: string;
+}
+interface SnapshotManifest {
+    files?: SnapshotManifestFile[];
+}
+interface HydrationPlan {
+    manifest: SnapshotManifest;
+    sourceSnapshotSha: string;
+    winners: HydrationWinnerSkill[];
+    skippedByRule: Array<{
+        ident: string;
+        agent: SyncAgent;
+        relativePath: string;
+        reason: string;
+    }>;
+    totalFiles: number;
+    totalBytes: number;
+}
+/**
+ * Build the dedup winner plan from the snapshot. Fails closed on symlinks and
+ * on a missing or unreadable sync-manifest.
+ */
+export declare function planStationHydration(stationId: string, repoRoot: string): HydrationPlan;
+/**
+ * Run the hydration. Dry-run reports and writes nothing; apply detects
+ * conflicts across the whole plan first and only then writes, so the terminal
+ * refusal genuinely writes nothing.
+ */
+export declare function writeStationHydration(options: StationHydrationOptions): StationHydrationResult;
+export {};

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

@@ -0,0 +1,96 @@
+import { type SyncHomeDefinition } from "./portable-snapshot-filter.js";
+/**
+ * The wire schema of the per-station sync-manifest. The name keeps the
+ * fleet-resources spelling deliberately: the fleet hydrator (and the snapshot
+ * repo's consumers) record and compare this string, so the package-owned
+ * producer writes the same value the retired script wrote.
+ */
+export declare const STATION_SYNC_MANIFEST_SCHEMA = "hasna.fleet-resources.skills-sync-manifest/v1";
+/** Package identity recorded in the manifest's producer field. */
+export declare const STATION_SNAPSHOT_PRODUCER: {
+    name: string;
+    version: string;
+};
+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). */
+    readonly detail: string[];
+    constructor(code: StationSnapshotErrorCode, message: string, detail?: string[]);
+}
+/** Validate a station id the same way the source script does. */
+export declare function validateStationId(stationId: string): void;
+export interface PortableSnapshotFile {
+    relativePath: string;
+    fullPath: string;
+    size: number;
+    mtimeMs: number;
+    mtimeIso: string;
+}
+export interface SnapshotSkip {
+    relativePath: string;
+    reason: "symlink" | "not-portable" | "excluded" | "refused-scanner-flagged" | "not-regular-file";
+}
+export interface ScannedHome {
+    definition: SyncHomeDefinition;
+    homePath: string;
+    portable: PortableSnapshotFile[];
+    skipped: SnapshotSkip[];
+}
+export interface SnapshotPlan {
+    definition: SyncHomeDefinition;
+    source: PortableSnapshotFile;
+    destination: string;
+    digest: string;
+}
+export interface StationSnapshotOptions {
+    stationId: string;
+    /** Target repo root; the snapshot lands in <repoRoot>/resources/<stationId>/skills. */
+    repoRoot?: string;
+    /** Stage the homes from a mirror instead of this machine's real $HOME. */
+    homesRoot?: string;
+    /** Report without writing anything (the default, as in the source script). */
+    dryRun?: boolean;
+}
+export interface StationSnapshotManifestFile {
+    relativePath: string;
+    destination: string;
+    subClass: "skills" | "custom" | "agent-homes";
+    agent: string | null;
+    sha256: string;
+    sourceMtimeMs: number;
+    sourceMtimeIso: string;
+    size: number;
+}
+export interface StationSnapshotResult {
+    stationId: string;
+    mode: "dry-run" | "populate";
+    repoRoot: string;
+    stats: {
+        files: number;
+        bytes: number;
+        written?: number;
+        unchanged?: number;
+    };
+    homes: Array<{
+        name: string;
+        homePath: string;
+        files: number;
+        skipped: number;
+    }>;
+    manifestPath?: string;
+    files: StationSnapshotManifestFile[];
+}
+export declare function sha256File(filePath: string): string;
+/** Scan every home and build the write plan; fails closed on symlinks. */
+export declare function planStationSnapshot(options: StationSnapshotOptions): {
+    scanned: ScannedHome[];
+    plans: SnapshotPlan[];
+    totalBytes: number;
+};
+/**
+ * Run the per-station snapshot. Dry-run reports and writes nothing; populate
+ * detects conflicts across the whole plan first and only then writes, so the
+ * terminal refusal genuinely writes nothing.
+ */
+export declare function writeStationSnapshot(options: StationSnapshotOptions): StationSnapshotResult;