@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/lib/skills.js

@@ -0,0 +1,191 @@
+/**
+ * Discovery and loading for the packaged Unity skills.
+ *
+ * Each skill is a directory bundle `<skillDir>/<name>/SKILL.md`, the same shape
+ * the harness filesystem provider reads, so the tree needs no transformation.
+ * Discovery parses frontmatter into a catalog candidate and every load re-reads
+ * the file, matching the harness convention that a skill body has no separate
+ * cache.
+ *
+ * One parse cache is shared by every agent's provider: discovery runs per agent
+ * scope, but the files belong to this package, so one cache keyed by path plus
+ * modification time and size keeps N agents from re-parsing the same documents
+ * while still noticing an edit.
+ *
+ * @module dsh-unity/lib/skills
+ */
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SKILL_NAME, parseInvocation, parseSkillMarkdown } from './frontmatter.js';
+import { readRequirements } from './requirements.js';
+/**
+ * Create a frontmatter cache keyed by path and file identity.
+ *
+ * @returns the cache.
+ */
+export function createParseCache() {
+    const entries = new Map();
+    return {
+        async read(file) {
+            let info;
+            try {
+                info = await stat(file);
+            }
+            catch {
+                return undefined;
+            }
+            const cached = entries.get(file);
+            if (cached !== undefined && cached.mtimeMs === info.mtimeMs && cached.size === info.size)
+                return cached.parsed;
+            const parsed = parseSkillMarkdown(await readFile(file, 'utf8'));
+            entries.set(file, { mtimeMs: info.mtimeMs, size: info.size, parsed });
+            return parsed;
+        },
+        clear() {
+            entries.clear();
+        },
+    };
+}
+/**
+ * Create a reader for one packaged skill directory.
+ *
+ * @param options - reader settings.
+ * @returns the reader.
+ */
+export function createUnitySkillReader(options) {
+    const { skillDir, providerName, source, rank, exclude, logger } = options;
+    const cache = options.parseCache ?? createParseCache();
+    /** Parse one skill bundle into a catalog candidate. */
+    async function parseBundle(entryName, dir) {
+        const file = join(dir, 'SKILL.md');
+        const parsed = await cache.read(file);
+        if (parsed === undefined) {
+            logger.warn(`unity skills: ${file} skipped because it has no YAML frontmatter`);
+            return undefined;
+        }
+        const { data } = parsed;
+        const skillName = typeof data.name === 'string' ? data.name.trim() : '';
+        const description = typeof data.description === 'string' ? data.description.trim() : '';
+        if (!SKILL_NAME.test(skillName) || description.length === 0) {
+            logger.warn(`unity skills: ${file} skipped because frontmatter requires a kebab-case name and a description`);
+            return undefined;
+        }
+        if (skillName !== entryName) {
+            logger.warn(`unity skills: ${file} declares name "${skillName}" but its folder is "${entryName}"`);
+        }
+        const whenToUse = typeof data.whenToUse === 'string' && data.whenToUse.trim() !== '' ? data.whenToUse.trim() : undefined;
+        const metadata = typeof data.metadata === 'object' && data.metadata !== null && !Array.isArray(data.metadata)
+            ? data.metadata
+            : undefined;
+        return {
+            name: skillName,
+            description,
+            ...(whenToUse === undefined ? {} : { whenToUse }),
+            invocation: parseInvocation(data),
+            requirements: readRequirements(data),
+            provider: providerName,
+            source,
+            rank,
+            locator: { dir, file },
+            resourceBase: { kind: 'directory', path: dir },
+            path: file,
+            ...(metadata === undefined ? {} : { metadata }),
+        };
+    }
+    return {
+        skillDir,
+        async list(lookup = {}) {
+            lookup.signal?.throwIfAborted();
+            let entries;
+            try {
+                entries = await readdir(skillDir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+                    return [];
+                throw error;
+            }
+            const candidates = [];
+            for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+                lookup.signal?.throwIfAborted();
+                if (exclude !== undefined && exclude.has(entry.name))
+                    continue;
+                const dir = join(skillDir, entry.name);
+                if (!(await isDirectory(dir, entry.isDirectory(), entry.isSymbolicLink())))
+                    continue;
+                try {
+                    const candidate = await parseBundle(entry.name, dir);
+                    if (candidate !== undefined)
+                        candidates.push(candidate);
+                }
+                catch (error) {
+                    lookup.signal?.throwIfAborted();
+                    logger.warn(`unity skills: ${dir} skipped: ${String(error)}`);
+                }
+            }
+            return candidates;
+        },
+        async load(candidate, lookup = {}) {
+            lookup.signal?.throwIfAborted();
+            const locator = candidate?.locator;
+            if (locator === undefined)
+                return undefined;
+            let raw;
+            try {
+                raw = await readFile(locator.file, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+                    return undefined;
+                throw error;
+            }
+            lookup.signal?.throwIfAborted();
+            const parsed = parseSkillMarkdown(raw);
+            if (parsed === undefined)
+                return undefined;
+            const { data, body } = parsed;
+            const skillName = typeof data.name === 'string' ? data.name.trim() : '';
+            const description = typeof data.description === 'string' ? data.description.trim() : '';
+            if (!SKILL_NAME.test(skillName) || description.length === 0)
+                return undefined;
+            const whenToUse = typeof data.whenToUse === 'string' && data.whenToUse.trim() !== '' ? data.whenToUse.trim() : undefined;
+            const metadata = typeof data.metadata === 'object' && data.metadata !== null && !Array.isArray(data.metadata)
+                ? data.metadata
+                : undefined;
+            return {
+                name: skillName,
+                description,
+                ...(whenToUse === undefined ? {} : { whenToUse }),
+                invocation: parseInvocation(data),
+                source,
+                provider: providerName,
+                resourceBase: { kind: 'directory', path: locator.dir },
+                path: await resolveDisplayPath(locator.file),
+                ...(metadata === undefined ? {} : { metadata }),
+                content: body,
+            };
+        },
+    };
+}
+/** Whether a directory entry is a directory, following symlinks. */
+async function isDirectory(dir, isDir, isLink) {
+    if (isDir)
+        return true;
+    if (!isLink)
+        return false;
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Prefer the real path for previews, falling back to the discovered path. */
+async function resolveDisplayPath(file) {
+    try {
+        return await realpath(file);
+    }
+    catch {
+        return file;
+    }
+}

package/lib/types/frontmatter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * YAML frontmatter reader for SKILL.md files.
+ *
+ * The skill documents use a small, well-understood subset of YAML, so the plugin
+ * carries its own reader instead of a parser dependency: the package must install
+ * with no build-time or run-time third-party code. Supported syntax:
+ *
+ * - top-level `key: value` mappings, including nested block mappings
+ *   (`required_packages`, `metadata`);
+ * - block sequences (`allowed-tools` followed by `- item` lines);
+ * - flow sequences (`modes: [agent, ask]`);
+ * - plain, single-quoted, and double-quoted scalars;
+ * - literal (`|`, `|-`, `|+`) and folded (`>`, `>-`, `>+`) block scalars;
+ * - full-line comments and inline ` #` comments on plain scalars.
+ *
+ * Scalars resolve through the YAML 1.2 core schema, matching what a full parser
+ * would produce for these documents. The invocation policy uses the registry's
+ * strict boolean grammar. A value this reader cannot represent is reported as a
+ * syntax error so the caller can skip the skill instead of advertising a wrong
+ * description.
+ *
+ * @module dsh-unity/lib/frontmatter
+ */
+/** A parsed YAML scalar, sequence, or mapping. */
+export type YamlValue = string | number | boolean | null | YamlValue[] | YamlMapping;
+/** A parsed YAML mapping. */
+export interface YamlMapping {
+    [key: string]: YamlValue;
+}
+/** Parsed frontmatter plus the Markdown body that follows it. */
+export interface ParsedSkill {
+    readonly data: YamlMapping;
+    readonly body: string;
+}
+/** The two invocation controls the registry understands. */
+export interface InvocationPolicy {
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+}
+/** Kebab-case grammar shared by the harness skill registry. */
+export declare const SKILL_NAME: RegExp;
+/**
+ * Split a Markdown document into its YAML frontmatter block and body.
+ *
+ * @param raw - complete file text.
+ * @returns the frontmatter source and body, or `undefined` without a fence.
+ */
+export declare function splitFrontmatter(raw: string): {
+    yaml: string;
+    body: string;
+} | undefined;
+/**
+ * Parse a SKILL.md document into frontmatter fields and body.
+ *
+ * @param raw - complete file text.
+ * @returns parsed frontmatter and the trimmed body, or `undefined` without a fence.
+ * @throws {SyntaxError} when the frontmatter is not the supported YAML subset.
+ */
+export declare function parseSkillMarkdown(raw: string): ParsedSkill | undefined;
+/**
+ * Parse the supported YAML subset into a plain value.
+ *
+ * @param source - YAML text without the surrounding fences.
+ * @returns a mapping, sequence, scalar, or `null` for a `key:` without a value.
+ * @throws {SyntaxError} on indentation this subset cannot represent.
+ */
+export declare function parseYamlSubset(source: string): YamlValue;
+/**
+ * Read a frontmatter boolean with the registry's strict grammar.
+ *
+ * @param data - parsed frontmatter.
+ * @param key - exact frontmatter key.
+ * @returns the value, or `undefined` when the key is absent.
+ * @throws {TypeError} when the key is present but is not a boolean spelling.
+ */
+export declare function frontmatterBoolean(data: YamlMapping, key: string): boolean | undefined;
+/**
+ * Resolve the invocation policy from frontmatter.
+ *
+ * @param data - parsed frontmatter.
+ * @returns the policy; absent keys keep both surfaces permitted.
+ * @throws {Error} when a legacy camelCase key is present.
+ */
+export declare function parseInvocation(data: YamlMapping): InvocationPolicy;

package/lib/types/gating.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Visibility decisions for one agent's skill catalog.
+ *
+ * The harness separates two questions about a skill: whether the model may see
+ * and load it (`modelInvocable`) and whether a person may invoke it by name
+ * (`userInvocable`). That split is exactly what project-aware gating needs: a
+ * skill that does not apply to the current project should leave the model's
+ * catalog to save context and avoid wrong suggestions, while staying reachable
+ * through an explicit `/skill-name` request.
+ *
+ * The rules here are intentionally conservative:
+ *
+ * - outside a Unity project only the configured workspace skills stay visible;
+ * - an unmet editor or package requirement hides the skill;
+ * - an *unknown* fact never hides a skill, so a broken manifest cannot silently
+ *   empty the catalog;
+ * - a skill the project provides itself is not offered by this plugin at all,
+ *   which is what keeps a project's own customization authoritative.
+ *
+ * @module dsh-unity/lib/gating
+ */
+import type { SkillCandidate } from './harness.ts';
+import type { ProjectFacts } from './project.ts';
+/** The settings that change a gating decision. */
+export interface GatingSettings {
+    readonly enforceRequirements: boolean;
+    readonly gateByProject: boolean;
+    readonly workspaceSkills: ReadonlySet<string>;
+}
+/** One skill left out of the model catalog, with the reason shown to the model. */
+export interface HiddenSkill {
+    readonly name: string;
+    readonly reason: string;
+}
+/** The catalog this plugin serves for one agent. */
+export interface GatedCatalog {
+    /** Every candidate, with `modelInvocable` adjusted for hidden skills. */
+    readonly candidates: SkillCandidate[];
+    readonly hidden: HiddenSkill[];
+    readonly projectOverridden: string[];
+}
+/** The model-visibility decision for a single skill. */
+export interface VisibilityDecision {
+    readonly modelInvocable: boolean;
+    readonly reason: string | undefined;
+}
+/**
+ * Decide the model-visibility of one skill candidate.
+ *
+ * @param candidate - candidate carrying its `requirements`.
+ * @param facts - project facts from `detectProject`.
+ * @param settings - resolved plugin settings.
+ * @returns the decision and, when hidden, a short human-readable reason.
+ */
+export declare function decideVisibility(candidate: SkillCandidate, facts: ProjectFacts | undefined, settings: GatingSettings): VisibilityDecision;
+/**
+ * Build the catalog this plugin serves for one agent.
+ *
+ * Every candidate stays in the list so a person can still invoke a hidden skill
+ * by name; only its `modelInvocable` flag changes. Candidates the project
+ * overrides are dropped instead, so the project's own copy wins the name.
+ *
+ * @param candidates - candidates from the skill reader.
+ * @param facts - project facts, or `undefined` outside a project.
+ * @param settings - resolved plugin settings.
+ * @param projectSkills - skill names the project supplies itself.
+ * @returns gated candidates and the reasons for every hidden skill.
+ */
+export declare function gateCatalog(candidates: readonly SkillCandidate[], facts: ProjectFacts | undefined, settings: GatingSettings, projectSkills?: ReadonlySet<string>): GatedCatalog;
+/**
+ * Render the runtime-context line contributed for one agent.
+ *
+ * Kept to one short paragraph: it is re-read on every prompt assembly, so it must
+ * describe facts the model cannot infer and nothing else.
+ *
+ * @param facts - project facts.
+ * @param hidden - gated-away skills.
+ * @returns the context text, or `undefined` when there is nothing to say.
+ */
+export declare function renderContext(facts: ProjectFacts | undefined, hidden: readonly HiddenSkill[]): string | undefined;

package/lib/types/harness.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Structural declarations for the harness surfaces this plugin uses.
+ *
+ * The package is a plugin bundle, not a harness package: it never imports
+ * `@deepseek-ai/*` at runtime, and it deliberately keeps no build-time dependency
+ * on them so a local checkout type-checks without a network install. The
+ * interfaces below transcribe the parts of the harness contracts that matter
+ * here — the skill registry provider contract, the prompt-context contribution,
+ * the agent-scope boundary, and the optional services reached through `ctx.get`.
+ *
+ * Each type names the harness contract it mirrors. When the harness changes one
+ * of them, this file is the single place to update.
+ *
+ * @module dsh-unity/lib/harness
+ */
+/** `SkillInvocationPolicy` from the `skills` service contract. */
+export interface SkillInvocationPolicy {
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+}
+/** What a skill declares about the project it needs. */
+export interface SkillRequirements {
+    readonly editor?: string;
+    readonly packages: ReadonlyArray<{
+        readonly name: string;
+        readonly range: string;
+    }>;
+}
+/** The opaque handle a provider hands back to the registry and receives again on load. */
+export interface SkillLocator {
+    readonly dir: string;
+    readonly file: string;
+}
+/** `SkillCandidate` — a catalog entry with its provider-private locator. */
+export interface SkillCandidate {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicy;
+    readonly requirements?: SkillRequirements;
+    readonly source: string;
+    readonly provider: string;
+    readonly rank: number;
+    readonly locator: SkillLocator;
+    readonly resourceBase: {
+        readonly kind: 'directory';
+        readonly path: string;
+    };
+    readonly path?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** `SkillDefinition` — a loaded body plus everything the candidate carried. */
+export interface SkillDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicy;
+    readonly source: string;
+    readonly provider: string;
+    readonly resourceBase: {
+        readonly kind: 'directory';
+        readonly path: string;
+    };
+    readonly path?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly content: string;
+}
+/** `SkillProviderControl` — the registration's lifecycle and cache invalidation. */
+export interface SkillProviderControl {
+    readonly signal: AbortSignal;
+    readonly invalidate: () => void;
+}
+/** Options the registry passes to discovery and loading. */
+export interface SkillLookupOptions {
+    readonly cwd?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+/** `SkillProvider` — what this plugin registers. */
+export interface SkillProvider {
+    readonly name: string;
+    list(options: SkillLookupOptions): Promise<readonly SkillCandidate[]>;
+    get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+}
+/** The `skills` registry surface this plugin touches. */
+export interface SkillsService {
+    registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
+}
+/** `PromptContext` from the `system-prompt` contract. */
+export interface PromptContext {
+    readonly name: string;
+    readonly order: number;
+    readonly text: string | ((context: unknown) => string);
+    readonly required?: boolean;
+    readonly interpolate?: boolean;
+}
+/** The `systemPrompt` registry surface this plugin touches. */
+export interface SystemPromptService {
+    context(context: PromptContext): () => void;
+}
+/** The `workingDirectory` service surface this plugin touches. */
+export interface WorkingDirectoryService {
+    get(session: SessionLike | undefined): string | undefined;
+}
+/** The `agents` service surface this plugin touches. */
+export interface AgentsService {
+    list(): AgentLike[];
+}
+/** The `subprocess` service surface this plugin touches. */
+export interface SubprocessService {
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+}
+/** Enough of a Session to read an identity and a fallback directory. */
+export interface SessionLike {
+    readonly id?: string;
+    readonly header?: {
+        readonly cwd?: string;
+    };
+    readonly cwd?: string;
+}
+/**
+ * The agent-scope boundary.
+ *
+ * Registrations made through this context land in the agent's own scope layer,
+ * which is what makes the provider win duplicate names and vary by project.
+ */
+export interface AgentContext {
+    get(name: string): unknown;
+}
+/** The agent surface this plugin touches. */
+export interface AgentLike {
+    readonly id?: string;
+    readonly session?: SessionLike;
+    readonly ctx?: AgentContext;
+}
+/** A logger with the two levels this plugin uses. */
+export interface Logger {
+    warn(message: string): void;
+    debug?(message: string): void;
+}
+/**
+ * The Cordis plugin context, narrowed to what `apply()` uses.
+ *
+ * `get(name)` is the optional-service accessor; `skills` is declared because the
+ * plugin imports it as a hard dependency.
+ */
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly skills: SkillsService;
+    get(name: string): unknown;
+    on(event: string, listener: (payload: unknown) => unknown): () => void;
+    effect(create: () => () => void, label?: string): () => void;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Unity's curated skills as a DeepSeek Harness plugin.
+ *
+ * The package carries 34 skills under `skills/` and serves them through the
+ * harness skill registry. What distinguishes this from a directory of Markdown
+ * files is *where* and *how* they are served:
+ *
+ * - registration happens per agent, through that agent's own context, so this
+ *   provider lives in the agent's scope layer and its catalog can depend on the
+ *   project the agent is working in;
+ * - a Unity project is detected from the session's working directory, and skills
+ *   whose `required_editor_version` / `required_packages` cannot be met leave the
+ *   model's catalog while staying reachable by explicit name;
+ * - the detected project facts are contributed to the agent's runtime context, so
+ *   the model states the editor version and package situation instead of guessing;
+ * - the skill directory is watched, and a frontmatter membership change
+ *   invalidates the cached catalog instead of requiring a restart.
+ *
+ * @module @aqian0/dsh-unity
+ */
+import type { RegistrySettings } from './registry.ts';
+import type { ParseCache } from './skills.ts';
+import type { PluginContext } from './harness.ts';
+/** Loader row name. */
+export declare const name = "unity-skills";
+/** The skill registry this provider attaches to. */
+export declare const inject: string[];
+/** Provider name the registry lists the catalog under. */
+export declare const DEFAULT_PROVIDER_NAME = "unity";
+/**
+ * Default rank inside one scope layer. The catalog normally lands in the agent's
+ * own layer, where the nearest layer already wins duplicates; the rank only
+ * orders this provider against runtime (`ctx.skills.register()`) registrations,
+ * which use 250.
+ */
+export declare const DEFAULT_RANK = 240;
+/**
+ * Skills worth showing outside a Unity project: creating a project, driving the
+ * editor from the CLI, and managing packages are all meaningful before a project
+ * exists.
+ */
+export declare const DEFAULT_WORKSPACE_SKILLS: readonly string[];
+/** Row config accepted from the loader patch. */
+export interface PluginConfig {
+    readonly providerName?: string;
+    readonly rank?: number;
+    readonly skillDir?: string;
+    readonly exclude?: readonly string[];
+    readonly workspaceSkills?: readonly string[];
+    readonly gateByProject?: boolean;
+    readonly enforceRequirements?: boolean;
+    readonly injectContext?: boolean;
+    readonly watchSkills?: boolean;
+    readonly respectProjectRoots?: boolean;
+}
+/** Normalized settings, with the parse cache attached by {@link apply}. */
+export interface ResolvedSettings extends RegistrySettings {
+    readonly watchSkills: boolean;
+    parseCache: ParseCache | undefined;
+}
+/**
+ * Register the Unity skill provider on `ctx.skills`.
+ *
+ * @param ctx - Cordis plugin context; `skills` is injected.
+ * @param config - row config from the loader patch.
+ */
+export declare function apply(ctx: PluginContext, config?: PluginConfig): void;
+/**
+ * Validate row config into normalized settings.
+ *
+ * @param config - row config from the loader patch.
+ * @returns normalized settings.
+ * @throws {TypeError} when a field is present but unusable.
+ */
+export declare function resolveSettings(config: PluginConfig): ResolvedSettings;

package/lib/types/project.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Unity project detection.
+ *
+ * A session's working directory may sit anywhere inside a Unity project, so the
+ * plugin walks up to the nearest ancestor that carries
+ * `ProjectSettings/ProjectVersion.txt` — the marker Unity itself writes and the
+ * same file that names the editor version. From there it reads the facts that
+ * decide whether a skill applies: the editor version, the UPM packages in
+ * `Packages/manifest.json`, the inferred render pipeline, whether an Editor holds
+ * the project lock, and whether the `unity` CLI is on `PATH`.
+ *
+ * Everything here is read-only and best-effort. A partially readable project is
+ * reported with the fields it does have; a directory that is not a Unity project
+ * reports `undefined` rather than throwing.
+ *
+ * @module dsh-unity/lib/project
+ */
+import { readdir, stat } from 'node:fs/promises';
+/** Relative path of the file that identifies a Unity project root. */
+export declare const PROJECT_MARKER: string;
+/** Render pipeline inferred from the installed packages. */
+export type RenderPipeline = 'hdrp' | 'urp' | 'builtin';
+/** What detection learned about one project. */
+export interface ProjectFacts {
+    readonly root: string;
+    readonly editorVersion?: string;
+    readonly packages?: Map<string, string>;
+    readonly renderPipeline?: RenderPipeline;
+    readonly editorOpen: boolean;
+    readonly cliAvailable: boolean;
+}
+/** Collaborators a detection call can substitute, used by tests. */
+export interface DetectOptions {
+    readonly stat?: typeof stat;
+    readonly readFile?: (path: string) => Promise<string>;
+    readonly maxDepth?: number;
+    readonly resolveExecutable?: (command: string) => Promise<string | undefined>;
+}
+/**
+ * Find the nearest ancestor containing the Unity project marker.
+ *
+ * @param cwd - directory to start from.
+ * @param options - injectable filesystem and walk depth.
+ * @returns the absolute project root, or `undefined` when there is none.
+ */
+export declare function findProjectRoot(cwd: string, options?: DetectOptions): Promise<string | undefined>;
+/**
+ * Read the editor version from `ProjectVersion.txt`.
+ *
+ * @param text - file contents.
+ * @returns the version such as `6000.3.14f1`, or `undefined` when absent.
+ */
+export declare function parseProjectVersion(text: string): string | undefined;
+/**
+ * Read installed UPM packages from a manifest.
+ *
+ * @param text - `Packages/manifest.json` contents.
+ * @returns package id to version, or `undefined` when the manifest is not a mapping.
+ */
+export declare function parsePackages(text: string): Map<string, string> | undefined;
+/**
+ * Infer the render pipeline from installed packages.
+ *
+ * @param packages - installed packages, or `undefined` when unknown.
+ * @returns the pipeline name, or `undefined` when the package list is unknown.
+ */
+export declare function inferRenderPipeline(packages: Map<string, string> | undefined): RenderPipeline | undefined;
+/**
+ * Detect the Unity project that contains a directory.
+ *
+ * @param cwd - session working directory.
+ * @param options - injectable collaborators and walk depth.
+ * @returns project facts, or `undefined` outside a project.
+ */
+export declare function detectProject(cwd: string, options?: DetectOptions): Promise<ProjectFacts | undefined>;
+/**
+ * Skill names a project provides itself, which this plugin must not shadow.
+ *
+ * @param root - project root.
+ * @param options - injectable filesystem.
+ * @returns skill names found under the project skill roots.
+ */
+export declare function readProjectSkillNames(root: string, options?: {
+    readdir?: typeof readdir;
+    stat?: typeof stat;
+}): Promise<Set<string>>;
+/**
+ * A short, stable identity for a fact set, used to notice project changes.
+ *
+ * @param facts - detected facts.
+ * @returns a cache and comparison key.
+ */
+export declare function factsKey(facts: ProjectFacts | undefined): string;