@hasna/skills 0.1.70 → 0.1.71

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,103 @@
+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;
+}
+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";
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.70",
+  "version": "0.1.71",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {