skilld-harness 3.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Harlan Wilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# skilld-harness
+
+Run visible skilld-maintained Skills through an AI SDK Harness.
+
+The package checks output limits, paths, file types, and Skill frontmatter.
+It then promotes generated Skills with an atomic directory rename.
+
+## Install
+
+```sh
+pnpm add skilld-harness @ai-sdk/harness ws zod
+```
+
+Use Node 22 or newer.
+The sandbox must provide POSIX `sh`, `rm`, `mkdir`, and GNU `find`.
+
+## Run a Skill
+
+```ts
+import { createSkillHarness } from 'skilld-harness'
+
+const skillHarness = createSkillHarness({
+  harness,
+  sandbox,
+})
+
+const result = await skillHarness.run({
+  _tag: 'ProjectSkill',
+  projectDir: process.cwd(),
+  destination: {
+    rootDir: '.skills',
+    name: 'my-project',
+  },
+})
+```
+
+Every run returns a tagged `Ok` or `Err` value.
+An installed Skill can include cleanup warnings after promotion.
+
+Pass `fetch` to `createSkillHarness` when the host owns HTTP access.
+The default adapter uses the Node global fetch implementation.
+
+## Visible Skills
+
+Import `skilld-harness/skills` to load the published Skill instructions.
+
+```ts
+import {
+  loadSkilldMaintainedSkill,
+  skilldMaintainedSkillNames,
+} from 'skilld-harness/skills'
+
+const names = await skilldMaintainedSkillNames()
+const skill = await loadSkilldMaintainedSkill('generate-project-skill')
+```
+
+The same Skill files remain usable directly through an Agent.
+Direct runs remain user reviewed.

package/dist/_chunks/skills.mjs

@@ -0,0 +1,87 @@
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, posix, relative, resolve, sep } from "node:path";
+import { parseDocument } from "yaml";
+import { fileURLToPath } from "node:url";
+function isSkillName(value) {
+	return value.length >= 1 && value.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function resolveWithin(root, candidate) {
+	const absoluteRoot = resolve(root);
+	const absoluteCandidate = resolve(root, candidate);
+	const fromRoot = relative(absoluteRoot, absoluteCandidate);
+	if (fromRoot === "" || !fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot)) return absoluteCandidate;
+	return null;
+}
+function normalizeOutputPath(value) {
+	if (value.length === 0 || value.includes("\\") || value.includes("\0") || posix.isAbsolute(value)) return null;
+	const normalized = posix.normalize(value);
+	if (normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized !== value) return null;
+	return normalized;
+}
+const skillRoots = [
+	resolve(dirname(fileURLToPath(import.meta.url)), "../skills"),
+	resolve(dirname(fileURLToPath(import.meta.url)), "skills"),
+	resolve(dirname(fileURLToPath(import.meta.url)), "../../../skills")
+];
+function parseManifest(source) {
+	const value = JSON.parse(source);
+	if (!Array.isArray(value) || value.some((name) => typeof name !== "string" || !isSkillName(name))) throw new Error("skilld-maintained Skill manifest is invalid.");
+	if (new Set(value).size !== value.length) throw new Error("skilld-maintained Skill manifest contains duplicate names.");
+	return Object.freeze([...value]);
+}
+async function locateFile(path) {
+	for (const root of skillRoots) {
+		const value = await readFile(resolve(root, path), "utf8").catch((error) => {
+			if (error.code === "ENOENT") return null;
+			throw error;
+		});
+		if (value !== null) return value;
+	}
+	throw new Error(`skilld-maintained Skill file is missing: ${path}`);
+}
+function splitSkill(source) {
+	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+	if (!match) throw new Error("skilld-maintained Skill frontmatter is invalid.");
+	const document = parseDocument(match[1], { uniqueKeys: true });
+	if (document.errors.length > 0) throw new Error("skilld-maintained Skill frontmatter is invalid.");
+	const frontmatter = document.toJS();
+	if (!frontmatter || typeof frontmatter !== "object") throw new Error("skilld-maintained Skill frontmatter is invalid.");
+	const values = frontmatter;
+	if (typeof values.name !== "string" || typeof values.description !== "string") throw new Error("skilld-maintained Skill frontmatter is incomplete.");
+	return {
+		name: values.name,
+		description: values.description,
+		content: match[2]
+	};
+}
+async function harnessSkillNames() {
+	return parseManifest(await locateFile("harness-skills.json"));
+}
+async function skilldMaintainedSkillNames() {
+	return parseManifest(await locateFile("skilld-maintained-skills.json"));
+}
+async function loadSkilldMaintainedSkill(name) {
+	if (!(await skilldMaintainedSkillNames()).includes(name)) throw new Error(`Unknown skilld-maintained Skill: ${name}`);
+	const skill = splitSkill(await locateFile(`${name}/SKILL.md`));
+	if (skill.name !== name) throw new Error(`skilld-maintained Skill name does not match its directory: ${name}`);
+	if (!(await harnessSkillNames()).includes(name)) return skill;
+	const request = await locateFile(`${name}/assets/harness-request.md`);
+	return {
+		...skill,
+		files: [{
+			path: "assets/harness-request.md",
+			content: request
+		}]
+	};
+}
+const DEFAULT_OUTPUT_POLICY = Object.freeze({
+	maxSourceFiles: 2e3,
+	maxSourceFileBytes: 524288,
+	maxSourceBytes: 52428800,
+	maxOutputFiles: 64,
+	maxOutputFileBytes: 524288,
+	maxOutputBytes: 4194304
+});
+export { DEFAULT_OUTPUT_POLICY, harnessSkillNames, isSkillName, loadSkilldMaintainedSkill, normalizeOutputPath, resolveWithin, skilldMaintainedSkillNames };
+
+//# sourceMappingURL=skills.mjs.map

package/dist/_chunks/skills.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.mjs","names":[],"sources":["../../src/internal/paths.ts","../../src/skills.ts"],"sourcesContent":["import { isAbsolute, posix, relative, resolve, sep } from 'node:path'\n\nexport function isSkillName(value: string): boolean {\n  return value.length >= 1\n    && value.length <= 64\n    && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)\n}\n\nexport function resolveWithin(root: string, candidate: string): string | null {\n  const absoluteRoot = resolve(root)\n  const absoluteCandidate = resolve(root, candidate)\n  const fromRoot = relative(absoluteRoot, absoluteCandidate)\n  if (fromRoot === '' || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== '..' && !isAbsolute(fromRoot)))\n    return absoluteCandidate\n  return null\n}\n\nexport function normalizeOutputPath(value: string): string | null {\n  if (value.length === 0 || value.includes('\\\\') || value.includes('\\0') || posix.isAbsolute(value))\n    return null\n  const normalized = posix.normalize(value)\n  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized !== value)\n    return null\n  return normalized\n}\n","import type { HarnessV1Skill } from '@ai-sdk/harness'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { parseDocument } from 'yaml'\nimport { isSkillName } from './internal/paths.ts'\n\nconst skillRoots = [\n  resolve(dirname(fileURLToPath(import.meta.url)), '../skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), 'skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), '../../../skills'),\n] as const\n\nfunction parseManifest(source: string): ReadonlyArray<string> {\n  const value = JSON.parse(source) as unknown\n  if (!Array.isArray(value) || value.some(name => typeof name !== 'string' || !isSkillName(name)))\n    throw new Error('skilld-maintained Skill manifest is invalid.')\n  if (new Set(value).size !== value.length)\n    throw new Error('skilld-maintained Skill manifest contains duplicate names.')\n  return Object.freeze([...value])\n}\n\nasync function locateFile(path: string): Promise<string> {\n  for (const root of skillRoots) {\n    const value = await readFile(resolve(root, path), 'utf8').catch((error) => {\n      if ((error as NodeJS.ErrnoException).code === 'ENOENT')\n        return null\n      throw error\n    })\n    if (value !== null)\n      return value\n  }\n  throw new Error(`skilld-maintained Skill file is missing: ${path}`)\n}\n\nfunction splitSkill(source: string): { name: string, description: string, content: string } {\n  const match = source.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n([\\s\\S]*)$/)\n  if (!match)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const document = parseDocument(match[1]!, { uniqueKeys: true })\n  if (document.errors.length > 0)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n  const frontmatter = document.toJS() as unknown\n  if (!frontmatter || typeof frontmatter !== 'object')\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const values = frontmatter as Record<string, unknown>\n  if (typeof values.name !== 'string' || typeof values.description !== 'string')\n    throw new Error('skilld-maintained Skill frontmatter is incomplete.')\n\n  return { name: values.name, description: values.description, content: match[2]! }\n}\n\nexport async function harnessSkillNames(): Promise<ReadonlyArray<string>> {\n  const source = await locateFile('harness-skills.json')\n  return parseManifest(source)\n}\n\nexport async function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>> {\n  const source = await locateFile('skilld-maintained-skills.json')\n  return parseManifest(source)\n}\n\nexport async function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill> {\n  const names = await skilldMaintainedSkillNames()\n  if (!names.includes(name))\n    throw new Error(`Unknown skilld-maintained Skill: ${name}`)\n\n  const source = await locateFile(`${name}/SKILL.md`)\n  const skill = splitSkill(source)\n  if (skill.name !== name)\n    throw new Error(`skilld-maintained Skill name does not match its directory: ${name}`)\n\n  const harnessSkills = await harnessSkillNames()\n  if (!harnessSkills.includes(name))\n    return skill\n\n  const request = await locateFile(`${name}/assets/harness-request.md`)\n  return {\n    ...skill,\n    files: [{ path: 'assets/harness-request.md', content: request }],\n  }\n}\n\nexport const DEFAULT_OUTPUT_POLICY = Object.freeze({\n  maxSourceFiles: 2_000,\n  maxSourceFileBytes: 512 * 1024,\n  maxSourceBytes: 50 * 1024 * 1024,\n  maxOutputFiles: 64,\n  maxOutputFileBytes: 512 * 1024,\n  maxOutputBytes: 4 * 1024 * 1024,\n})\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+import { HarnessAgentSandboxConfig } from "@ai-sdk/harness/agent";
+import { HarnessV1, HarnessV1SandboxProvider } from "@ai-sdk/harness";
+interface SkillDestination {
+  readonly rootDir: string;
+  readonly name: string;
+}
+type PackageSource = {
+  readonly _tag: 'NpmPackage';
+  readonly spec: string;
+} | {
+  readonly _tag: 'LocalPackage';
+  readonly rootDir: string;
+  readonly packageDir: string;
+};
+type SkillRun = {
+  readonly _tag: 'PackageSkill';
+  readonly source: PackageSource;
+  readonly destination: SkillDestination;
+} | {
+  readonly _tag: 'ProjectSkill';
+  readonly projectDir: string;
+  readonly destination: SkillDestination;
+} | {
+  readonly _tag: 'ReviewSkill';
+  readonly skillDir: string;
+};
+interface SkillOutputPolicy {
+  readonly maxSourceFiles: number;
+  readonly maxSourceFileBytes: number;
+  readonly maxSourceBytes: number;
+  readonly maxOutputFiles: number;
+  readonly maxOutputFileBytes: number;
+  readonly maxOutputBytes: number;
+}
+interface SkillRunOptions {
+  readonly signal?: AbortSignal;
+}
+interface SkillFile {
+  readonly path: string;
+  readonly bytes: number;
+}
+interface SourceAttempt {
+  readonly source: string;
+  readonly status: 'used' | 'skipped';
+  readonly reason?: string;
+}
+interface GeneratedSkill {
+  readonly _tag: 'GeneratedSkill';
+  readonly name: string;
+  readonly outputDir: string;
+  readonly files: ReadonlyArray<SkillFile>;
+  readonly sourceAttempts: ReadonlyArray<SourceAttempt>;
+  /** Cleanup problems after the new Skill reached its destination. */
+  readonly warnings: ReadonlyArray<string>;
+}
+interface SkillReviewFinding {
+  readonly level: 'error' | 'warning' | 'note';
+  readonly path: string;
+  readonly message: string;
+  readonly fix: string;
+}
+interface SkillReview {
+  readonly _tag: 'SkillReview';
+  readonly summary: string;
+  readonly findings: ReadonlyArray<SkillReviewFinding>;
+}
+type SkillRunError = {
+  readonly _tag: 'InvalidInput';
+  readonly message: string;
+} | {
+  readonly _tag: 'SourceUnavailable';
+  readonly message: string;
+  readonly attempts: ReadonlyArray<SourceAttempt>;
+  readonly cause?: unknown;
+} | {
+  readonly _tag: 'AgentFailed';
+  readonly message: string;
+  readonly cause?: unknown;
+} | {
+  readonly _tag: 'InvalidSkill';
+  readonly message: string;
+  readonly issues: ReadonlyArray<string>;
+} | {
+  readonly _tag: 'UnsafeOutputPath';
+  readonly message: string;
+  readonly path: string;
+} | {
+  readonly _tag: 'OutputBusy';
+  readonly message: string;
+  readonly path: string;
+} | {
+  readonly _tag: 'PromotionFailed';
+  readonly message: string;
+  readonly path: string;
+  readonly cause?: unknown;
+} | {
+  readonly _tag: 'Cancelled';
+  readonly message: string;
+};
+type SkillRunResult = {
+  readonly _tag: 'Ok';
+  readonly value: GeneratedSkill | SkillReview;
+} | {
+  readonly _tag: 'Err';
+  readonly error: SkillRunError;
+};
+interface SkillHarness {
+  readonly run: (input: SkillRun, options?: SkillRunOptions) => Promise<SkillRunResult>;
+}
+interface CreateSkillHarnessOptions {
+  readonly harness: HarnessV1;
+  /** The sandbox must provide POSIX sh, rm, mkdir, and GNU find. */
+  readonly sandbox: HarnessV1SandboxProvider;
+  /** onSession runs after the Harness writes its visible inputs. */
+  readonly sandboxConfig?: HarnessAgentSandboxConfig;
+  readonly outputPolicy?: Partial<SkillOutputPolicy>;
+  /** HTTP adapter for npm metadata and immutable source archives. */
+  readonly fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+declare function createSkillHarness(options: CreateSkillHarnessOptions): SkillHarness;
+export { type CreateSkillHarnessOptions, type GeneratedSkill, type PackageSource, type SkillDestination, type SkillFile, type SkillHarness, type SkillOutputPolicy, type SkillReview, type SkillReviewFinding, type SkillRun, type SkillRunError, type SkillRunOptions, type SkillRunResult, type SourceAttempt, createSkillHarness };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/harness.ts"],"mappings":";;UAGiB;WACN;WACA;;KAGC;WAEC;WACA;;WAGA;WACA;WACA;;KAGD;WAEC;WACA,QAAQ;WACR,aAAa;;WAGb;WACA;WACA,aAAa;;WAGb;WACA;;UAGI;WACN;WACA;WACA;WACA;WACA;WACA;;UAGM;WACN,SAAS;;UAGH;WACN;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,OAAO,cAAc;WACrB,gBAAgB,cAAc;;WAE9B,UAAU;;UAGJ;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA,UAAU,cAAc;;KAGvB;WACK;WAA+B;;WAEjC;WACA;WACA,UAAU,cAAc;WACxB;;WAEE;WAA8B;WAA0B;;WACxD;WAA+B;WAA0B,QAAQ;;WACjE;WAAmC;WAA0B;;WAC7D;WAA6B;WAA0B;;WACvD;WAAkC;WAA0B;WAAuB;;WACnF;WAA4B;;KAEjC;WACK;WAAqB,OAAO,iBAAiB;;WAC7C;WAAsB,OAAO;;UAE7B;WACN,MAAM,OAAO,UAAU,UAAU,oBAAoB,QAAQ;;UAGvD;WACN,SAAS;;WAET,SAAS;;WAET,gBAAgB;WAChB,eAAe,QAAQ;;WAEvB,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ;;iBCkElE,mBAAmB,SAAS,4BAA4B"}