dsh-pstack 0.1.0 → 0.2.0-beta.1

package/dist/index.d.mts

@@ -1,16 +1,278 @@
-import "@deepseek-ai/dsh-skill";
-import { Context } from "@deepseek-ai/cordis";
 //#region src/provider.d.ts
-export declare const name = "pstack";
-interface Config {
-  /** Extra skill directories to serve in addition to the bundled set. */
-  readonly extraSkillDirectories?: string[];
+/**
+ * The bundled pstack skill provider: one provider over the 55 generated skills
+ * that ship inside this package.
+ *
+ * The provider contract below mirrors `@deepseek-ai/dsh-skill` 0.2.1-rc.3, which
+ * was read through the host Inspect provider (`Service.listService` with
+ * `service: "skills"`) and the installed type declarations. It is restated here
+ * as a structural contract instead of imported so the plugin keeps zero runtime
+ * imports from the host packages: a workspace-directory bundle is linked from
+ * its checkout, where `@deepseek-ai/*` is not resolvable.
+ *
+ * Design constraints this module enforces, from the port design document §8.1:
+ *
+ * - The catalog is built once from the package assets and never watched. A
+ *   package update is the refresh boundary.
+ * - A malformed bundled skill fails the whole index instead of disappearing
+ *   from the catalog, so a broken asset is a startup error rather than a skill
+ *   users silently cannot see.
+ * - `get()` only accepts a locator this provider produced. Directory names are
+ *   never joined from caller input.
+ */
+/**
+ * Standard precedence rank for packaged skill providers, re-exported by
+ * `@deepseek-ai/dsh-skill` as `BUNDLED_SKILL_RANK`. Restated to keep the package
+ * dependency-free; a mismatch only changes which provider wins a name collision.
+ */
+export declare const BUNDLED_SKILL_RANK = 600;
+/** Default provider name used when the row does not override it. */
+export declare const DEFAULT_PROVIDER_NAME = "pstack";
+/** Origin bucket for a skill contribution. */
+type SkillSource = "project-dsh" | "project-agents" | "runtime" | "user-dsh" | "user-agents" | "custom" | "bundled" | (string & {});
+/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
+type SkillResourceBase = {
+  readonly kind: "directory";
+  readonly path: string;
+} | {
+  readonly kind: "url";
+  readonly url: string;
+} | {
+  readonly kind: "opaque";
+  readonly description: string;
+};
+/** Invocation controls shared by skill discovery consumers. */
+interface SkillInvocationPolicy {
+  /** Whether model-facing catalogs and loaders include this skill. */
+  readonly modelInvocable: boolean;
+  /** Whether human-facing command catalogs and loaders include this skill. */
+  readonly userInvocable: boolean;
+}
+/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
+interface SkillSummary {
+  /** Absolute instruction file path. */
+  readonly path?: string;
+  /** Kebab-case identifier used to address the skill. */
+  readonly name: string;
+  /** Short routing description shown by discovery consumers. */
+  readonly description: string;
+  /** Optional extra routing guidance. */
+  readonly whenToUse?: string;
+  /** Resolved model and user invocation controls. */
+  readonly invocation: SkillInvocationPolicy;
+  /** Discovery source that produced this skill. */
+  readonly source: SkillSource;
+  /** Provider that owns this skill body. */
+  readonly provider: string;
+  /** Provider-specific base for relative resources. */
+  readonly resourceBase?: SkillResourceBase;
+}
+/** Provider catalog entry used by the registry to merge and later load skills. */
+interface SkillCandidate extends SkillSummary {
+  /** Lower ranks win duplicate skill names. */
+  readonly rank: number;
+  /** Opaque provider-owned handle passed back to `provider.get()`. */
+  readonly locator: unknown;
+  /** Parsed optional metadata object from provider-specific skill frontmatter. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
+interface SkillDefinition extends SkillSummary {
+  /** Markdown instruction body after frontmatter removal. */
+  readonly content: string;
+  /** Parsed optional metadata object from frontmatter. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Caller context used for cwd-sensitive and abortable provider work. */
+interface SkillLookupOptions {
+  /** Workspace selector for the current lookup. */
+  readonly cwd?: string | undefined;
+  /** Abort discovery or loading work for the current caller. */
+  readonly signal?: AbortSignal | undefined;
+}
+/** Registration-scoped lifecycle capability handed to a provider factory. */
+interface SkillProviderControl {
+  /** Aborts when registration fails or the exact provider registration is disposed. */
+  readonly signal: AbortSignal;
+  /** Invalidate completed catalogs and notify consumers. */
+  readonly invalidate: () => void;
 }
+/** Provider interface for one source of skills. */
+interface SkillProvider {
+  /** Unique provider name in the `ctx.skills` registry. */
+  readonly name: string;
+  /** List available skill candidates for the current lookup context. */
+  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>;
+  /** Load a complete skill body for a previously listed candidate. */
+  readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>;
+}
+/** One validated on-disk bundled skill. */
+interface BundledSkill {
+  readonly name: string;
+  readonly description: string;
+  readonly whenToUse?: string;
+  readonly invocation: SkillInvocationPolicy;
+  /** Absolute skill directory; the candidate resource base. */
+  readonly directory: string;
+  /** Absolute `SKILL.md` path. */
+  readonly instructionFile: string;
+}
+/** Validated skills keyed by their absolute directory. */
+type BundledSkillIndex = ReadonlyMap<string, BundledSkill>;
+/** Raised when a bundled asset violates the provider contract. */
+export declare class BundledSkillError extends Error {
+  constructor(message: string);
+}
+/**
+ * Read and validate every bundled skill below one directory.
+ *
+ * This is the startup check: it runs before the provider registers, so a missing
+ * `SKILL.md`, an invalid frontmatter block, or a name that disagrees with its
+ * directory fails plugin activation with a path-qualified message instead of
+ * dropping a skill from the catalog.
+ *
+ * @param skillsRoot - absolute path of the directory holding the skill directories.
+ * @returns validated skills keyed by absolute skill directory, sorted by name.
+ * @throws {BundledSkillError} when the tree or any skill in it is malformed.
+ */
+export declare function loadBundledSkillIndex(skillsRoot: string): BundledSkillIndex;
+/**
+ * Build the provider over an already validated index.
+ *
+ * @param index - result of {@link loadBundledSkillIndex}.
+ * @param providerName - registry name for this provider.
+ * @returns a read-only provider whose catalog never changes until the package does.
+ */
+export declare function createPstackSkillProvider(index: BundledSkillIndex, providerName?: string): SkillProvider;
+/**
+ * Load the index and build the provider in one step, failing on a malformed tree.
+ *
+ * `apply()` uses this exact function, so the startup failure path and the
+ * provider used in tests are the same code.
+ *
+ * @param skillsRoot - absolute path of the bundled skill root.
+ * @param providerName - registry name for this provider.
+ * @returns the provider over the validated index.
+ */
+export declare function createPstackSkillProviderFromRoot(skillsRoot: string, providerName?: string): SkillProvider;
+//#endregion
+//#region src/paths.d.ts
+/**
+ * Package-internal resource locations.
+ *
+ * The provider reads generated assets in place instead of copying them into a
+ * user-visible skills directory, so every path here is resolved from this
+ * module's own location. The modules run from `src/` in a checkout and from the
+ * bundled `dist/index.mjs` in an installed package; both sit one directory below
+ * the package root, so the same expression holds in both cases.
+ */
+/** Absolute path of the package root: the repository in a checkout, the install directory after packing. */
+export declare const PACKAGE_ROOT: string;
+/** Absolute path of the generated, committed assets directory. */
+export declare const ASSETS_ROOT: string;
+/** Absolute path of the directory holding the 55 bundled skill directories. */
+export declare const SKILLS_ROOT: string;
+/** Absolute path of the generated harness mapping document. */
+export declare const HARNESS_DOC_PATH: string;
+//#endregion
+//#region src/frontmatter.d.ts
+/**
+ * Frontmatter parsing for pstack skills and agents.
+ *
+ * This is a deliberately small YAML subset, not YAML. It reads the shapes the
+ * upstream files use: plain scalars, single and double quotes, folded (`>` and
+ * `>-`) and literal (`|` and `|-`) blocks, comments, and blank lines. Nesting
+ * and multi-document streams are rejected rather than half-supported.
+ */
+export interface Frontmatter {
+  readonly data: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+export interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string;
+  readonly disableModelInvocation: boolean;
+  readonly userInvocable: boolean;
+  readonly whenToUse?: string;
+}
+export interface AgentFrontmatter {
+  readonly name: string;
+  readonly description: string;
+}
+export interface DroppedFrontmatterField {
+  readonly file: string;
+  readonly field: string;
+  readonly value: string;
+}
+export declare const SKILL_CONSUMED_FIELDS: readonly ["name", "description", "disable-model-invocation", "user-invocable", "whenToUse"];
+export declare const SKILL_DROPPED_FIELDS: readonly ["icon", "color", "paths"];
+export declare const AGENT_CONSUMED_FIELDS: readonly ["name", "description"];
+export declare const AGENT_DROPPED_FIELDS: readonly ["is_background"];
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+export declare class FrontmatterError extends Error {
+  constructor(message: string);
+}
+export declare function parseFrontmatter(source: string): Frontmatter;
+export declare function validateSkillFrontmatter(data: Readonly<Record<string, string>>, source: string): SkillFrontmatter;
+export declare function validateAgentFrontmatter(data: Readonly<Record<string, string>>, source: string): AgentFrontmatter;
+export declare function serializeSkillFrontmatter(data: SkillFrontmatter): string;
+export declare function serializeAgentFrontmatter(data: AgentFrontmatter): string;
+export declare function skillDroppedFields(data: Readonly<Record<string, string>>, source: string): readonly DroppedFrontmatterField[];
+export declare function agentDroppedFields(data: Readonly<Record<string, string>>, source: string): readonly DroppedFrontmatterField[];
+//#endregion
+//#region src/index.d.ts
+/** Plugin name used by Loader diagnostics for this row. */
+export declare const name = "pstack";
+/** The provider needs the skill registry and nothing else. */
 export declare const inject: string[];
-export declare function apply(ctx: Context, config?: Config): void;
-/** Absolute root of the generated skill tree, exported for doctor checks. */
-export declare const skillsRoot: string;
-export declare const skillsRootUrl: import("node:url").URL;
+/** Row configuration. Every field is optional; an omitted `config` is valid. */
+export interface PstackConfig {
+  /** Registry name for the provider; change it when two rows must coexist. */
+  readonly providerName?: string;
+}
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (string | number)[];
+}
+type StandardSchemaResult = {
+  readonly value: PstackConfig;
+  readonly issues?: undefined;
+} | {
+  readonly issues: readonly StandardSchemaIssue[];
+};
+/**
+ * Minimal Standard Schema validator for this plugin's row config.
+ *
+ * Cordis validates `apply()`'s second argument with `Config["~standard"]` and
+ * substitutes the returned `value`, so an omitted row `config` resolves to the
+ * documented defaults without a schemastery dependency.
+ */
+export declare const Config: {
+  "~standard": {
+    version: number;
+    vendor: string;
+    validate(value: unknown): StandardSchemaResult;
+  };
+};
+/** The slice of the Cordis context this plugin requires. */
+export interface PstackSkillHost {
+  readonly skills: {
+    registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
+  };
+}
+/**
+ * Register the bundled pstack skill provider.
+ *
+ * The bundled tree is validated before the provider registers, so a malformed
+ * `SKILL.md` fails plugin activation with a path-qualified error instead of
+ * removing one skill from the catalog. Nothing is copied out of the package and
+ * nothing is watched: reinstalling the package is the refresh boundary.
+ *
+ * @param ctx - host context carrying the skill registry.
+ * @param config - validated row config.
+ * @throws {import("./provider.ts").BundledSkillError} when the bundled tree is malformed.
+ */
+export declare function apply(ctx: PstackSkillHost, config?: PstackConfig): void;
 //#endregion
-export type { Config };
+export type { BundledSkill, BundledSkillIndex, SkillCandidate, SkillDefinition, SkillInvocationPolicy, SkillLookupOptions, SkillProvider, SkillProviderControl, SkillResourceBase, SkillSource, SkillSummary };
 //# sourceMappingURL=index.d.mts.map