@delorenj/skillex 0.3.1 → 0.4.0

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

@@ -10,9 +10,21 @@ export interface SkillMetadata {
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly provenance: Readonly<Record<string, unknown>> | null;
 }
+/** Who owns a definition's bytes: the catalog's all-skills/, or a repository (ADR-0002). */
+export interface SkillOwner {
+    readonly kind: "catalog" | "repo";
+    /** The declaring link source; null for catalog definitions. */
+    readonly source: string | null;
+    readonly repo: string | null;
+    /** The resolved checkout root on this machine; null for catalog definitions. */
+    readonly checkout: string | null;
+    /** The owning checkout's HEAD; null for catalog definitions or when Git cannot say. */
+    readonly commit: string | null;
+}
 export interface SkillDetails extends SkillMetadata {
     readonly name: string;
     readonly path: string;
+    readonly owner: SkillOwner;
     readonly references: readonly SkillReference[];
 }
 export interface ListSkillsOptions extends RegistryOptions {

package/dist/core/composition-mutation.d.ts

@@ -28,7 +28,7 @@ export interface CompositionPlan {
 }
 export declare function compositionError<T>(command: string, error: unknown): ResultEnvelope<T | null>;
 export declare function conflict(path: string, message?: string): never;
-export declare function requestedSkills(registry: string, names: readonly string[], path: string): Promise<Map<string, string>>;
+export declare function requestedSkills(registry: string, names: readonly string[], path: string, composition?: "set" | "pack"): Promise<Map<string, string>>;
 export declare function newPlan(registry: RegistrySelection, composition: CompositionDetails, dryRun: boolean): Promise<CompositionPlan>;
 export declare function planDirectory(plan: CompositionPlan, path: string): Promise<void>;
 export declare function inspectCanonicalLink(plan: CompositionPlan, path: string, target: string): Promise<boolean>;

package/dist/core/composition.d.ts

@@ -1,12 +1,23 @@
+import { type RegistryRef } from "./registry-context.js";
 import type { PackSelection, ResolvedPack } from "./selection.js";
-export declare function canonicalSkill(registry: string, name: string): Promise<string>;
+export interface CanonicalOptions {
+    /** Resolving a set or pack member: repo-owned names are refused in phase 1 (ADR-0002 §4). */
+    readonly composition?: "set" | "pack";
+}
+/** Phase 1: committed set and pack link farms cannot reference a machine-local checkout. */
+export declare function refuseOwnedMember(name: string, kind: "set" | "pack", path?: string): never;
+/**
+ * One name, one directory: all-skills/<name>, or the working tree of the link source that declares
+ * it. A name in both is refused (E_DIVERGENT_CANONICAL_NAME); neither ever shadows the other.
+ */
+export declare function canonicalSkill(registry: RegistryRef, name: string, options?: CanonicalOptions): Promise<string>;
 export declare function setMembers(registry: string, name: string): Promise<{
     path: string;
     names: string[];
 }>;
-export declare function setMemberTarget(registry: string, setPath: string, name: string): Promise<string>;
+export declare function setMemberTarget(registry: RegistryRef, setPath: string, name: string): Promise<string>;
 export interface PackInventory extends ResolvedPack {
     readonly names: readonly string[];
 }
 /** pack.toml owns membership; its generated skills/ links are checked by verify. */
-export declare function packInventory(registry: string, selection: PackSelection): Promise<PackInventory>;
+export declare function packInventory(registryRef: RegistryRef, selection: PackSelection): Promise<PackInventory>;

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

@@ -1,3 +1,4 @@
+import type { SkillOwner } from "./catalog-types.js";
 import type { SyncChange, SyncOptions } from "./reconciliation-types.js";
 import type { Diagnostic } from "./result.js";
 import type { ExcludedBinding, Resolution, ScopeName, SkillOrigin } from "./selection.js";
@@ -72,5 +73,7 @@ export interface SkillExplanation {
 export interface ExplainResult {
     readonly name: string;
     readonly canonical: string | null;
+    /** Owner of the canonical definition: all-skills/ or a repo-owned link source (ADR-0002). */
+    readonly owner: SkillOwner | null;
     readonly scopes: readonly SkillExplanation[];
 }

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

@@ -12,6 +12,9 @@ export interface DoctorSourceInspection {
     readonly packs: number;
     readonly provenance: number;
     readonly digestsChecked: number;
+    /** Skills declared by link sources (ADR-0002); each resolved one is hub-linted. */
+    readonly repoOwnedSkills: number;
+    readonly hubsLinted: number;
 }
 export interface ConfiguredLegacyWriter {
     readonly kind: "mise" | "service";

package/dist/core/host-identity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which machine wrote a receipt, journal or lock claim.
+ *
+ * `os.hostname()` is that answer on Linux, where the hostname is configured
+ * state. On macOS it is not: with no `scutil --get HostName` set (the default),
+ * `gethostname()` reports whatever name DHCP or Bonjour handed out last, and it
+ * changes on its own. On one Mac it went from `Mac.attlocal.net` to
+ * `HelloSub.local` between two runs, a few minutes apart, and every profile
+ * receipt written under the first name was refused as "another host's"
+ * (E_RECEIPT_INVALID). A lock claim left behind under the old name would be
+ * a "foreign host" claim that can never be reaped.
+ *
+ * macOS therefore names the machine by its hardware UUID (IOPlatformUUID),
+ * which survives renames, DHCP and Bonjour conflict renaming, and does not
+ * survive a move to a different Mac, which is the case receipts must refuse.
+ * When the UUID cannot be read, the hostname is used, as before.
+ */
+export interface HostIdentitySources {
+    readonly platform: string;
+    readonly hostname: () => string;
+    readonly platformUuid: () => string | null;
+}
+/** IOPlatformUUID from `ioreg`, or null. Never throws. */
+export declare function readDarwinPlatformUuid(): string | null;
+/** The identity for `sources`; pure, so every platform branch is testable anywhere. */
+export declare function resolveHostIdentity(sources: HostIdentitySources): string;
+/** This machine's stable identity (cached for the process). Linux: `os.hostname()`. */
+export declare function hostIdentity(): string;
+/**
+ * Every value a record written on THIS machine may carry: the stable identity,
+ * and the bare hostname earlier releases wrote. Accepting the hostname keeps a
+ * receipt written before the change valid exactly when it was valid before
+ * (the hostname still matches); it never accepts another machine's record that
+ * the old check would have refused.
+ */
+export declare function localHostIdentities(): readonly string[];

package/dist/core/hub-lint.d.ts

@@ -0,0 +1,83 @@
+import type { RegistryRef } from "./registry-context.js";
+import { type Diagnostic, ExitCode, type ResultEnvelope } from "./result.js";
+import type { RegistryOptions } from "./selection.js";
+/**
+ * Hub lint (ADR-0002 §6). Every rule is structural or an exact syntax match, so prose never
+ * produces a finding:
+ *
+ * - Links are Markdown inline links and reference definitions (`[x](path)`, `![x](path)`,
+ *   `[id]: path`) outside fenced code blocks and inline code spans. URLs (any `scheme:`), `//`
+ *   links and pure `#anchors` are ignored; `#fragment` and `?query` suffixes are stripped. An
+ *   absolute target (`/...` or `~...`) or one that resolves outside the hub is an escape; a
+ *   relative target that does not exist is missing. Paths written in prose or backticks are never
+ *   checked for existence.
+ * - Scanned files are every `*.md` in the hub except under its top-level `examples/`,
+ *   `templates/` and `assets/` directories, which may quote foreign Markdown.
+ * - Orphans are Markdown files under `references/` or `subskills/` that no scanned file links to
+ *   or names by path in an inline code span (relative to that file or to the hub root).
+ * - Skill references are the exact phrase "load the `name` hub" or "load the `name` skill"
+ *   (load/loads/loaded/loading, "the" optional), whose name must be a valid skill name that
+ *   resolves in all-skills/ or is declared by a link source. Other backticked words are prose.
+ */
+export interface HubLintOptions {
+    /** Line budget for SKILL.md before W_HUB_SIZE. */
+    readonly maxLines?: number;
+    /** Decide whether a skill name is known; omit to skip E_HUB_SKILL_REF_UNKNOWN. */
+    readonly knownSkill?: (name: string) => Promise<boolean>;
+    /**
+     * A wild hub lives in all-skills/ beside every other catalog skill and keeps its .source.yaml
+     * provenance there, so the repository rules (E_HUB_COUNT, W_HUB_PROVENANCE) do not apply.
+     */
+    readonly wild?: boolean;
+}
+export interface HubLintTarget {
+    /** The hub directory. */
+    readonly path: string;
+    /** The name a link source declares for this hub, when there is one. */
+    readonly declaredName?: string;
+    readonly source?: string;
+    readonly checkout?: string;
+}
+export interface HubLintData {
+    readonly name: string;
+    readonly path: string;
+    readonly source: string | null;
+    readonly checkout: string | null;
+    readonly lines: number | null;
+    readonly files: number;
+    readonly links: number;
+}
+export interface HubLintReport {
+    readonly data: HubLintData;
+    readonly findings: readonly Diagnostic[];
+}
+export declare const HUB_SIZE_LIMIT = 500;
+interface Line {
+    readonly number: number;
+    /** Line text with inline code spans blanked out. */
+    readonly prose: string;
+    /** Line text with code spans intact (for the explicit load phrase). */
+    readonly raw: string;
+    readonly spans: readonly string[];
+}
+/** Split Markdown into prose lines, skipping fenced code blocks and blanking inline code. */
+export declare function markdownLines(text: string): Line[];
+/** Markdown link targets on one prose line. */
+export declare function linkTargets(line: string): string[];
+/** A local path from a link target, or null for URLs, anchors and empty targets. */
+export declare function localTarget(target: string): string | null;
+/** Lint one hub directory. Structural failures are findings; only an absent hub throws. */
+export declare function lintHub(target: HubLintTarget, options?: HubLintOptions): Promise<HubLintReport>;
+/** Exit for lint findings: errors refuse, warnings are drift, info is clean. */
+export declare function hubLintExit(findings: readonly Diagnostic[]): ExitCode;
+/** Whether a name resolves in all-skills/ or is declared by any link source. */
+export declare function knownSkillIn(registry: RegistryRef): (name: string) => Promise<boolean>;
+/** Lint the hub of one repo-owned skill, using its declaration and resolved checkout. */
+export declare function lintOwnedSkill(registry: RegistryRef, name: string, options?: HubLintOptions): Promise<HubLintReport>;
+export interface LintSkillOptions extends RegistryOptions {
+    readonly path?: string;
+    readonly maxLines?: number;
+}
+/** `skillex skill lint <name>` or `skillex skill lint --path <hub>`. */
+export declare function lintSkill(name: string | undefined, options?: LintSkillOptions): Promise<ResultEnvelope<HubLintData | null>>;
+export {};

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

@@ -0,0 +1,54 @@
+import type { SkillOwner } from "./catalog-types.js";
+import { SkillexError } from "./error.js";
+import { type RegistryRef } from "./registry-context.js";
+import type { VendorCheckout, VendorSource } from "./vendor-types.js";
+/** A skill defined in its owning repository's working tree (ADR-0002), never in all-skills/. */
+export interface OwnedSkill {
+    readonly name: string;
+    /** Realpath of <checkout>/<subdir>/<name>: a real directory inside the checkout. */
+    readonly path: string;
+    readonly source: string;
+    readonly repo: string;
+    readonly checkout: string;
+    readonly checkoutRoot: string;
+    /** Realpath of <checkout>/<subdir>: the directory that holds the repository's one hub. */
+    readonly skillsRoot: string;
+    readonly subdir: string;
+}
+/** Link-mode declarations from all-skills/sources.toml. Names are known without any checkout. */
+export interface OwnedDeclarations {
+    readonly path: string;
+    readonly sources: readonly VendorSource[];
+    readonly owners: ReadonlyMap<string, VendorSource>;
+}
+export interface OwnedCheckout {
+    readonly source: VendorSource;
+    readonly checkout: VendorCheckout;
+}
+/** Declared repo-owned names. A selection memoizes them; a bare root reuses an unchanged read. */
+export declare function ownedDeclarations(registry: RegistryRef): Promise<OwnedDeclarations>;
+/** The link source that owns a name, or undefined for catalog and unknown names. */
+export declare function ownedSource(registry: RegistryRef, name: string): Promise<VendorSource | undefined>;
+/**
+ * Resolve and verify one link source's checkout. An absent checkout yields root null; a present
+ * checkout of the wrong repository, a stale one, or a non-root one is always refused.
+ */
+export declare function ownedCheckout(registry: RegistryRef, source: VendorSource): Promise<OwnedCheckout>;
+/**
+ * Resolve a repo-owned skill, or undefined when no link source declares the name. A declared name
+ * whose checkout is unavailable fails: E_SOURCE_CHECKOUT_MISSING for a required source and
+ * E_SKILL_MISSING for an optional one. Filesystem checks run on every call.
+ */
+export declare function ownedSkill(registry: RegistryRef, name: string): Promise<OwnedSkill | undefined>;
+/** Every declared repo-owned skill, resolved independently; failures are returned, not thrown. */
+export declare function ownedSkills(registry: RegistryRef): Promise<readonly {
+    readonly name: string;
+    readonly source: VendorSource;
+    readonly skill?: OwnedSkill;
+    readonly error?: SkillexError;
+}[]>;
+/** The owning repository's HEAD, for provenance displays. Null when Git cannot say. */
+export declare function ownedCommit(registry: RegistryRef, checkoutRoot: string): Promise<string | null>;
+export declare const catalogOwner: SkillOwner;
+/** The owner of a resolved definition path: its link source when it is repo-owned. */
+export declare function skillOwner(registry: RegistryRef, name: string, path: string): Promise<SkillOwner>;

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

@@ -3,11 +3,13 @@ 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";
+import type { RegistrySelection, ResolvedScope, SkillOrigin } from "./selection.js";
 interface Desired {
     readonly name: string;
     readonly target: string;
     readonly registry: string;
+    /** The selection that resolved this binding; repo-owned skills re-resolve through it. */
+    readonly selection: RegistrySelection;
     readonly origins: readonly SkillOrigin[];
     readonly winner: "global" | "project";
 }

package/dist/core/reconciliation.d.ts

@@ -3,7 +3,7 @@ import type { ActivationData, ActivationJournal, EntryIdentity, OwnedNode, Sourc
 import { type DerivationPreview } from "./derivation.js";
 import type { SyncChange, SyncOptions, SyncPlan, SyncResult, SyncScopePlan } from "./reconciliation-types.js";
 import { type Diagnostic, type ResultEnvelope } from "./result.js";
-import type { Resolution, ResolvedScope, SkillsManifest } from "./selection.js";
+import type { RegistrySelection, Resolution, ResolvedScope, SkillsManifest } from "./selection.js";
 interface Operation {
     readonly path: string;
     readonly previous?: OwnedNode;
@@ -20,6 +20,8 @@ interface Recovery {
 interface ScopeWork {
     readonly options: SyncOptions;
     readonly scope: ResolvedScope;
+    /** Every registry the resolution consulted; inherited bindings may come from another one. */
+    readonly registries: readonly RegistrySelection[];
     readonly snapshot: ReceiptSnapshot<ActivationData>;
     readonly receiptOptions: ReceiptOptions;
     readonly data: ActivationData;
@@ -39,6 +41,13 @@ export interface PreparedSync {
 }
 /** Internal shared revision evidence for scope and profile receipts. */
 export declare function sourceRevision(kind: SourceRevision["kind"], path: string): Promise<SourceRevision>;
+/**
+ * Revisions to compare a fresh plan against its receipt. A repo-owned hub is a live link into
+ * its owning checkout, so that repository's HEAD moving changes no link: a source that is not
+ * some registry's all-skills/ keeps its recorded commit for the comparison. The fresh commit
+ * is still written whenever the receipt is rewritten for any other reason.
+ */
+export declare function settledRevisions(next: readonly SourceRevision[], recorded: readonly SourceRevision[] | undefined, catalogRoots: ReadonlySet<string>): SourceRevision[];
 /**
  * Plan-only boundary for a set not yet materialized. Reuses every destination,
  * receipt, recovery and alias guard; only the on-disk set check is replaced by

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

@@ -0,0 +1,26 @@
+import type { RegistryOptions, RegistrySelection } from "./selection.js";
+/**
+ * The machine context a registry was discovered with. Repo-owned (link) sources resolve their
+ * checkouts per machine, so a lookup must use the same home, environment and working directory
+ * that selected the registry. Kept beside the selection, never inside it: selections are wire
+ * data, and this context is not.
+ */
+export interface RegistryContext {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly cwd: string;
+    readonly checkouts?: Readonly<Record<string, string>>;
+}
+/** A registry identity: a discovered selection, or a bare root path from older call sites. */
+export type RegistryRef = string | RegistrySelection;
+export declare function registryRoot(registry: RegistryRef): string;
+export declare function contextFromOptions(options: RegistryOptions & {
+    readonly checkouts?: Readonly<Record<string, string>>;
+}): RegistryContext;
+/** Called by registry discovery so later lookups through this selection share its context. */
+export declare function bindRegistryContext(selection: RegistrySelection, context: RegistryContext): void;
+/**
+ * A selection's own context; a bare root falls back to the most recent discovery of that root in
+ * this process, then to the process defaults.
+ */
+export declare function registryContext(registry: RegistryRef): RegistryContext;

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

@@ -1,5 +1,7 @@
 import { type Diagnostic } from "./result.js";
 import type { VendorCheckout, VendorOptions, VendorSource, VendorSourcesManifest } from "./vendor-types.js";
+/** The pinned version of a vendor-mode source; link sources never reach vendoring. */
+export declare function vendorVersion(source: VendorSource): string;
 export declare function checkVendorSignal(options: Pick<VendorOptions, "signal">): void;
 /** Load the owning catalog's declaration only; prepared migration files are never fallback input. */
 export declare function readVendorSources(options?: VendorOptions): Promise<VendorSourcesManifest>;

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

@@ -22,7 +22,10 @@ export interface VendorSourceSkill {
 export interface VendorSource {
     readonly name: string;
     readonly repo: string;
-    readonly version: string;
+    /** "vendor" copies a pinned commit into all-skills/; "link" exposes the checkout's working tree (ADR-0002). */
+    readonly mode: "vendor" | "link";
+    /** Required for vendor mode; optional and unused in link mode. */
+    readonly version: string | null;
     readonly checkout: string;
     readonly subdir: string;
     readonly membership: "explicit" | "discovery";
@@ -71,7 +74,7 @@ export interface VendorSkillStatus {
     readonly name: string;
     readonly path: string;
     readonly source: string;
-    readonly state: "ok" | "missing" | "unrecorded" | "invalid" | "modified" | "stale" | "unknown" | "recorded" | "orphaned" | "foreign";
+    readonly state: "ok" | "missing" | "unrecorded" | "invalid" | "modified" | "stale" | "unknown" | "recorded" | "orphaned" | "foreign" | "linked";
     readonly recordedCommit: string | null;
     readonly upstreamCommit: string | null;
     readonly recordedDigest: string | null;
@@ -99,6 +102,7 @@ export interface VendorStatusResult {
     readonly upstream: boolean;
     readonly sources: readonly {
         readonly name: string;
+        readonly mode: "vendor" | "link";
         readonly membership: "explicit" | "recorded";
         readonly checkout: VendorCheckout | null;
         readonly upstreamCommit: string | null;
@@ -107,6 +111,8 @@ export interface VendorStatusResult {
 }
 export interface VendorSourceResolution {
     readonly name: string;
+    /** Link sources are never vendored: they are reported as skipped and linked. */
+    readonly linked?: true;
     readonly checkout: string | null;
     readonly commit: string | null;
     readonly refKind: "branch" | "tag" | "commit" | "unknown" | null;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { freezeBmadPack } from "./core/bmad-freeze.js";
 export { explainBmadSkill, inspectBmadStatus } from "./core/bmad-status.js";
 export type { BmadCanonicalStatus, BmadCommandClient, BmadCommandFile, BmadCommandInventory, BmadExplainData, BmadExplainOptions, BmadForeignSkill, BmadFreezeChange, BmadFreezeData, BmadFreezeOptions, BmadProvenance, BmadReference, BmadSkillExplanation, BmadSkillInventory, BmadSkillManifestEntry, BmadSourceInstallation, BmadSourceModule, BmadStatusData, BmadStatusOptions, } from "./core/bmad-types.js";
 export { listSkills, showSkill } from "./core/catalog.js";
-export type { ListSkillsOptions, SkillDetails, SkillListData, SkillMetadata, SkillReference, SkillShowData, } from "./core/catalog-types.js";
+export type { ListSkillsOptions, SkillDetails, SkillListData, SkillMetadata, SkillOwner, SkillReference, SkillShowData, } from "./core/catalog-types.js";
 export { type CatalogChange, type CatalogWriteOptions, type CatalogWriteResult, type CreateSkillOptions, createSkill, importSkill, } from "./core/catalog-write.js";
 export { ClientIsolationCommand, type ClientIsolationOptions, type ClientIsolationPlan, type ClientIsolationResult, type ClientVerification, type ClientVerifyOptions, isolateClient, type OpenCodeRequest, unisolateClient, verifyClientIsolation, } from "./core/client-isolation.js";
 export type { CompositionChange, CompositionDetails, CompositionMutationData, CompositionOptions, PackListData, PackShowData, SetListData, SetShowData, } from "./core/composition-types.js";
@@ -16,6 +16,8 @@ export { discoverRegistry, discoverScopes } from "./core/discovery.js";
 export { doctor } from "./core/doctor.js";
 export type { ConfiguredLegacyWriter, DoctorOptions, DoctorResult, DoctorSourceInspection, DoctorWriterInspection, RunningLegacyWriter, } from "./core/doctor-types.js";
 export { SkillexError } from "./core/error.js";
+export { type HostIdentitySources, hostIdentity, localHostIdentities, resolveHostIdentity, } from "./core/host-identity.js";
+export { HUB_SIZE_LIMIT, type HubLintData, type HubLintOptions, type HubLintReport, type HubLintTarget, hubLintExit, knownSkillIn, type LintSkillOptions, linkTargets, lintHub, lintOwnedSkill, lintSkill, localTarget, markdownLines, } from "./core/hub-lint.js";
 export type { ExecutedImport, ImportExecution, PendingImport, PlannedSources, SourceEntry, SourceInventory, SourceOptions, SourceProvenance, } from "./core/import-sources.js";
 export { executeImports, inventorySkillRoot, inventorySource, membersFromInventories, planSourceMembers, provenanceFrom, releaseInventory, } from "./core/import-sources.js";
 export { type LockOptions, withLock } from "./core/lock.js";
@@ -23,6 +25,7 @@ export { isSkillName, isVersionComponent, parseManifest, readManifest } from "./
 export { migrate } from "./core/migration.js";
 export type { MigrationItem, MigrationMapping, MigrationOptions, MigrationResult, } from "./core/migration-types.js";
 export { type NormalizeOptions, normalizeScope } from "./core/normalization.js";
+export { type OwnedDeclarations, type OwnedSkill, ownedDeclarations, ownedSkill, ownedSkills, } from "./core/owned-sources.js";
 export { addPackSkills, type CreatePackOptions, createPack, listPacks, removePackSkills, showPack, verifyPack, } from "./core/packs.js";
 export type { HermesRootSelection, ProfileCandidate, ProfileChange, ProfileListResult, ProfileLocalEntry, ProfileLocation, ProfileOptions, ProfileShowResult, ProfileSummary, ProfileSyncOptions, ProfileSyncResult, } from "./core/profile-types.js";
 export { listProfiles, showProfile, syncProfile } from "./core/profiles.js";