@jini-ai/agentic 0.3.7 → 0.4.1

package/dist/skills/install/github.d.ts

@@ -0,0 +1,21 @@
+/** Commit-pinned public GitHub import with one request/body deadline, byte caps and refused redirects. */
+import { type SkillUploadFile } from "./validation.js";
+import type { SkillFetchPort } from "./ports.js";
+export interface GitHubSkillSource {
+    readonly githubUrl: string;
+    readonly commit: string;
+}
+/** Restricts every request to api.github.com, disallows redirects, pins one immutable commit.
+ * @complexity O(files + downloaded bytes), at most 256 file requests and 8 MiB decoded content.
+ */
+export declare function fetchGitHubSkill({ githubUrl, fetch: fetchImpl }: {
+    githubUrl: string;
+    fetch: SkillFetchPort;
+}, _optional?: Record<string, never>): Promise<{
+    files: SkillUploadFile[];
+    source: {
+        githubUrl: string;
+        commit: string;
+    };
+}>;
+//# sourceMappingURL=github.d.ts.map

package/dist/skills/install/github.js

@@ -0,0 +1,92 @@
+/** Commit-pinned public GitHub import with one request/body deadline, byte caps and refused redirects. */
+import { MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, decodeSkillBase64, SkillInputError } from "./validation.js";
+/** Restricts every request to api.github.com, disallows redirects, pins one immutable commit.
+ * @complexity O(files + downloaded bytes), at most 256 file requests and 8 MiB decoded content.
+ */
+export async function fetchGitHubSkill({ githubUrl, fetch: fetchImpl }, _optional = {}) {
+    let url;
+    try {
+        url = new URL(githubUrl);
+    }
+    catch {
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    }
+    let parts;
+    try {
+        parts = url.pathname.replace(/\/$/, "").split("/").slice(1).map(p => decodeURIComponent(p));
+    }
+    catch {
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    }
+    if (url.protocol !== "https:" || url.hostname !== "github.com" || url.port || url.username || url.password || url.search || url.hash || parts.length < 2 || (parts.length > 2 && (parts[2] !== "tree" || parts.length < 4)) || parts.some(p => !/^[a-zA-Z0-9_.-]+$/.test(p) || p === "." || p === ".."))
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    const owner = parts[0];
+    const repo = parts[1].replace(/\.git$/, "");
+    if (!repo)
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    const base = `https://api.github.com/repos/${owner}/${repo}`;
+    // One deadline for the whole fetch, including streaming response bodies.
+    const signal = AbortSignal.timeout(30_000);
+    async function json(endpoint) {
+        const response = await fetchImpl({ url: endpoint }, { redirect: "error", signal, headers: { Accept: "application/vnd.github+json" } });
+        if (!response.ok)
+            throw new SkillInputError({ message: `GitHub could not fetch this skill (HTTP ${response.status}). Use a public repository URL.` });
+        if (!response.body)
+            throw new SkillInputError({ message: "GitHub returned an empty response." });
+        const reader = response.body.getReader();
+        let bytes = 0;
+        const chunks = [];
+        try {
+            for (;;) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.length;
+                if (bytes > MAX_SKILL_BYTES * 2)
+                    throw new SkillInputError({ message: "GitHub skill response exceeds its size limit." });
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        const result = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!result || typeof result !== "object" || Array.isArray(result))
+            throw new SkillInputError({ message: "GitHub returned an invalid skill response." });
+        return result;
+    }
+    const commit = (await json(`${base}/commits/${encodeURIComponent(parts[3] ?? "HEAD")}`)).sha;
+    if (typeof commit !== "string" || !/^[a-f0-9]{40}$/.test(commit))
+        throw new SkillInputError({ message: "GitHub returned an invalid commit." });
+    const tree = await json(`${base}/git/trees/${commit}?recursive=1`);
+    if (tree.truncated || !Array.isArray(tree.tree))
+        throw new SkillInputError({ message: "GitHub repository tree is incomplete. Choose a smaller skill repository." });
+    const prefix = parts.length > 4 ? parts.slice(4).join("/") + "/" : "";
+    const files = [];
+    let total = 0;
+    let actualBytes = 0;
+    for (const row of tree.tree) {
+        if (typeof row.path !== "string" || !row.path.startsWith(prefix))
+            continue;
+        const relative = row.path.slice(prefix.length);
+        if (!/^(SKILL\.md|README\.md|LICENSE|(?:references|scripts|assets)\/.*)$/.test(relative) || row.type === "tree")
+            continue;
+        if (row.type !== "blob" || !["100644", "100755"].includes(String(row.mode)))
+            throw new SkillInputError({ message: "GitHub skills may contain only regular files." });
+        if (typeof row.size !== "number" || row.size < 0 || row.size > MAX_SKILL_FILE_BYTES || typeof row.sha !== "string" || !/^[a-f0-9]{40}$/.test(row.sha))
+            throw new SkillInputError({ message: "GitHub skill file exceeds its size limit or has invalid metadata." });
+        total += row.size;
+        if (total > MAX_SKILL_BYTES || files.length >= MAX_SKILL_FILES)
+            throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
+        const blob = await json(`${base}/git/blobs/${row.sha}`);
+        if (blob.encoding !== "base64" || typeof blob.content !== "string")
+            throw new SkillInputError({ message: "GitHub returned an invalid skill file." });
+        const contentBase64 = blob.content.replace(/\s/g, "");
+        actualBytes += decodeSkillBase64({ value: contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES }).length;
+        if (actualBytes > MAX_SKILL_BYTES)
+            throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
+        files.push({ path: relative, contentBase64 });
+    }
+    return { files, source: { githubUrl, commit } };
+}
+//# sourceMappingURL=github.js.map

package/dist/skills/install/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./validation.js";
+export * from "./ports.js";
+export * from "./archive.js";
+export * from "./github.js";
+export * from "./state.js";
+export * from "./install-service.js";
+export * from "./layout.js";
+export * from "./live-registration.js";
+export * from "./fetch-adapter.js";
+export * from "./node-filesystem.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/install/index.js

@@ -0,0 +1,11 @@
+export * from "./validation.js";
+export * from "./ports.js";
+export * from "./archive.js";
+export * from "./github.js";
+export * from "./state.js";
+export * from "./install-service.js";
+export * from "./layout.js";
+export * from "./live-registration.js";
+export * from "./fetch-adapter.js";
+export * from "./node-filesystem.js";
+//# sourceMappingURL=index.js.map

package/dist/skills/install/install-service.d.ts

@@ -0,0 +1,44 @@
+import { type SkillUploadFile } from "./validation.js";
+import { type GitHubSkillSource } from "./github.js";
+import type { SkillInstallDeps } from "./ports.js";
+export interface ManagedSkill {
+    readonly toolId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly enabled: boolean;
+    readonly source: "uploaded" | GitHubSkillSource;
+}
+export type SkillInstallInput = {
+    readonly workspaceId: string;
+} & ({
+    readonly githubUrl: string;
+} | {
+    readonly files: readonly SkillUploadFile[];
+} | {
+    readonly archiveBase64: string;
+});
+export interface SkillInstaller {
+    installSkill(required: SkillInstallInput): Promise<ManagedSkill>;
+    listManagedSkills(required: {
+        workspaceId: string;
+    }): Promise<ManagedSkill[]>;
+    setSkillEnabled(required: {
+        workspaceId: string;
+        toolId: string;
+        enabled: boolean;
+    }): Promise<void>;
+    uninstallSkill(required: {
+        workspaceId: string;
+        toolId: string;
+    }): Promise<void>;
+}
+/** Validate before writes; publish via rename, with instance-local queues keyed by resolved root.
+ * Cross-process exclusivity remains the host filesystem/layout adapter's responsibility.
+ */
+export declare function createSkillInstaller(deps: SkillInstallDeps, optional?: {
+    onChanged?: (required: {
+        workspaceId: string;
+        toolId: string;
+    }) => void | Promise<void>;
+}): SkillInstaller;
+//# sourceMappingURL=install-service.d.ts.map

package/dist/skills/install/install-service.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { SkillInputError, validateSkillFiles } from "./validation.js";
+import { readSkillArchive } from "./archive.js";
+import { fetchGitHubSkill } from "./github.js";
+import { readSkillState } from "./state.js";
+/** Validate before writes; publish via rename, with instance-local queues keyed by resolved root.
+ * Cross-process exclusivity remains the host filesystem/layout adapter's responsibility.
+ */
+export function createSkillInstaller(deps, optional = {}) {
+    const queues = new Map();
+    const layoutFor = (workspaceId) => {
+        const layout = deps.layout.resolve({ workspaceId });
+        if (!path.isAbsolute(layout.workspaceRoot) || !path.isAbsolute(layout.stagingRoot))
+            throw new SkillInputError({ message: "Skill roots must be absolute." });
+        if (!layout.stateFileName || /[/\\\x00]/.test(layout.stateFileName) || [".", ".."].includes(layout.stateFileName) || ["SKILL.md", "README.md", "LICENSE", "references", "scripts", "assets"].includes(layout.stateFileName))
+            throw new SkillInputError({ message: "Invalid skill state file name." });
+        return layout;
+    };
+    async function locked(workspaceId, work) {
+        const key = layoutFor(workspaceId).workspaceRoot;
+        const result = (queues.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
+        queues.set(key, result);
+        try {
+            return await result;
+        }
+        finally {
+            if (queues.get(key) === result)
+                queues.delete(key);
+        }
+    }
+    async function listManagedSkills(required) {
+        const layout = layoutFor(required.workspaceId);
+        const sources = await deps.toolSourceLoader.load(required, { includeDisabled: true });
+        return Promise.all(sources.map(async (skill) => {
+            const directory = containedDirectory(layout.workspaceRoot, skill.directory);
+            return { toolId: skill.id, name: skill.skillName, description: skill.description,
+                ...await readSkillState({ directory, stateFileName: layout.stateFileName, filesystem: deps.filesystem }) };
+        }));
+    }
+    async function managedDirectory(required) {
+        const skill = (await deps.toolSourceLoader.load({ workspaceId: required.workspaceId }, { includeDisabled: true })).find(source => source.id === required.toolId);
+        if (!skill)
+            throw new SkillInputError({ message: "Skill was not found." });
+        const directory = containedDirectory(layoutFor(required.workspaceId).workspaceRoot, skill.directory);
+        if ((await deps.filesystem.lstat({ path: directory })).kind !== "directory")
+            throw new SkillInputError({ message: "Skill directory must be a regular directory." });
+        return directory;
+    }
+    const changed = async (workspaceId, toolId) => { await optional.onChanged?.({ workspaceId, toolId }); };
+    return {
+        listManagedSkills,
+        async installSkill(input) {
+            let upload;
+            let source = "uploaded";
+            if ("githubUrl" in input)
+                ({ files: upload, source } = await fetchGitHubSkill({ githubUrl: input.githubUrl, fetch: deps.fetch }));
+            else if ("archiveBase64" in input)
+                upload = await readSkillArchive({ base64: input.archiveBase64, archiveReader: deps.archiveReader });
+            else
+                upload = input.files;
+            const validated = validateSkillFiles({ files: upload, yamlReader: deps.yamlReader });
+            const toolId = deps.toolId({ name: validated.name });
+            const layout = layoutFor(input.workspaceId);
+            return locked(input.workspaceId, async () => {
+                if ((await listManagedSkills(input)).some(skill => skill.toolId === toolId))
+                    throw new SkillInputError({ message: `Skill '${validated.name}' is already installed. Remove it before installing another version.` });
+                await deps.filesystem.mkdir({ path: layout.workspaceRoot });
+                await deps.filesystem.mkdir({ path: layout.stagingRoot });
+                const staging = await deps.filesystem.mkdtemp({ prefix: path.join(layout.stagingRoot, "skill-") });
+                try {
+                    for (const [relative, bytes] of validated.files) {
+                        const target = path.join(staging, relative);
+                        await deps.filesystem.mkdir({ path: path.dirname(target) });
+                        await deps.filesystem.writeFile({ path: target, bytes, exclusive: true, mode: 0o600 });
+                    }
+                    await deps.filesystem.writeFile({ path: path.join(staging, layout.stateFileName), bytes: Buffer.from(JSON.stringify({ enabled: true, source })), exclusive: true, mode: 0o600 });
+                    await deps.filesystem.rename({ from: staging, to: path.join(layout.workspaceRoot, validated.name) });
+                    await changed(input.workspaceId, toolId);
+                    return { toolId, name: validated.name, description: validated.description, enabled: true, source };
+                }
+                finally {
+                    await deps.filesystem.remove({ path: staging }, { recursive: true, force: true });
+                }
+            });
+        },
+        async setSkillEnabled(input) {
+            if (typeof input.enabled !== "boolean")
+                throw new SkillInputError({ message: "enabled must be a boolean." });
+            await locked(input.workspaceId, async () => {
+                const directory = await managedDirectory(input);
+                const layout = layoutFor(input.workspaceId);
+                const state = await readSkillState({ directory, stateFileName: layout.stateFileName, filesystem: deps.filesystem });
+                const id = deps.ids.next({});
+                if (!id || /[/\\\x00]/.test(id))
+                    throw new SkillInputError({ message: "Invalid skill temporary id." });
+                const temporary = path.join(directory, `.skill-state-${id}.tmp`);
+                try {
+                    // A rejected write can leave partial bytes; cleanup must cover writing as well as rename.
+                    await deps.filesystem.writeFile({ path: temporary, bytes: Buffer.from(JSON.stringify({ ...state, enabled: input.enabled })), exclusive: true, mode: 0o600 });
+                    await deps.filesystem.rename({ from: temporary, to: path.join(directory, layout.stateFileName) });
+                }
+                finally {
+                    await deps.filesystem.remove({ path: temporary }, { force: true });
+                }
+                await changed(input.workspaceId, input.toolId);
+            });
+        },
+        async uninstallSkill(input) {
+            await locked(input.workspaceId, async () => {
+                await deps.filesystem.remove({ path: await managedDirectory(input) }, { recursive: true });
+                await changed(input.workspaceId, input.toolId);
+            });
+        },
+    };
+}
+function containedDirectory(root, directory) {
+    if (!directory || directory === "." || directory === ".." || /[/\\\x00]/.test(directory))
+        throw new SkillInputError({ message: "Skill directory must be one safe segment." });
+    return path.join(root, directory);
+}
+//# sourceMappingURL=install-service.js.map

package/dist/skills/install/layout.d.ts

@@ -0,0 +1,13 @@
+import type { SkillLayoutPort } from './ports.js';
+/** Every storage location is host-owned; this adapter has no product or cwd defaults.
+ * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName
+ * contract used by the installer. No site, environment or cwd defaults are allowed: separate
+ * workspace roots and staging roots keep installation writes inside the host's selected paths.
+ */
+export declare function createSkillLayout(required: {
+    root: string;
+    stagingRoot: string;
+    workspaceDirectory: string;
+    stateFileName: string;
+}, _optional?: Record<string, never>): SkillLayoutPort;
+//# sourceMappingURL=layout.d.ts.map

package/dist/skills/install/layout.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+/** Every storage location is host-owned; this adapter has no product or cwd defaults.
+ * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName
+ * contract used by the installer. No site, environment or cwd defaults are allowed: separate
+ * workspace roots and staging roots keep installation writes inside the host's selected paths.
+ */
+export function createSkillLayout(required, _optional = {}) {
+    const { root, stagingRoot, workspaceDirectory, stateFileName } = required;
+    if (!path.isAbsolute(root) || !path.isAbsolute(stagingRoot))
+        throw new Error('Skill roots must be absolute paths.');
+    if (!/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(workspaceDirectory))
+        throw new Error('Invalid workspace directory segment.');
+    if (!stateFileName || /[/\\\x00]/.test(stateFileName) || ['.', '..', 'SKILL.md', 'README.md', 'LICENSE', 'references', 'scripts', 'assets'].includes(stateFileName))
+        throw new Error('Invalid skill state file name.');
+    return Object.freeze({ resolve({ workspaceId }) {
+            const normalized = workspaceId.toLowerCase();
+            if (normalized.length > 64 || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(normalized))
+                throw new Error(`resolve: '${workspaceId}' is not a valid workspace id`);
+            return { workspaceRoot: path.join(root, workspaceDirectory, normalized), stagingRoot: path.resolve(stagingRoot), stateFileName };
+        } });
+}
+//# sourceMappingURL=layout.js.map

package/dist/skills/install/live-registration.d.ts

@@ -0,0 +1,61 @@
+export interface SkillRegistration<Descriptor extends {
+    id: string;
+} = {
+    id: string;
+}, Context = unknown> {
+    readonly descriptor: Descriptor;
+    readonly policy: {
+        authorize(required: {
+            context: Context;
+        }): unknown;
+    };
+    readonly handler: (required: {
+        context: Context;
+    }) => unknown;
+}
+export interface SkillRegistryPort<Descriptor extends {
+    id: string;
+} = {
+    id: string;
+}, Context = unknown> {
+    list(required: Record<string, never>): Descriptor[];
+    has(required: {
+        id: string;
+    }): boolean;
+    register(required: {
+        tool: SkillRegistration<Descriptor, Context>;
+    }): void;
+}
+export interface SkillsRefreshRegistry {
+    refreshInstalledSkills?(required: Record<string, never>): Promise<boolean>;
+}
+/** Keep append-only registry slots while dispatching current registrations or failing closed. */
+export declare function createLiveSkillRegistration<Descriptor extends {
+    id: string;
+}, Context>(required: {
+    registry: SkillRegistryPort<Descriptor, Context>;
+    inactiveError: (required: {
+        id: string;
+    }) => Error;
+}, _optional?: Record<string, never>): ({ tools }: {
+    tools: readonly SkillRegistration<Descriptor, Context>[];
+}) => boolean;
+/** Prevent older loads overwriting newer registrations; reset after both success and failure. */
+export declare function createSkillRefresher<T>(required: {
+    load: (required: Record<string, never>) => Promise<readonly T[]>;
+    replace: (required: {
+        tools: readonly T[];
+    }) => boolean;
+}, _optional?: Record<string, never>): {
+    refreshInstalledSkills(required: Record<string, never>): Promise<boolean>;
+};
+export declare function createSkillRefreshMiddleware(required: {
+    registry: SkillsRefreshRegistry;
+}, optional?: {
+    onChanged?: (required: Record<string, never>) => void;
+}): ({ next }: {
+    next: (required: Record<string, never>, optional?: {
+        error?: unknown;
+    }) => void;
+}) => Promise<void>;
+//# sourceMappingURL=live-registration.d.ts.map

package/dist/skills/install/live-registration.js

@@ -0,0 +1,64 @@
+/** Keep append-only registry slots while dispatching current registrations or failing closed. */
+export function createLiveSkillRegistration(required, _optional = {}) {
+    const { registry } = required;
+    const active = new Map();
+    const slots = new Map();
+    const list = registry.list.bind(registry), has = registry.has.bind(registry);
+    registry.list = input => list(input).filter(d => !slots.has(d.id) || active.has(d.id));
+    registry.has = input => slots.has(input.id) ? active.has(input.id) : has(input);
+    let fingerprint = '';
+    return ({ tools }) => {
+        const nextFingerprint = JSON.stringify(tools.map(t => t.descriptor));
+        const next = new Map(tools.map(t => [t.descriptor.id, t]));
+        if (next.size !== tools.length)
+            throw new Error('Duplicate skill registration ID.');
+        for (const tool of tools) {
+            const id = tool.descriptor.id, existing = slots.get(id);
+            if (existing)
+                Object.assign(existing.descriptor, tool.descriptor);
+            else {
+                const slot = {
+                    descriptor: { ...tool.descriptor },
+                    policy: { authorize: input => active.get(id)?.policy.authorize(input) ?? 'deny' },
+                    handler: input => {
+                        const current = active.get(id);
+                        if (!current)
+                            throw required.inactiveError({ id });
+                        return current.handler(input);
+                    },
+                };
+                registry.register({ tool: slot });
+                slots.set(id, slot);
+            }
+        }
+        active.clear();
+        for (const [id, tool] of next)
+            active.set(id, tool);
+        const changed = fingerprint !== nextFingerprint;
+        fingerprint = nextFingerprint;
+        return changed;
+    };
+}
+/** Prevent older loads overwriting newer registrations; reset after both success and failure. */
+export function createSkillRefresher(required, _optional = {}) {
+    let pending;
+    return { refreshInstalledSkills: (_required) => {
+            if (!pending)
+                pending = required.load({}).then(tools => required.replace({ tools })).finally(() => { pending = undefined; });
+            return pending;
+        } };
+}
+export function createSkillRefreshMiddleware(required, optional = {}) {
+    return async ({ next }) => {
+        try {
+            if (await required.registry.refreshInstalledSkills?.({}))
+                optional.onChanged?.({});
+        }
+        catch (error) {
+            next({}, { error });
+            return;
+        }
+        next({});
+    };
+}
+//# sourceMappingURL=live-registration.js.map

package/dist/skills/install/node-filesystem.d.ts

@@ -0,0 +1,4 @@
+import type { FilesystemPort } from './ports.js';
+/** Node adapter kept separate from the injected installation policy. */
+export declare function createNodeSkillFilesystem(_required: Record<string, never>, _optional?: Record<string, never>): FilesystemPort;
+//# sourceMappingURL=node-filesystem.d.ts.map

package/dist/skills/install/node-filesystem.js

@@ -0,0 +1,41 @@
+import { lstat, mkdir, mkdtemp, open, rename, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+/** Node adapter kept separate from the injected installation policy. */
+export function createNodeSkillFilesystem(_required, _optional = {}) {
+    return {
+        mkdir: async ({ path }) => { await mkdir(path, { recursive: true }); },
+        mkdtemp: ({ prefix }) => mkdtemp(prefix),
+        lstat: async ({ path }) => {
+            const stat = await lstat(path);
+            return { kind: stat.isSymbolicLink() ? 'symlink' : stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : 'other', size: stat.size };
+        },
+        readFile: async ({ path, maxBytes }) => {
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size > maxBytes)
+                    throw new Error('Invalid skill installation record.');
+                const chunks = [];
+                let size = 0;
+                for (;;) {
+                    const chunk = Buffer.alloc(Math.min(4096, maxBytes + 1 - size));
+                    const result = await handle.read(chunk, 0, chunk.length, null);
+                    if (!result.bytesRead)
+                        break;
+                    size += result.bytesRead;
+                    if (size > maxBytes)
+                        throw new Error('Invalid skill installation record.');
+                    chunks.push(chunk.subarray(0, result.bytesRead));
+                }
+                return Buffer.concat(chunks);
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        writeFile: ({ path, bytes, exclusive, mode }) => writeFile(path, bytes, { flag: exclusive ? 'wx' : 'w', mode }),
+        rename: ({ from, to }) => rename(from, to),
+        remove: ({ path }, options = {}) => rm(path, options),
+    };
+}
+//# sourceMappingURL=node-filesystem.js.map

package/dist/skills/install/ports.d.ts

@@ -0,0 +1,101 @@
+/** The adapter uses failsafe YAML and rejects duplicate keys; the installer never parses YAML itself. */
+export interface YamlReaderPort {
+    read(required: {
+        yaml: string;
+    }): unknown;
+}
+/** Layout is host-owned. Staging and workspace roots must share a rename-capable filesystem. */
+export interface SkillLayoutPort {
+    resolve(required: {
+        workspaceId: string;
+    }): {
+        workspaceRoot: string;
+        stagingRoot: string;
+        stateFileName: string;
+    };
+}
+export interface SkillFilesystemPort {
+    mkdir(required: {
+        path: string;
+    }): Promise<void>;
+    mkdtemp(required: {
+        prefix: string;
+    }): Promise<string>;
+    writeFile(required: {
+        path: string;
+        bytes: Uint8Array;
+        mode: number;
+        exclusive: true;
+    }): Promise<void>;
+    readFile(required: {
+        path: string;
+        maxBytes: number;
+    }): Promise<Uint8Array>;
+    lstat(required: {
+        path: string;
+    }): Promise<{
+        kind: "file" | "directory" | "symlink" | "other";
+        size: number;
+    }>;
+    rename(required: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+    remove(required: {
+        path: string;
+    }, optional?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+}
+/** Compatibility name used by the original node adapter and copied contract tests. */
+export type FilesystemPort = SkillFilesystemPort;
+/** Adapters must expose lstat semantics: symlinks are never classified as regular files/directories. */
+export interface SkillToolSource {
+    id: string;
+    skillName: string;
+    description: string;
+    directory: string;
+}
+export interface ToolSourceLoaderPort {
+    load(required: {
+        workspaceId: string;
+    }, optional?: {
+        includeDisabled?: boolean;
+    }): Promise<readonly SkillToolSource[]>;
+}
+export interface ArchiveEntry {
+    path: string;
+    kind: "file" | "directory" | "other";
+    size: number;
+    /** Closing/returning the iterator must release the entry stream, including early refusal. */
+    read(required: Record<string, never>): AsyncIterable<Uint8Array>;
+}
+/** ZIP adapter must use strict names, validate sizes, and expose lazy entries without extraction. */
+export interface ArchiveReaderPort {
+    open(required: {
+        bytes: Uint8Array;
+    }): Promise<{
+        entries: AsyncIterable<ArchiveEntry>;
+        close(required: Record<string, never>): void;
+    }>;
+}
+/** HTTP transport follows the argument-object convention; hosts own credentials and networking. */
+export type SkillFetchPort = (required: {
+    url: string;
+}, optional?: RequestInit) => Promise<Response>;
+export interface SkillInstallDeps {
+    layout: SkillLayoutPort;
+    filesystem: SkillFilesystemPort;
+    archiveReader: ArchiveReaderPort;
+    yamlReader: YamlReaderPort;
+    fetch: SkillFetchPort;
+    ids: {
+        next(required: Record<string, never>): string;
+    };
+    toolId: (required: {
+        name: string;
+    }) => string;
+    toolSourceLoader: ToolSourceLoaderPort;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/skills/install/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/skills/install/state.d.ts

@@ -0,0 +1,13 @@
+import type { GitHubSkillSource } from "./github.js";
+import type { SkillFilesystemPort } from "./ports.js";
+export interface SkillState {
+    readonly enabled: boolean;
+    readonly source: "uploaded" | GitHubSkillSource;
+}
+/** Missing legacy records default to enabled; malformed records and symlinks fail closed. */
+export declare function readSkillState(required: {
+    directory: string;
+    stateFileName: string;
+    filesystem: SkillFilesystemPort;
+}, _optional?: Record<string, never>): Promise<SkillState>;
+//# sourceMappingURL=state.d.ts.map

package/dist/skills/install/state.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+/** Missing legacy records default to enabled; malformed records and symlinks fail closed. */
+export async function readSkillState(required, _optional = {}) {
+    const statePath = path.join(required.directory, required.stateFileName);
+    try {
+        const info = await required.filesystem.lstat({ path: statePath });
+        if (info.kind !== "file" || info.size > 8192)
+            throw new Error("Invalid skill installation record.");
+        const bytes = await required.filesystem.readFile({ path: statePath, maxBytes: 8192 });
+        if (bytes.length > 8192)
+            throw new Error("Invalid skill installation record.");
+        const state = JSON.parse(Buffer.from(bytes).toString("utf8"));
+        if (!state || typeof state.enabled !== "boolean" || (state.source !== "uploaded" && (!state.source || typeof state.source.githubUrl !== "string" || !/^[a-f0-9]{40}$/.test(state.source.commit))))
+            throw new Error("Invalid skill installation record.");
+        return state;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { enabled: true, source: "uploaded" };
+        throw error;
+    }
+}
+//# sourceMappingURL=state.js.map