dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/index.d.mts

@@ -1,118 +1,46 @@
-//#region src/provider.d.ts
+import { _ as ToolsHost, d as SkillProvider, f as SkillProviderControl, u as SkillInvocationPolicy } from "./host-contract-CUPSpeNk.mjs";
+import { LoadSkillResult, SkillResourceResult, SkillsHost, TOOL_NAME, createPstackSkillTool, readSkillResource, renderLoadedSkill } from "./skill.mjs";
 /**
- * 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.
+ * Package-internal resource locations.
  *
- * Design constraints this module enforces, from the port design document §8.1:
+ * Every shipped resource is read from `dist/` and nowhere else. The bundler writes the
+ * public entries at `dist/*.mjs` and shared helper chunks under `dist/internal/`, the
+ * pstack build writes `dist/pstack/`, and the packaging step writes `dist/skills/`.
  *
- * - 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.
+ * `PACKAGE_ROOT` therefore sits either one level above this module (an entry bundle in
+ * `dist/`) or two (a helper chunk in `dist/internal/`). Both layouts are known, so the
+ * directory name decides instead of probing for `dist` first and falling back.
  */
-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";
+/** Absolute path of the package root. */
+export declare const PACKAGE_ROOT: string;
+/** Absolute path of the generated pstack tree. */
+export declare const PORT_ROOT: string;
+/** Absolute path of the ported pstack skill directories. */
+export declare const SKILLS_ROOT: string;
+/** Absolute path of the vendored skill directories (`skills/vendored` at pack time). */
+export declare const VENDORED_SKILLS_ROOT: string;
+/** Absolute path of the skills authored in this repository. */
+export declare const AUTHORED_SKILLS_ROOT: string;
+/** Absolute path of the shipped harness mapping document. */
+export declare const HARNESS_DOC_PATH: string;
+/** One skill root the provider loads, labelled for collision errors. */
+interface SkillRoot {
   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>;
+  readonly label: string;
 }
+/** Every skill root, in load order. Recursive discovery handles each root's nesting. */
+export declare const SKILL_ROOTS: readonly SkillRoot[];
+/** Standard precedence rank for packaged skill providers. */
+export declare const BUNDLED_SKILL_RANK = 600;
+/** Default provider name. */
+export declare const DEFAULT_PROVIDER_NAME = "pstack";
 /** 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. */
+  /** Absolute skill directory; also the resource base. */
   readonly directory: string;
   /** Absolute `SKILL.md` path. */
   readonly instructionFile: string;
@@ -124,155 +52,38 @@ export declare class BundledSkillError extends Error {
   constructor(message: string);
 }
 /**
- * Read and validate every bundled skill below one directory.
+ * Read and validate every bundled skill under every root.
  *
- * 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.
+ * A skill name may appear in only one root; a duplicate is a packaging mistake, so it
+ * fails activation rather than letting one silently shadow the other. A root that does
+ * not exist is skipped, but an empty merged catalog fails.
  */
-export declare function loadBundledSkillIndex(skillsRoot: string): BundledSkillIndex;
+export declare function loadBundledSkillIndexes(roots: readonly SkillRoot[]): 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.
+ * The catalog is sorted by name so two installs present the same order, and it 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. */
+/** Cordis row name, used by Loader diagnostics. */
 export declare const name = "pstack";
-/** The provider needs the skill registry and nothing else. */
+/** The row needs the skill registry and the tool registry. */
 export declare const inject: string[];
-/** 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: {
+  readonly skills: SkillsHost & {
     registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
   };
+  readonly tools: ToolsHost;
+  /** Optional-service read for `systemPrompt`; absent is fine. */
+  get?(name: string): unknown;
 }
 /**
- * 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.
+ * Register the bundled pstack skill provider and the trusted loader.
  *
- * @param ctx - host context carrying the skill registry.
- * @param config - validated row config.
- * @throws {import("./provider.ts").BundledSkillError} when the bundled tree is malformed.
+ * @param ctx - host context carrying the skill and tool registries.
+ * @throws {import("./internal/skill-provider.ts").BundledSkillError} when the tree is malformed.
  */
-export declare function apply(ctx: PstackSkillHost, config?: PstackConfig): void;
-//#endregion
-export type { BundledSkill, BundledSkillIndex, SkillCandidate, SkillDefinition, SkillInvocationPolicy, SkillLookupOptions, SkillProvider, SkillProviderControl, SkillResourceBase, SkillSource, SkillSummary };
-//# sourceMappingURL=index.d.mts.map
+export declare function apply(ctx: PstackSkillHost): void;
+export { type LoadSkillResult, TOOL_NAME as PSTACK_SKILL_TOOL_NAME, type SkillResourceResult, type SkillRoot, createPstackSkillTool, readSkillResource, renderLoadedSkill };