@senior-skills/core 1.0.0

package/dist/application/update-skills.js

@@ -0,0 +1,115 @@
+import { AgentSkillsError, ErrorCode } from "../domain/errors.js";
+import { classifyChange } from "../domain/version.js";
+import { selectAgents } from "./agent-selection.js";
+import { InstallSkills } from "./install-skills.js";
+/**
+ * Update: detect current → resolve newest compatible → install atomically → report the diff.
+ *
+ * Implemented on top of {@link InstallSkills} rather than beside it. The install pipeline
+ * already does fetch/verify/validate/atomic-commit correctly; duplicating it here would mean
+ * two places to keep safe.
+ */
+export class UpdateSkills {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async execute(options) {
+        if (options.withSuggests === true && options.names.length === 0) {
+            throw new AgentSkillsError(ErrorCode.USAGE, '--with-suggests requires explicit skill names for update', {
+                hints: ['senior-skills update <skill> --with-suggests'],
+            });
+        }
+        const selection = await selectAgents(this.ctx, {
+            scope: options.scope,
+            ...(options.agents === undefined ? {} : { agents: options.agents }),
+            ...(options.projectRoot === undefined ? {} : { projectRoot: options.projectRoot }),
+            ...(options.startDir === undefined ? {} : { startDir: options.startDir }),
+        });
+        const current = new Map();
+        for (const target of selection.targets) {
+            for (const skill of await this.ctx.installer.list(target)) {
+                if (skill.unmanaged)
+                    continue;
+                const known = current.get(skill.name);
+                // When agents disagree, the oldest wins: updating brings every agent forward.
+                if (known === undefined || classifyChange(skill.version, known) !== 'downgrade') {
+                    current.set(skill.name, skill.version);
+                }
+            }
+        }
+        const names = options.names.length > 0 ? options.names : [...current.keys()].sort();
+        if (names.length === 0) {
+            throw new AgentSkillsError(ErrorCode.NOT_INSTALLED, 'Nothing to update', {
+                details: [
+                    '',
+                    'No senior-skills-managed skills were found in:',
+                    ...selection.targets.map((target) => `  ${target.displayName} (${target.scope}): ${target.root}`),
+                ],
+                hints: ['senior-skills install <skill>   to install one'],
+            });
+        }
+        for (const name of names) {
+            if (current.has(name))
+                continue;
+            throw new AgentSkillsError(ErrorCode.NOT_INSTALLED, `"${name}" is not installed`, {
+                hints: [`senior-skills install ${name}`, 'senior-skills list'],
+                data: { name },
+            });
+        }
+        // `^current` keeps update within the major by default; `--major` opens it up.
+        const refs = names.map((name) => {
+            const version = current.get(name);
+            return options.major === true ? `${name}@latest` : `${name}@^${version}`;
+        });
+        const install = await new InstallSkills(this.ctx).execute({
+            refs,
+            scope: options.scope,
+            ...(options.agents === undefined ? {} : { agents: options.agents }),
+            ...(options.projectRoot === undefined ? {} : { projectRoot: options.projectRoot }),
+            ...(options.startDir === undefined ? {} : { startDir: options.startDir }),
+            ...(options.registry === undefined ? {} : { registry: options.registry }),
+            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+            force: options.force === true,
+            ...(options.withSuggests === true
+                ? {
+                    withSuggests: true,
+                    suggestedVersionRanges: Object.fromEntries([...current].map(([name, version]) => [
+                        name,
+                        options.major === true ? 'latest' : `^${version}`,
+                    ])),
+                }
+                : {}),
+        });
+        const changes = [];
+        const additions = [];
+        const unchanged = [];
+        for (const skill of install.resolved) {
+            const from = current.get(skill.name);
+            const results = install.results.filter((result) => result.name === skill.name && (from === undefined || result.outcome === 'installed'));
+            if (from === undefined || results.length > 0) {
+                additions.push({
+                    name: skill.name,
+                    version: skill.version,
+                    suggestedBy: skill.suggestedBy ?? [],
+                    results,
+                });
+            }
+            if (from === undefined) {
+                // Keep the existing changes representation for JSON consumers; additions carry
+                // the explicit new-package plan, including skipped destinations and provenance.
+                changes.push({ name: skill.name, from: skill.version, to: skill.version, bump: 'same' });
+                continue;
+            }
+            const bump = classifyChange(from, skill.version);
+            if (bump === 'same') {
+                unchanged.push(skill.name);
+            }
+            else {
+                changes.push({ name: skill.name, from, to: skill.version, bump });
+            }
+        }
+        return { changes, additions, unchanged, install };
+    }
+}
+//# sourceMappingURL=update-skills.js.map

package/dist/application/update-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-skills.js","sourceRoot":"","sources":["../../src/application/update-skills.ts"],"names":[],"mappings":"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"}

package/dist/application/validate-package.d.ts

@@ -0,0 +1,27 @@
+import type { SkillPackage } from '../domain/skill-package.ts';
+import { type ValidationIssue, type ValidationReport } from '../domain/validation.ts';
+import type { AgentAdapter } from '../ports/agent-adapter.ts';
+import { type LoadPackageOptions } from './package-loader.ts';
+import type { ApplicationContext } from './context.ts';
+export interface ValidatePackageOptions extends LoadPackageOptions {
+    /** Directory name to compare against the manifest name, when validating from disk. */
+    readonly directoryName?: string;
+    /** Adapters whose agent-specific rules should also run. */
+    readonly adapters?: readonly AgentAdapter[];
+}
+/**
+ * Validates an already-loaded package.
+ *
+ * Reports every problem it can find rather than throwing on the first: an author fixing a
+ * package wants the whole list, and `install` wants to distinguish "unusable" from
+ * "imperfect".
+ */
+export declare function validatePackage(pkg: SkillPackage, options?: ValidatePackageOptions): ValidationReport;
+export declare function pathSafetyIssues(path: string): readonly ValidationIssue[];
+export interface ValidateDirectoryResult extends ValidationReport {
+    readonly pkg: SkillPackage;
+    readonly directory: string;
+}
+/** Loads a package from disk and validates it. The `validate` command in one call. */
+export declare function validateDirectory(ctx: ApplicationContext, directory: string, options?: ValidatePackageOptions): Promise<ValidateDirectoryResult>;
+//# sourceMappingURL=validate-package.d.ts.map

package/dist/application/validate-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-package.d.ts","sourceRoot":"","sources":["../../src/application/validate-package.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CAkLlB;AAqBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAazE;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,kBAAkB,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAUlC"}

package/dist/application/validate-package.js

@@ -0,0 +1,165 @@
+import { MANIFEST_FILENAME, entrypointFor } from "../domain/manifest.js";
+import { inspectPath } from "../domain/path-safety.js";
+import { normalize } from "../domain/posix-path.js";
+import { documentDescription, documentName, documentVersion } from "../domain/skill-document.js";
+import { IssueCollector, buildReport, } from "../domain/validation.js";
+import { isSemanticVersion } from "../domain/version.js";
+import { loadPackageFromDirectory } from "./package-loader.js";
+/**
+ * Validates an already-loaded package.
+ *
+ * Reports every problem it can find rather than throwing on the first: an author fixing a
+ * package wants the whole list, and `install` wants to distinguish "unusable" from
+ * "imperfect".
+ */
+export function validatePackage(pkg, options = {}) {
+    const issues = new IssueCollector();
+    const { manifest, document } = pkg;
+    const entrypoint = entrypointFor(manifest.kind);
+    // A workflow declares its identity in `export const meta`, every other kind in YAML
+    // frontmatter. Only the wording differs; the rules are the same.
+    const holder = manifest.kind === 'workflow' ? 'meta' : 'frontmatter';
+    // --- Identity agreement -------------------------------------------------------------
+    const docName = documentName(document);
+    if (docName === undefined) {
+        issues.error('skill.name.missing', entrypoint, `${capitalise(holder)} is missing "name"`, `Add name: "${manifest.name}" to the ${entrypoint} ${holder}`);
+    }
+    else if (docName !== manifest.name) {
+        issues.error('skill.name.mismatch', entrypoint, `${capitalise(holder)} name "${docName}" does not match manifest name "${manifest.name}"`, 'Both files and the directory name must agree');
+    }
+    if (options.directoryName !== undefined && options.directoryName !== manifest.name) {
+        issues.error('package.directory.mismatch', options.directoryName, `Directory is named "${options.directoryName}" but the ${manifest.kind} is named "${manifest.name}"`, `Rename the directory to "${manifest.name}"`);
+    }
+    const docVersion = documentVersion(document);
+    if (docVersion !== undefined) {
+        if (!isSemanticVersion(docVersion)) {
+            issues.error('skill.version.invalid', entrypoint, `${capitalise(holder)} version "${docVersion}" is not valid semver`);
+        }
+        else if (docVersion !== manifest.version) {
+            issues.error('skill.version.mismatch', entrypoint, `${capitalise(holder)} version "${docVersion}" does not match manifest version "${manifest.version}"`, `Keep them in sync, or drop the version from the ${holder}`);
+        }
+    }
+    const docDescription = documentDescription(document);
+    if (docDescription === undefined || docDescription === '') {
+        issues.error('skill.description.missing', entrypoint, `${capitalise(holder)} is missing "description"`, manifest.kind === 'workflow'
+            ? 'It is what search and info show for the workflow; it is required'
+            : 'Both Claude Code and Codex route on the description; it is required');
+    }
+    else if (collapse(docDescription) !== collapse(manifest.description)) {
+        // Adapters project the *manifest* description into the installed entrypoint, and the
+        // registry index carries only the manifest description. A divergent frontmatter one is
+        // therefore text no agent ever reads — including any trigger or boundary clause an
+        // author added there, which is how routing degrades silently.
+        //
+        // A warning and not an error: the package installs and works, so refusing it would be
+        // disproportionate. A registry that wants the stronger guarantee enforces it at index
+        // build time, where it can see its own packages — this repository does exactly that.
+        issues.warn('skill.description.mismatch', entrypoint, `${capitalise(holder)} description does not match the manifest description`, `Only the manifest description ships; make them identical, or edit ${MANIFEST_FILENAME} instead`);
+    }
+    // --- Body ---------------------------------------------------------------------------
+    if (document.body.trim().length < 40) {
+        issues.warn('skill.body.thin', entrypoint, manifest.kind === 'workflow'
+            ? 'The script body is nearly empty'
+            : 'The Markdown body is nearly empty', manifest.kind === 'workflow'
+            ? 'The body is the script the agent runs; meta alone does nothing'
+            : 'The body is what the agent loads once the package is selected');
+    }
+    // --- Declared files exist ------------------------------------------------------------
+    const present = new Set(pkg.files.map((file) => file.path));
+    for (const declared of manifest.files) {
+        const relative = normalize(declared.replace(/\/+$/, ''));
+        const isDirectory = declared.endsWith('/');
+        const satisfied = isDirectory
+            ? [...present].some((path) => path === relative || path.startsWith(`${relative}/`))
+            : present.has(relative);
+        if (!satisfied) {
+            issues.warn('package.files.missing', MANIFEST_FILENAME, `"${declared}" is declared in files but is not present`, 'Remove it from files, or add the file');
+        }
+    }
+    if (!present.has(entrypoint)) {
+        issues.error('package.entrypoint.missing', entrypoint, `Package has no ${entrypoint}`);
+    }
+    if (!present.has(MANIFEST_FILENAME)) {
+        issues.error('package.manifest.missing', MANIFEST_FILENAME, `Package has no ${MANIFEST_FILENAME}`);
+    }
+    // --- Path safety for every shipped file ----------------------------------------------
+    for (const file of pkg.files) {
+        issues.absorb(pathSafetyIssues(file.path));
+    }
+    // --- agentOverrides are allowlisted by the adapter that consumes them ------------------
+    const adapters = options.adapters ?? [];
+    for (const [agentId, override] of Object.entries(manifest.agentOverrides)) {
+        const adapter = adapters.find((candidate) => candidate.id === agentId);
+        if (adapters.length > 0 && adapter === undefined) {
+            issues.warn('manifest.agentOverrides.unknownAgent', `agentOverrides.${agentId}`, `No adapter is registered for agent "${agentId}"`, 'The override will be ignored');
+            continue;
+        }
+        if (adapter === undefined)
+            continue;
+        for (const key of Object.keys(override)) {
+            if (adapter.overrideKeys.includes(key))
+                continue;
+            issues.error('manifest.agentOverrides.unknownKey', `agentOverrides.${agentId}.${key}`, `Agent "${agentId}" does not accept the override key "${key}"`, `Accepted keys: ${adapter.overrideKeys.join(', ') || '(none)'}`);
+        }
+    }
+    // --- Declared compatibility refers to agents we know ----------------------------------
+    if (adapters.length > 0) {
+        for (const compatibility of manifest.compatibility) {
+            if (adapters.some((adapter) => adapter.id === compatibility.id))
+                continue;
+            issues.warn('manifest.compatibility.unknownAgent', `compatibility.agents.${compatibility.id}`, `Unknown agent id "${compatibility.id}"`, `Known: ${adapters.map((adapter) => adapter.id).join(', ')}`);
+        }
+    }
+    // --- Agent-specific rules -------------------------------------------------------------
+    for (const adapter of adapters) {
+        if (manifest.compatibility.length > 0 &&
+            !manifest.compatibility.some((entry) => entry.id === adapter.id)) {
+            continue;
+        }
+        issues.absorb(adapter.validate(pkg));
+    }
+    return issues.report();
+}
+/**
+ * Reports path-safety violations as validation issues.
+ *
+ * The rules themselves live in `domain/path-safety.ts`, shared with the installer's
+ * extractor, so a package that `validate` accepts can never be one the extractor rejects.
+ */
+function capitalise(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+ * Normalises whitespace before comparing two descriptions. A folded YAML scalar (`>`) and a
+ * quoted one carry the same text with different line breaks, and that difference is not a
+ * mismatch anybody needs to hear about.
+ */
+function collapse(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+export function pathSafetyIssues(path) {
+    const violation = inspectPath(path);
+    if (violation === undefined)
+        return [];
+    return [
+        {
+            severity: 'error',
+            rule: `path.${violation.rule}`,
+            at: path,
+            message: violation.message,
+            hint: 'Rename the file so it is safe on every platform',
+        },
+    ];
+}
+/** Loads a package from disk and validates it. The `validate` command in one call. */
+export async function validateDirectory(ctx, directory, options = {}) {
+    const loaded = await loadPackageFromDirectory(ctx.fs, directory, options);
+    const report = validatePackage(loaded.pkg, {
+        ...options,
+        directoryName: options.directoryName ?? ctx.fs.basename(loaded.directory),
+        adapters: options.adapters ?? ctx.agents.all(),
+    });
+    const combined = buildReport([...loaded.issues, ...report.issues]);
+    return { ...combined, pkg: loaded.pkg, directory: loaded.directory };
+}
+//# sourceMappingURL=validate-package.js.map

package/dist/application/validate-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-package.js","sourceRoot":"","sources":["../../src/application/validate-package.ts"],"names":[],"mappings":"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"}

package/dist/application/workspace.d.ts

@@ -0,0 +1,22 @@
+import { type Lockfile } from '../domain/lockfile.ts';
+import type { SemanticVersion } from '../domain/version.ts';
+import type { FileSystem } from '../ports/infrastructure.ts';
+/**
+ * Walks up from `start` looking for a project marker.
+ *
+ * Returns `undefined` rather than defaulting to the cwd: silently treating an arbitrary
+ * directory as a project is how tools end up scattering `.claude/` folders around a filesystem.
+ *
+ * The home directory is never a project, and the walk stops there. `~/.claude` and `~/.codex`
+ * are an agent's *global* configuration; treating them as project markers would make every
+ * command run from anywhere under `$HOME` — a scratch directory, a temp folder — resolve
+ * "project scope" to the user's home and install into their global configuration by accident.
+ */
+export declare function findProjectRoot(fs: FileSystem, start: string, homeDir?: string): Promise<string | undefined>;
+export declare function requireProjectRoot(fs: FileSystem, start: string, homeDir?: string): Promise<string>;
+export declare function lockfilePath(fs: FileSystem, projectRoot: string): string;
+export declare function readLockfile(fs: FileSystem, projectRoot: string): Promise<Lockfile>;
+export declare function writeLockfile(fs: FileSystem, projectRoot: string, lock: Lockfile): Promise<void>;
+/** Version pins from the lockfile, in the shape the resolver expects. */
+export declare function pinsFrom(lock: Lockfile): Record<string, SemanticVersion>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/application/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/application/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAS7D;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7B;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAIzF;AAED,wBAAsB,aAAa,CACjC,EAAE,EAAE,UAAU,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAIxE"}

package/dist/application/workspace.js

@@ -0,0 +1,66 @@
+import { LOCKFILE_NAME, emptyLockfile, parseLockfile, stringifyLockfile, } from "../domain/lockfile.js";
+import { AgentSkillsError, ErrorCode } from "../domain/errors.js";
+/**
+ * Markers that make a directory "a project". `.git` is the usual answer; the others let the
+ * tool work in a checkout that is not a git repository, or in a subdirectory of one that has
+ * its own agent configuration.
+ */
+const PROJECT_MARKERS = [LOCKFILE_NAME, '.git', '.claude', '.agents', '.codex'];
+/**
+ * Walks up from `start` looking for a project marker.
+ *
+ * Returns `undefined` rather than defaulting to the cwd: silently treating an arbitrary
+ * directory as a project is how tools end up scattering `.claude/` folders around a filesystem.
+ *
+ * The home directory is never a project, and the walk stops there. `~/.claude` and `~/.codex`
+ * are an agent's *global* configuration; treating them as project markers would make every
+ * command run from anywhere under `$HOME` — a scratch directory, a temp folder — resolve
+ * "project scope" to the user's home and install into their global configuration by accident.
+ */
+export async function findProjectRoot(fs, start, homeDir) {
+    const home = homeDir === undefined ? undefined : fs.resolve(homeDir);
+    let current = fs.resolve(start);
+    for (;;) {
+        if (current === home)
+            return undefined;
+        for (const marker of PROJECT_MARKERS) {
+            if (await fs.exists(fs.join(current, marker)))
+                return current;
+        }
+        const parent = fs.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+export async function requireProjectRoot(fs, start, homeDir) {
+    const root = await findProjectRoot(fs, start, homeDir);
+    if (root !== undefined)
+        return root;
+    throw new AgentSkillsError(ErrorCode.USAGE, 'Not inside a project', {
+        details: [`Looked for ${PROJECT_MARKERS.join(', ')} in ${start} and every parent directory.`],
+        hints: [
+            'Run the command from inside a project,',
+            'pass --project-root <path>,',
+            'or use --global to install into your user configuration',
+        ],
+        data: { start },
+    });
+}
+export function lockfilePath(fs, projectRoot) {
+    return fs.join(projectRoot, LOCKFILE_NAME);
+}
+export async function readLockfile(fs, projectRoot) {
+    const path = lockfilePath(fs, projectRoot);
+    if (!(await fs.exists(path)))
+        return emptyLockfile();
+    return parseLockfile(await fs.readTextFile(path), path);
+}
+export async function writeLockfile(fs, projectRoot, lock) {
+    await fs.writeFile(lockfilePath(fs, projectRoot), stringifyLockfile(lock));
+}
+/** Version pins from the lockfile, in the shape the resolver expects. */
+export function pinsFrom(lock) {
+    return Object.fromEntries(Object.entries(lock.skills).map(([name, entry]) => [name, entry.version]));
+}
+//# sourceMappingURL=workspace.js.map

package/dist/application/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/application/workspace.ts"],"names":[],"mappings":"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"}

package/dist/domain/agent.d.ts

@@ -0,0 +1,89 @@
+import type { PackageKind } from './manifest.ts';
+import type { SkillPackage } from './skill-package.ts';
+/** Stable adapter identifier, e.g. `claude-code`, `codex`. Appears in receipts and lockfiles. */
+export type AgentId = string;
+/** `global` targets the user's home configuration; `project` targets a repository. */
+export type InstallScope = 'global' | 'project';
+export declare const INSTALL_SCOPES: readonly InstallScope[];
+/** Everything an adapter may consult when computing a skill root. */
+export interface LocationContext {
+    readonly homeDir: string;
+    readonly projectRoot?: string;
+    /** Raw environment, so an adapter can honour `$CODEX_HOME` or `$CLAUDE_CONFIG_DIR`. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** User override from config, e.g. `agents["codex"].globalRoot`. Wins over defaults. */
+    readonly overrideRoot?: string;
+}
+/**
+ * How one installed package appears inside an agent's root: a directory holding the
+ * package's files, or a single file named after the package. Claude Code skills are
+ * directories; its commands are `<name>.md` files.
+ */
+export type EntryShape = 'directory' | 'file';
+/** Where and how one agent stores packages of one kind. */
+export interface AgentLocation {
+    /** Absolute path of the directory holding every package of this kind. */
+    readonly root: string;
+    readonly shape: EntryShape;
+    /** Suffix appended to the package name for `file` shape, e.g. `.md`. Empty otherwise. */
+    readonly extension: string;
+}
+export type DetectionStrength = 'strong' | 'weak' | 'none';
+export interface DetectionEvidence {
+    readonly strength: DetectionStrength;
+    /** Short machine-ish label, e.g. `config-dir`, `executable`, `project-dir`. */
+    readonly kind: string;
+    /** Human-readable location or explanation. */
+    readonly detail: string;
+}
+export interface AgentDetection {
+    readonly agentId: AgentId;
+    /** True when at least one piece of strong evidence was found. */
+    readonly installed: boolean;
+    readonly strength: DetectionStrength;
+    readonly evidence: readonly DetectionEvidence[];
+    /** Populated only when the agent reliably exposes a version. */
+    readonly version?: string;
+}
+export declare function detectionFrom(agentId: AgentId, evidence: readonly DetectionEvidence[], version?: string): AgentDetection;
+/**
+ * One file the adapter wants written into the installed skill directory.
+ * Either inline `content` (adapter-synthesised, e.g. Codex's `agents/openai.yaml`)
+ * or `copyFrom` (a path in the neutral package, copied verbatim).
+ */
+export type LayoutEntry = {
+    readonly path: string;
+    readonly content: Uint8Array;
+    readonly copyFrom?: undefined;
+} | {
+    readonly path: string;
+    readonly copyFrom: string;
+    readonly content?: undefined;
+};
+/**
+ * The projection of a neutral package onto one agent. Pure data: producing it must not
+ * touch the filesystem, which is what makes every adapter snapshot-testable.
+ */
+export interface AgentLayout {
+    /**
+     * Files to write. Paths are relative to the installed package directory; for a `file`
+     * shaped target there must be exactly one entry, and its path is unused because the
+     * installer names the file after the package.
+     */
+    readonly entries: readonly LayoutEntry[];
+    /** Frontmatter the adapter wants in the installed entrypoint document. */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+}
+/** Convenience view used by `list`, `doctor` and the installer. */
+export interface AgentTarget extends AgentLocation {
+    readonly agentId: AgentId;
+    readonly displayName: string;
+    readonly scope: InstallScope;
+    readonly kind: PackageKind;
+}
+/** Path of one installed package inside its root, for both entry shapes. */
+export declare function entryNameFor(target: AgentLocation, name: string): string;
+export interface AgentLayoutInput {
+    readonly pkg: SkillPackage;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/domain/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/domain/agent.ts"],"names":[],"mappings":"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"}

package/dist/domain/agent.js

@@ -0,0 +1,20 @@
+export const INSTALL_SCOPES = ['global', 'project'];
+export function detectionFrom(agentId, evidence, version) {
+    const strength = evidence.some((item) => item.strength === 'strong')
+        ? 'strong'
+        : evidence.some((item) => item.strength === 'weak')
+            ? 'weak'
+            : 'none';
+    return {
+        agentId,
+        installed: strength === 'strong',
+        strength,
+        evidence,
+        ...(version === undefined ? {} : { version }),
+    };
+}
+/** Path of one installed package inside its root, for both entry shapes. */
+export function entryNameFor(target, name) {
+    return `${name}${target.extension}`;
+}
+//# sourceMappingURL=agent.js.map

package/dist/domain/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/domain/agent.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,cAAc,GAA4B,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAgD7E,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,QAAsC,EACtC,OAAgB;IAEhB,MAAM,QAAQ,GAAsB,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC;QACrF,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,MAAM,CAAC;YACjD,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,MAAM,CAAC;IACb,OAAO;QACL,OAAO;QACP,SAAS,EAAE,QAAQ,KAAK,QAAQ;QAChC,QAAQ;QACR,QAAQ;QACR,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAkCD,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,IAAY;IAC9D,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;AACtC,CAAC"}