@delorenj/skillex 0.1.1

package/dist/core/migration-activation.d.ts

@@ -0,0 +1,6 @@
+import type { MigrationOptions, MigrationSectionResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+/** Recover recorded objects before current source or manifest validation; never plan new intent. */
+export declare function recoverActivationMigration(options?: MigrationOptions): Promise<ResultEnvelope<MigrationSectionResult | null>>;
+/** A migration section never selects an ambient scope and never invokes ordinary sync. */
+export declare function migrateActivation(options?: MigrationOptions): Promise<ResultEnvelope<MigrationSectionResult | null>>;

package/dist/core/migration-common.d.ts

@@ -0,0 +1,8 @@
+import type { MigrationMapping, MigrationOptions, MigrationSectionResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+export declare function checkMigrationSignal(options: Pick<MigrationOptions, "signal">): void;
+/** Validate authored choices and capture a private, immutable copy before asynchronous work. */
+export declare function parseMigrationMapping(input: unknown): MigrationMapping;
+export declare function normalizeMigrationOptions(options?: MigrationOptions): MigrationOptions;
+export declare function migrationFailure<T>(command: string, error: unknown, data: T): ResultEnvelope<T>;
+export declare function emptyMigrationSection(): MigrationSectionResult;

package/dist/core/migration-manifest.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationOptions, MigrationSectionResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+/** Translate only an explicitly selected declaration; no activation paths are managed here. */
+export declare function migrateManifest(options: MigrationOptions, nameMap?: Readonly<Record<string, string>>): Promise<ResultEnvelope<MigrationSectionResult | null>>;

package/dist/core/migration-registry-state.d.ts

@@ -0,0 +1,72 @@
+import { type BigIntStats } from "node:fs";
+import { type ReceiptSnapshot } from "./activation-state.js";
+import type { MigrationItem, MigrationOptions } from "./migration-types.js";
+export interface MigrationIdentity {
+    readonly dev: string;
+    readonly ino: string;
+    readonly uid: string;
+    readonly mode: number;
+    readonly kind: "directory" | "file" | "link";
+}
+export interface MigrationEntry {
+    readonly path: string;
+    readonly kind: MigrationIdentity["kind"];
+    readonly mode: number;
+    readonly bytes?: Buffer;
+    readonly target?: string;
+}
+export interface MigrationTreeEvidence {
+    readonly root: MigrationIdentity;
+    readonly entries: readonly {
+        readonly path: string;
+        readonly identity: MigrationIdentity;
+        readonly hash: string | null;
+        readonly target: string | null;
+    }[];
+    readonly digest: string;
+}
+export interface MigrationTree {
+    readonly evidence: MigrationTreeEvidence;
+    readonly entries: readonly MigrationEntry[];
+}
+export interface MigrationOperation {
+    readonly item: MigrationItem;
+    readonly path: string;
+    readonly stage: string | null;
+    readonly parked: string | null;
+    readonly parent: MigrationIdentity;
+    readonly ancestors: readonly {
+        readonly path: string;
+        readonly identity: MigrationIdentity;
+    }[];
+    readonly before: MigrationTreeEvidence | null;
+    readonly after: MigrationTreeEvidence | null;
+}
+export interface RegistryMigrationReceipt {
+    readonly version: 1;
+    readonly registry: string;
+    readonly phase: "preparing" | "ready" | "complete";
+    readonly operations: readonly MigrationOperation[];
+    readonly verified: readonly MigrationItem[];
+    readonly nameMap: Readonly<Record<string, string>>;
+    readonly provenance: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    readonly externalRoots?: readonly string[];
+}
+export declare function migrationFailure(path: string, message: string, code?: `E_${string}`): never;
+export declare function migrationLstat(path: string): Promise<BigIntStats | null>;
+export declare function migrationTreeDigest(entries: readonly MigrationEntry[]): string;
+/** Capture every entry, including hidden support assets and provenance, without following links. */
+export declare function captureMigrationTree(root: string): Promise<MigrationTree | null>;
+export declare function assertMigrationIdentity(path: string, expected: MigrationIdentity): Promise<void>;
+export declare function assertMigrationTree(path: string, expected: MigrationTreeEvidence | null): Promise<void>;
+export declare function migrationParent(path: string): Promise<MigrationIdentity>;
+export declare function migrationAncestors(registry: string, path: string): Promise<MigrationOperation["ancestors"]>;
+export declare function assertMigrationAncestors(ancestors: MigrationOperation["ancestors"]): Promise<void>;
+export declare function migrationStage(path: string, suffix: "new" | "old"): string;
+/** The unique staged root is complete and fsynced before any visible source entry is replaced. */
+export declare function stageMigrationTree(path: string, entries: readonly MigrationEntry[], parent: MigrationIdentity, ancestors?: MigrationOperation["ancestors"]): Promise<MigrationTreeEvidence>;
+export declare function removeMigrationTree(path: string, expected: MigrationTreeEvidence): Promise<void>;
+export declare function readRegistryMigrationReceipt(registry: string, options: MigrationOptions, externalRoots?: readonly string[]): Promise<ReceiptSnapshot<RegistryMigrationReceipt>>;
+export declare function writeRegistryMigrationReceipt(previous: ReceiptSnapshot<RegistryMigrationReceipt>, value: RegistryMigrationReceipt, options: MigrationOptions): Promise<ReceiptSnapshot<RegistryMigrationReceipt>>;
+/** Recover only the exact prepared objects, never a tree inferred from target containment. */
+export declare function publishMigrationOperation(operation: MigrationOperation): Promise<void>;

package/dist/core/migration-registry.d.ts

@@ -0,0 +1,7 @@
+import type { MigrationOptions, MigrationSectionResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+export interface RegistryMigrationSection extends MigrationSectionResult {
+    readonly nameMap: Readonly<Record<string, string>>;
+}
+/** Explicit registry migration; previews never create state, staging, catalog, or composition entries. */
+export declare function migrateRegistry(options?: MigrationOptions): Promise<ResultEnvelope<RegistryMigrationSection | null>>;

package/dist/core/migration-sources.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationOptions, MigrationSectionResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+/** Explicit declaration onboarding preserves all recorded skill bytes and upstream pins. */
+export declare function migrateSources(input: MigrationOptions): Promise<ResultEnvelope<MigrationSectionResult | null>>;

package/dist/core/migration-types.d.ts

@@ -0,0 +1,56 @@
+import type { LockOptions } from "./lock.js";
+import type { RegistryOptions, RegistrySelection } from "./selection.js";
+/** Explicit choices for inputs whose names or selections cannot be inferred from content. */
+export interface MigrationMapping {
+    readonly version: 1;
+    readonly names?: Readonly<Record<string, string>>;
+    /** Null explicitly retires a composition reference, never a real skill tree or activation entry. */
+    readonly references?: Readonly<Record<string, string | null>>;
+    readonly digests?: Readonly<Record<string, string>>;
+    readonly packs?: Readonly<Record<string, {
+        readonly name: string;
+        readonly version: string;
+    }>>;
+    readonly wrappers?: Readonly<Record<string, {
+        readonly name: string;
+        readonly ownedPaths: readonly string[];
+    }>>;
+    readonly manifests?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+export interface MigrationOptions extends RegistryOptions, LockOptions {
+    /** Preview is the default. Only true authorizes publication. */
+    readonly apply?: boolean;
+    /** No scope is selected from the current working directory. */
+    readonly scope?: "global" | "project";
+    readonly project?: string;
+    readonly profile?: string;
+    readonly hermesRoot?: string;
+    readonly mapping?: MigrationMapping;
+    readonly sourcesFile?: string;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}
+export interface MigrationItem {
+    readonly id: string;
+    readonly area: "catalog" | "composition" | "manifest" | "activation" | "profile" | "sources";
+    readonly action: string;
+    readonly path: string;
+    readonly target?: string;
+    readonly state: "ready" | "blocked" | "verified" | "preserved";
+    readonly beforeDigest?: string;
+    readonly afterDigest?: string;
+    readonly details: readonly string[];
+    readonly dependsOn: readonly string[];
+}
+/** Shared internal section result; the public result also identifies the selected registry. */
+export interface MigrationSectionResult {
+    readonly items: readonly MigrationItem[];
+    readonly applied: readonly string[];
+    readonly receipts: readonly string[];
+}
+export interface MigrationResult extends MigrationSectionResult {
+    readonly registry: RegistrySelection | null;
+    readonly apply: boolean;
+    readonly targets: readonly string[];
+}

package/dist/core/migration.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationOptions, MigrationResult } from "./migration-types.js";
+import { type ResultEnvelope } from "./result.js";
+/** Explicit, resumable conversion. No target scope is inferred from the caller's directory. */
+export declare function migrate(input?: MigrationOptions): Promise<ResultEnvelope<MigrationResult | null>>;

package/dist/core/packs.d.ts

@@ -0,0 +1,8 @@
+import type { CompositionMutationData, CompositionOptions, PackListData, PackShowData } from "./composition-types.js";
+import { type ResultEnvelope } from "./result.js";
+export declare function listPacks(options?: CompositionOptions): Promise<ResultEnvelope<PackListData | null>>;
+export declare function showPack(ref: string, options?: CompositionOptions): Promise<ResultEnvelope<PackShowData | null>>;
+export declare function verifyPack(ref: string, options?: CompositionOptions): Promise<ResultEnvelope<PackShowData | null>>;
+export declare function createPack(name: string, version: string, options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;
+export declare function addPackSkills(ref: string, names: readonly string[], options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;
+export declare function removePackSkills(ref: string, names: readonly string[], options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;

package/dist/core/profile-discovery.d.ts

@@ -0,0 +1,15 @@
+import type { HermesRootSelection, ProfileDiscovery, ProfileLocation, ProfileOptions } from "./profile-types.js";
+export declare function validateProfileName(name: string): void;
+export declare function checkProfileSignal(options: Pick<ProfileOptions, "signal">): void;
+/** Keep discovery, selection and receipt context on the same expanded home/cwd. */
+export declare function normalizeProfileOptions(options?: ProfileOptions): ProfileOptions & {
+    readonly home: string;
+    readonly cwd: string;
+};
+/** Hermes treats HERMES_HOME beneath profiles/NAME as a profile, before resolving its symlink. */
+export declare function discoverProfileRoot(options?: ProfileOptions): Promise<HermesRootSelection>;
+export declare function discoverProfile(name: string, options?: ProfileOptions): Promise<ProfileLocation>;
+/** Discovery reads no profile configuration, skill content, sticky selection or project manifest. */
+export declare function discoverProfiles(options?: ProfileOptions): Promise<ProfileDiscovery>;
+/** Guard root identity across planning and mutation; child changes are guarded by the applicator. */
+export declare function assertProfileIdentity(profile: ProfileLocation): Promise<void>;

package/dist/core/profile-state.d.ts

@@ -0,0 +1,27 @@
+import { type ReceiptOptions, type ReceiptSnapshot } from "./activation-state.js";
+import type { EntryIdentity, SourceRevision } from "./activation-types.js";
+import type { ProfileLocation } from "./profile-types.js";
+export interface ProfileJournal {
+    readonly id: string;
+    readonly name: string;
+    readonly stage: string;
+    readonly parked: string;
+    readonly previous?: EntryIdentity;
+    readonly next?: EntryIdentity;
+}
+export interface ProfileData {
+    readonly version: 1;
+    readonly root: EntryIdentity | null;
+    readonly project: string | null;
+    readonly sources: readonly SourceRevision[];
+    readonly links: Readonly<Record<string, EntryIdentity>>;
+    readonly pending?: ProfileJournal;
+}
+export interface ProfileState {
+    readonly snapshot: ReceiptSnapshot<ProfileData>;
+    readonly data: ProfileData;
+}
+export declare function emptyProfileData(): ProfileData;
+/** Profiles share atomic state IO, while their namespace, payload, and ownership rules remain separate. */
+export declare function readProfileState(profile: ProfileLocation, options?: ReceiptOptions): Promise<ProfileState>;
+export declare function writeProfileState(previous: ProfileState, data: ProfileData): Promise<ProfileState>;

package/dist/core/profile-sync.d.ts

@@ -0,0 +1,40 @@
+import { type Entry } from "./activation-ownership.js";
+import type { SourceRevision } from "./activation-types.js";
+import { type ProfileData, type ProfileState } from "./profile-state.js";
+import type { ProfileLocation, ProfileOptions, ProfileShowResult, ProfileSyncOptions, ProfileSyncResult } from "./profile-types.js";
+import { type Diagnostic, ExitCode, type ResultEnvelope } from "./result.js";
+import type { ResolvedScope, SkillOrigin } from "./selection.js";
+interface Desired {
+    readonly name: string;
+    readonly target: string;
+    readonly registry: string;
+    readonly origins: readonly SkillOrigin[];
+    readonly winner: "global" | "project";
+}
+interface Projection {
+    readonly project: string;
+    readonly desired: readonly Desired[];
+    readonly scopes: readonly ResolvedScope[];
+    readonly sources: readonly SourceRevision[];
+    readonly findings: readonly Diagnostic[];
+}
+interface ProfileWork {
+    readonly profile: ProfileLocation;
+    readonly state: ProfileState;
+    readonly root: Entry | undefined;
+    readonly projection: Projection;
+    readonly next: ProfileData;
+    readonly result: ProfileShowResult;
+    readonly options: ProfileOptions;
+}
+export interface ProfileInspection {
+    readonly result: ProfileShowResult;
+    readonly findings: readonly Diagnostic[];
+    readonly exit: ExitCode;
+    readonly state: ProfileState | null;
+    readonly work: ProfileWork | null;
+}
+/** Inspect existing profile content even when its source declarations cannot be resolved. */
+export declare function inspectProfile(profile: ProfileLocation, options?: ProfileOptions): Promise<ProfileInspection>;
+export declare function runProfileSync(name: string, options: ProfileSyncOptions): Promise<ResultEnvelope<ProfileSyncResult | null>>;
+export {};

package/dist/core/profile-types.d.ts

@@ -0,0 +1,88 @@
+import type { LockOptions } from "./lock.js";
+import type { Diagnostic } from "./result.js";
+import type { RegistryOptions, SkillOrigin } from "./selection.js";
+export interface ProfileOptions extends RegistryOptions, LockOptions {
+    readonly hermesRoot?: string;
+    readonly project?: string;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}
+export interface ProfileSyncOptions extends ProfileOptions {
+    readonly project: string;
+    readonly dryRun?: boolean;
+}
+export interface HermesRootSelection {
+    /** Expanded absolute spelling selected before following any profile symlink. */
+    readonly path: string;
+    readonly root: string | null;
+    readonly source: "argument" | "environment" | "default";
+}
+export interface ProfileLocation {
+    readonly name: string;
+    /** Hermes-visible profile path; root is its canonical directory target. */
+    readonly path: string;
+    readonly root: string;
+    readonly skillsRoot: string;
+    readonly rootSymlink: boolean;
+    readonly skills: {
+        readonly kind: "missing" | "directory" | "symlink" | "file" | "other";
+        readonly rawTarget: string | null;
+        readonly target: string | null;
+    };
+}
+export interface ProfileDiscovery {
+    readonly hermesRoot: HermesRootSelection;
+    readonly profiles: readonly ProfileLocation[];
+    readonly findings: readonly Diagnostic[];
+}
+export interface ProfileCandidate {
+    readonly name: string;
+    readonly path: string;
+    readonly target: string;
+    readonly origins: readonly SkillOrigin[];
+    readonly state: "create" | "update" | "unchanged" | "shadowed";
+    readonly winner: "global" | "project" | "profile";
+}
+export interface ProfileLocalEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: "directory" | "file" | "symlink" | "other";
+    readonly rawTarget: string | null;
+    readonly target: string | null;
+    readonly shadows: boolean;
+}
+export interface ProfileChange {
+    readonly action: "mkdir" | "create" | "update" | "prune" | "release" | "write-receipt" | "recover";
+    readonly name?: string;
+    readonly path: string;
+    readonly target?: string;
+}
+export interface ProfileSummary {
+    readonly profile: ProfileLocation;
+    readonly project: string | null;
+    readonly receiptPath: string | null;
+    readonly projection: "unmanaged" | "managed" | "pending" | "invalid";
+    readonly counts: {
+        readonly managed: number | null;
+        readonly local: number;
+    };
+}
+export interface ProfileListResult {
+    readonly hermesRoot: HermesRootSelection;
+    readonly profiles: readonly ProfileSummary[];
+}
+export interface ProfileShowResult {
+    readonly profile: ProfileLocation;
+    readonly project: string | null;
+    readonly receiptPath: string | null;
+    readonly managed: readonly ProfileCandidate[] | null;
+    readonly preserved: readonly ProfileLocalEntry[];
+    readonly changes: readonly ProfileChange[];
+    readonly pending: boolean;
+}
+export interface ProfileSyncResult extends ProfileShowResult {
+    readonly project: string;
+    readonly dryRun: boolean;
+    readonly applied: readonly ProfileChange[];
+}

package/dist/core/profiles.d.ts

@@ -0,0 +1,6 @@
+import type { ProfileListResult, ProfileOptions, ProfileShowResult, ProfileSyncOptions, ProfileSyncResult } from "./profile-types.js";
+import { type ResultEnvelope } from "./result.js";
+/** List configured profiles and read-only projection observations without choosing an ambient project. */
+export declare function listProfiles(options?: ProfileOptions): Promise<ResultEnvelope<ProfileListResult | null>>;
+export declare function showProfile(name: string, options?: ProfileOptions): Promise<ResultEnvelope<ProfileShowResult | null>>;
+export declare function syncProfile(name: string, options: ProfileSyncOptions): Promise<ResultEnvelope<ProfileSyncResult | null>>;

package/dist/core/reconciliation-types.d.ts

@@ -0,0 +1,36 @@
+import type { LockOptions } from "./lock.js";
+import type { ResolveOptions, ScopeName } from "./selection.js";
+export interface SyncOptions extends ResolveOptions, LockOptions {
+    readonly dryRun?: boolean;
+    readonly exitCode?: boolean;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}
+export interface SyncChange {
+    readonly scope: ScopeName;
+    readonly action: "create-directory" | "create-link" | "replace-link" | "remove-link" | "replace-root" | "write-receipt" | "recover";
+    readonly path: string;
+    readonly target?: string;
+}
+export interface SyncScopePlan {
+    readonly scope: ScopeName;
+    readonly root: string;
+    readonly activationRoot: string;
+    readonly mode: "composed" | "pack";
+    readonly skills: readonly {
+        readonly name: string;
+        readonly path: string;
+    }[];
+    readonly receiptPath: string;
+    readonly changes: readonly SyncChange[];
+}
+export interface SyncPlan {
+    readonly writeScopes: readonly ScopeName[];
+    readonly scopes: readonly SyncScopePlan[];
+    readonly changes: readonly SyncChange[];
+}
+export interface SyncResult extends SyncPlan {
+    readonly dryRun: boolean;
+    readonly applied: readonly SyncChange[];
+}

package/dist/core/reconciliation.d.ts

@@ -0,0 +1,47 @@
+import { type ReceiptOptions, type ReceiptSnapshot } from "./activation-state.js";
+import type { ActivationData, ActivationJournal, EntryIdentity, OwnedNode, SourceRevision } from "./activation-types.js";
+import type { SyncChange, SyncOptions, SyncPlan, SyncResult, SyncScopePlan } from "./reconciliation-types.js";
+import { type Diagnostic, type ResultEnvelope } from "./result.js";
+import type { Resolution, ResolvedScope } from "./selection.js";
+interface Operation {
+    readonly path: string;
+    readonly previous?: OwnedNode;
+    readonly target?: string;
+    readonly children?: ReadonlyMap<string, string>;
+    readonly changes: readonly SyncChange[];
+}
+interface Recovery {
+    readonly journal: ActivationJournal;
+    readonly published: boolean;
+    readonly restore: boolean;
+    readonly data: ActivationData;
+}
+interface ScopeWork {
+    readonly options: SyncOptions;
+    readonly scope: ResolvedScope;
+    readonly snapshot: ReceiptSnapshot<ActivationData>;
+    readonly receiptOptions: ReceiptOptions;
+    readonly data: ActivationData;
+    readonly sources: readonly SourceRevision[];
+    readonly recovery?: Recovery;
+    readonly directories: ReadonlyMap<string, EntryIdentity>;
+    readonly missingDirectories: readonly string[];
+    readonly operations: readonly Operation[];
+    readonly plan: SyncScopePlan;
+}
+/** Internal only: create and consume inside the activation ownership lock. */
+export interface PreparedSync {
+    readonly plan: SyncPlan;
+    readonly scopes: readonly ScopeWork[];
+    readonly findings: readonly Diagnostic[];
+    readonly resolution: Resolution;
+}
+/** Internal shared revision evidence for scope and profile receipts. */
+export declare function sourceRevision(kind: SourceRevision["kind"], path: string): Promise<SourceRevision>;
+/** Read-only internal preparation; callers must not retain it across lock acquisitions. */
+export declare function prepareSyncUnlocked(options?: SyncOptions, proposed?: ReadonlyMap<string, unknown>, expected?: ReadonlyMap<string, unknown>): Promise<PreparedSync>;
+/** Internal C06 boundary: caller holds the activation lock; this function re-resolves intent itself. */
+export declare function reconcileUnlocked(options?: SyncOptions, expected?: ReadonlyMap<string, unknown>): Promise<ResultEnvelope<SyncResult | null>>;
+export declare function planSync(options?: SyncOptions): Promise<ResultEnvelope<SyncPlan | null>>;
+export declare function sync(options?: SyncOptions): Promise<ResultEnvelope<SyncResult | null>>;
+export {};

package/dist/core/resolution.d.ts

@@ -0,0 +1,6 @@
+import { type ResultEnvelope } from "./result.js";
+import type { Resolution, ResolveOptions } from "./selection.js";
+/** Resolve intent offline. No manifests, catalog definitions, or activation paths are written. */
+export declare function resolveSelection(options?: ResolveOptions): Promise<ResultEnvelope<Resolution | null>>;
+/** Internal read-only preview: substitute only named manifests in discovered scopes. */
+export declare function resolveSelectionWithManifests(options?: ResolveOptions, proposed?: ReadonlyMap<string, unknown>, expected?: ReadonlyMap<string, unknown>): Promise<ResultEnvelope<Resolution | null>>;

package/dist/core/result.d.ts

@@ -0,0 +1,37 @@
+/** Process exits shared by the CLI and importing consumers. */
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly FAILURE: 1;
+    readonly CONFIG: 2;
+    readonly REFUSED: 3;
+    readonly PARTIAL: 4;
+    readonly LOCK_BUSY: 5;
+    readonly DRIFT: 6;
+    readonly INTERRUPTED: 130;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+export declare const JSON_SCHEMA_VERSION: 2;
+export interface Diagnostic {
+    readonly code: `E_${string}` | `W_${string}` | `I_${string}`;
+    readonly severity: "error" | "warning" | "info";
+    readonly message: string;
+    readonly path?: string;
+    readonly fix?: string;
+    readonly scope?: string;
+    readonly name?: string;
+    readonly detail?: readonly string[];
+}
+export interface ResultEnvelope<T> {
+    readonly schema: typeof JSON_SCHEMA_VERSION;
+    readonly command: string;
+    readonly ok: boolean;
+    readonly exit: ExitCode;
+    readonly data: T;
+    readonly findings: readonly Diagnostic[];
+}
+export interface ResultOptions {
+    readonly exit?: ExitCode;
+    readonly findings?: readonly Diagnostic[];
+}
+/** Construct the wire result without formatting output or exiting the process. */
+export declare function makeResult<T>(command: string, data: T, { exit, findings }?: ResultOptions): ResultEnvelope<T>;

package/dist/core/selection-command-types.d.ts

@@ -0,0 +1,23 @@
+import type { SyncChange, SyncOptions } from "./reconciliation-types.js";
+import type { ScopeName } from "./selection.js";
+export type SelectionKind = "skill" | "set" | "pack";
+export interface SelectionOptions extends Omit<SyncOptions, "scope" | "exitCode"> {
+    readonly scope?: ScopeName;
+}
+export interface SelectionChange {
+    readonly scope: ScopeName;
+    readonly action: "write-manifest" | SyncChange["action"];
+    readonly path: string;
+    readonly target?: string;
+}
+export interface SelectionResult {
+    readonly scope: ScopeName;
+    readonly root: string;
+    readonly manifestPath: string;
+    readonly manifest: Readonly<Record<string, unknown>>;
+    readonly dryRun: boolean;
+    readonly changed: boolean;
+    readonly saved: boolean;
+    readonly changes: readonly SelectionChange[];
+    readonly applied: readonly SelectionChange[];
+}

package/dist/core/selection-commands.d.ts

@@ -0,0 +1,6 @@
+import { type ResultEnvelope } from "./result.js";
+import type { SelectionKind, SelectionOptions, SelectionResult } from "./selection-command-types.js";
+export declare function initScope(options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
+export declare function enableSelection(kind: SelectionKind, reference: string, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
+export declare function disableSelection(kind: SelectionKind, reference: string, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
+export declare function setInheritance(enabled: boolean, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;

package/dist/core/selection-manifest.d.ts

@@ -0,0 +1,18 @@
+import { SkillexError } from "./error.js";
+import type { SkillsManifest } from "./selection.js";
+export interface SelectionManifestSnapshot {
+    readonly root: string;
+    readonly path: string;
+    readonly exists: boolean;
+    readonly raw: Readonly<Record<string, unknown>> | null;
+    readonly manifest: SkillsManifest | null;
+}
+/** The declaration may already be saved even when later durability checks fail. */
+export declare class SelectionManifestWriteError extends SkillexError {
+    readonly published: boolean;
+    constructor(error: SkillexError, published: boolean);
+}
+/** Inspect one source declaration. Missing .agents/skills.json never creates anything. */
+export declare function readSelectionManifest(root: string): Promise<SelectionManifestSnapshot>;
+/** Validate and atomically publish while the caller holds the shared activation lock. */
+export declare function writeSelectionManifest(previous: SelectionManifestSnapshot, raw: Readonly<Record<string, unknown>>): Promise<SelectionManifestSnapshot>;

package/dist/core/selection.d.ts

@@ -0,0 +1,98 @@
+export type ScopeName = "global" | "project";
+export type WriteScope = "auto" | ScopeName | "both";
+export interface SkillSelection {
+    readonly name: string;
+}
+export interface SetSelection {
+    readonly name: string;
+    readonly include?: readonly string[];
+    readonly exclude: readonly string[];
+    readonly optional: boolean;
+}
+export interface PackSelection {
+    readonly name: string;
+    readonly version?: string;
+    readonly optional: boolean;
+}
+export interface SkillsManifest {
+    readonly path: string;
+    readonly scope?: ScopeName;
+    readonly inheritGlobal: boolean;
+    readonly registry?: string;
+    readonly skills: readonly SkillSelection[];
+    readonly sets: readonly SetSelection[];
+    readonly packs: readonly PackSelection[];
+    readonly exclude: readonly string[];
+}
+export interface ScopeLocation {
+    readonly scope: ScopeName;
+    readonly root: string;
+    readonly path: string;
+    readonly exists: boolean;
+}
+export interface ScopeDiscovery {
+    readonly global: ScopeLocation;
+    readonly project?: ScopeLocation;
+    readonly writeScopes: readonly ScopeName[];
+}
+export interface DiscoveryOptions {
+    readonly cwd?: string;
+    readonly home?: string;
+    readonly project?: string;
+    readonly scope?: WriteScope;
+}
+export interface RegistryOptions {
+    readonly registryRoot?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly home?: string;
+    readonly cwd?: string;
+    readonly registry?: string;
+    readonly installedRoot?: string;
+}
+export interface RegistrySelection {
+    readonly root: string;
+    readonly source: "argument" | "environment" | "cache" | "checkout" | "installed" | "fallback";
+    readonly searched: readonly string[];
+}
+export interface ResolveOptions extends DiscoveryOptions {
+    readonly registryRoot?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly installedRoot?: string;
+}
+export interface SkillOrigin {
+    readonly scope: ScopeName;
+    readonly manifest: string;
+    readonly kind: "skill" | "set" | "pack" | "inherit";
+    readonly reference: string;
+}
+export interface ResolvedBinding {
+    readonly name: string;
+    readonly path: string;
+    readonly origins: readonly SkillOrigin[];
+}
+export interface ExcludedBinding {
+    readonly name: string;
+    readonly origins: readonly SkillOrigin[];
+    readonly by: "scope" | "set";
+    readonly reference: string;
+}
+export interface ResolvedPack {
+    readonly name: string;
+    readonly version: string;
+    readonly path: string;
+    readonly skillsRoot: string;
+}
+export interface ResolvedScope {
+    readonly scope: ScopeName;
+    readonly root: string;
+    readonly manifest: SkillsManifest;
+    readonly registry: RegistrySelection;
+    readonly mode: "composed" | "pack";
+    readonly pack?: ResolvedPack;
+    readonly bindings: readonly ResolvedBinding[];
+    readonly excluded: readonly ExcludedBinding[];
+}
+export interface Resolution {
+    readonly scopes: readonly ResolvedScope[];
+    readonly writeScopes: readonly ScopeName[];
+}