spawnfile 0.1.0

package/dist/filesystem/io.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { cp, mkdir, lstat, readFile, rm, stat, writeFile } from "node:fs/promises";
+export const copyDirectory = async (sourcePath, destinationPath, options = {}) => {
+    await cp(sourcePath, destinationPath, {
+        filter: options.filter,
+        force: true,
+        recursive: true
+    });
+};
+export const ensureDirectory = async (directoryPath) => {
+    await mkdir(directoryPath, { recursive: true });
+};
+export const fileExists = async (filePath) => {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const isSymlink = async (filePath) => {
+    try {
+        const stats = await lstat(filePath);
+        return stats.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+export const readUtf8File = async (filePath) => readFile(filePath, "utf8");
+export const ensureGitignoreEntry = async (directoryPath, entry) => {
+    const gitignorePath = path.join(directoryPath, ".gitignore");
+    const normalizedEntry = entry.trim();
+    if (normalizedEntry.length === 0) {
+        return false;
+    }
+    const existingSource = (await fileExists(gitignorePath)) ? await readUtf8File(gitignorePath) : "";
+    const existingEntries = new Set(existingSource
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0));
+    if (existingEntries.has(normalizedEntry)) {
+        return false;
+    }
+    const nextSource = existingSource.length === 0
+        ? `${normalizedEntry}\n`
+        : `${existingSource}${existingSource.endsWith("\n") ? "" : "\n"}${normalizedEntry}\n`;
+    await writeUtf8File(gitignorePath, nextSource);
+    return true;
+};
+export const removeDirectory = async (directoryPath) => {
+    await rm(directoryPath, { force: true, recursive: true });
+};
+export const writeUtf8File = async (filePath, content) => {
+    await writeFile(filePath, content, "utf8");
+};

package/dist/filesystem/paths.d.ts

@@ -0,0 +1,6 @@
+export declare const assertPortableRelativePath: (inputPath: string) => void;
+export declare const getCanonicalManifestPath: (filePath: string) => string;
+export declare const getManifestPath: (inputPath: string) => string;
+export declare const getProjectRoot: (manifestPath: string) => string;
+export declare const resolveProjectPath: (manifestPath: string, relativePath: string) => string;
+export declare const toPosixPath: (value: string) => string;

package/dist/filesystem/paths.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+const INVALID_PATH_SEGMENT = "..";
+export const assertPortableRelativePath = (inputPath) => {
+    if (inputPath.includes("\\")) {
+        throw new SpawnfileError("validation_error", `Paths must use forward slashes: ${inputPath}`);
+    }
+    if (path.isAbsolute(inputPath)) {
+        throw new SpawnfileError("validation_error", `Absolute paths are not allowed: ${inputPath}`);
+    }
+    const segments = inputPath.split("/");
+    if (segments.includes(INVALID_PATH_SEGMENT)) {
+        throw new SpawnfileError("validation_error", `Path traversal is not allowed: ${inputPath}`);
+    }
+};
+export const getCanonicalManifestPath = (filePath) => path.resolve(filePath);
+export const getManifestPath = (inputPath) => path.basename(inputPath) === "Spawnfile"
+    ? path.resolve(inputPath)
+    : path.resolve(inputPath, "Spawnfile");
+export const getProjectRoot = (manifestPath) => path.dirname(manifestPath);
+export const resolveProjectPath = (manifestPath, relativePath) => {
+    assertPortableRelativePath(relativePath);
+    const projectRoot = getProjectRoot(manifestPath);
+    const resolved = path.resolve(projectRoot, relativePath);
+    if (!resolved.startsWith(projectRoot + path.sep) && resolved !== projectRoot) {
+        throw new SpawnfileError("validation_error", `Path escapes project root: ${relativePath}`);
+    }
+    return resolved;
+};
+export const toPosixPath = (value) => value.split(path.sep).join("/");

package/dist/manifest/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./loadManifest.js";
+export * from "./renderSpawnfile.js";
+export * from "./scaffold.js";
+export * from "./schemas.js";
+export * from "./skillFrontmatter.js";

package/dist/manifest/index.js

@@ -0,0 +1,5 @@
+export * from "./loadManifest.js";
+export * from "./renderSpawnfile.js";
+export * from "./scaffold.js";
+export * from "./schemas.js";
+export * from "./skillFrontmatter.js";

package/dist/manifest/loadManifest.d.ts

@@ -0,0 +1,12 @@
+import { ExecutionBlock, Manifest, RuntimeBinding } from "./schemas.js";
+export interface LoadedManifest<TManifest extends Manifest = Manifest> {
+    manifest: TManifest;
+    manifestPath: string;
+}
+export declare const loadManifest: (manifestPath: string) => Promise<LoadedManifest>;
+export interface NormalizedRuntimeBinding {
+    name: string;
+    options: Record<string, unknown>;
+}
+export declare const normalizeRuntimeBinding: (runtime: RuntimeBinding | undefined) => NormalizedRuntimeBinding | undefined;
+export declare const mergeExecution: (parentExecution: ExecutionBlock | undefined, childExecution: ExecutionBlock | undefined) => ExecutionBlock | undefined;

package/dist/manifest/loadManifest.js

@@ -0,0 +1,208 @@
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { fileExists, isSymlink, readUtf8File, resolveProjectPath } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { isAgentManifest, isTeamManifest, manifestSchema } from "./schemas.js";
+import { parseSkillFrontmatter } from "./skillFrontmatter.js";
+const ensureUniqueNames = (names, label) => {
+    const seen = new Set();
+    for (const name of names) {
+        if (seen.has(name)) {
+            throw new SpawnfileError("validation_error", `Duplicate ${label}: ${name}`);
+        }
+        seen.add(name);
+    }
+};
+const getMcpNames = (mcpServers) => new Set((mcpServers ?? []).map((server) => server.name));
+const validateSkillRequirements = (skills, visibleMcpNames) => {
+    for (const skill of skills ?? []) {
+        for (const mcpName of skill.requires?.mcp ?? []) {
+            if (!visibleMcpNames.has(mcpName)) {
+                throw new SpawnfileError("validation_error", `Skill ${skill.ref} requires undeclared MCP server: ${mcpName}`);
+            }
+        }
+    }
+};
+const MARKDOWN_EXTENSION_PATTERN = /\.(md|markdown)$/i;
+const assertMarkdownDocumentPath = (documentPath) => {
+    if (!MARKDOWN_EXTENSION_PATTERN.test(documentPath)) {
+        throw new SpawnfileError("validation_error", `Document paths must point to Markdown files: ${documentPath}`);
+    }
+};
+const validateDocFiles = async (manifestPath, manifest) => {
+    const docs = manifest.docs;
+    if (!docs) {
+        return;
+    }
+    const docPaths = [
+        docs.heartbeat,
+        docs.identity,
+        docs.memory,
+        docs.soul,
+        docs.system,
+        ...Object.values(docs.extras ?? {})
+    ].filter((value) => Boolean(value));
+    await Promise.all(docPaths.map(async (documentPath) => {
+        assertMarkdownDocumentPath(documentPath);
+        const resolvedPath = resolveProjectPath(manifestPath, documentPath);
+        if (await isSymlink(resolvedPath)) {
+            throw new SpawnfileError("validation_error", `Symlinks are not allowed: ${documentPath}`);
+        }
+        if (!(await fileExists(resolvedPath))) {
+            throw new SpawnfileError("validation_error", `Document not found for manifest ${manifestPath}: ${documentPath}`);
+        }
+    }));
+};
+const validateManifestRefs = async (manifestPath, refs, label) => {
+    await Promise.all((refs ?? []).map(async (ref) => {
+        const refDirectoryPath = resolveProjectPath(manifestPath, ref);
+        if (await isSymlink(refDirectoryPath)) {
+            throw new SpawnfileError("validation_error", `Symlinks are not allowed: ${ref}`);
+        }
+        const childManifestPath = path.join(refDirectoryPath, "Spawnfile");
+        if (await isSymlink(childManifestPath)) {
+            throw new SpawnfileError("validation_error", `Symlinks are not allowed: ${ref}/Spawnfile`);
+        }
+        if (!(await fileExists(childManifestPath))) {
+            throw new SpawnfileError("validation_error", `${label} ref must point to a directory containing a Spawnfile: ${ref}`);
+        }
+    }));
+};
+const validateSkills = async (manifestPath, skills) => {
+    await Promise.all((skills ?? []).map(async (skill) => {
+        const skillDirPath = resolveProjectPath(manifestPath, skill.ref);
+        if (await isSymlink(skillDirPath)) {
+            throw new SpawnfileError("validation_error", `Symlinks are not allowed: ${skill.ref}`);
+        }
+        const skillFilePath = resolveProjectPath(manifestPath, `${skill.ref}/SKILL.md`);
+        if (await isSymlink(skillFilePath)) {
+            throw new SpawnfileError("validation_error", `Symlinks are not allowed: ${skill.ref}/SKILL.md`);
+        }
+        if (!(await fileExists(skillFilePath))) {
+            throw new SpawnfileError("validation_error", `Skill directory missing SKILL.md: ${skill.ref}`);
+        }
+        parseSkillFrontmatter(await readUtf8File(skillFilePath));
+    }));
+};
+const validateLocalAgentManifest = async (manifestPath, manifest) => {
+    ensureUniqueNames((manifest.mcp_servers ?? []).map((server) => server.name), "MCP server");
+    ensureUniqueNames((manifest.subagents ?? []).map((subagent) => subagent.id), "subagent id");
+    await validateDocFiles(manifestPath, manifest);
+    await validateSkills(manifestPath, manifest.skills);
+    await validateManifestRefs(manifestPath, manifest.subagents?.map((subagent) => subagent.ref), "Subagent");
+    validateSkillRequirements(manifest.skills, getMcpNames(manifest.mcp_servers));
+};
+const getSharedMcpNames = (shared) => getMcpNames(shared?.mcp_servers);
+const validateLocalTeamManifest = async (manifestPath, manifest) => {
+    ensureUniqueNames((manifest.shared?.mcp_servers ?? []).map((server) => server.name), "MCP server");
+    ensureUniqueNames(manifest.members.map((member) => member.id), "member id");
+    await validateDocFiles(manifestPath, manifest);
+    await validateSkills(manifestPath, manifest.shared?.skills);
+    await validateManifestRefs(manifestPath, manifest.members.map((member) => member.ref), "Member");
+    validateSkillRequirements(manifest.shared?.skills, getSharedMcpNames(manifest.shared));
+    const memberIds = new Set(manifest.members.map((member) => member.id));
+    if (manifest.structure.leader && !memberIds.has(manifest.structure.leader)) {
+        throw new SpawnfileError("validation_error", `Structure leader is not a declared team member: ${manifest.structure.leader}`);
+    }
+    for (const id of manifest.structure.external ?? []) {
+        if (!memberIds.has(id)) {
+            throw new SpawnfileError("validation_error", `Structure external references undeclared member: ${id}`);
+        }
+    }
+};
+const parseManifest = (source) => {
+    try {
+        return manifestSchema.parse(parseYaml(source));
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const issue = error.issues[0];
+            throw new SpawnfileError("invalid_manifest", `Invalid Spawnfile manifest: ${issue.message}`);
+        }
+        throw error;
+    }
+};
+export const loadManifest = async (manifestPath) => {
+    const source = await readUtf8File(manifestPath);
+    const manifest = parseManifest(source);
+    if (isAgentManifest(manifest)) {
+        await validateLocalAgentManifest(manifestPath, manifest);
+    }
+    if (isTeamManifest(manifest)) {
+        await validateLocalTeamManifest(manifestPath, manifest);
+    }
+    return { manifest, manifestPath };
+};
+export const normalizeRuntimeBinding = (runtime) => {
+    if (!runtime) {
+        return undefined;
+    }
+    if (typeof runtime === "string") {
+        return { name: runtime, options: {} };
+    }
+    return {
+        name: runtime.name,
+        options: runtime.options ?? {}
+    };
+};
+export const mergeExecution = (parentExecution, childExecution) => {
+    if (!parentExecution) {
+        return childExecution;
+    }
+    if (!childExecution) {
+        return parentExecution;
+    }
+    const model = parentExecution.model || childExecution.model
+        ? {
+            auth: childExecution.model?.auth ?? parentExecution.model?.auth,
+            fallback: childExecution.model?.fallback ?? parentExecution.model?.fallback,
+            primary: childExecution.model?.primary ?? parentExecution.model?.primary
+        }
+        : undefined;
+    if (model && !model.primary) {
+        throw new SpawnfileError("validation_error", "Merged execution model is missing a primary model");
+    }
+    const sandbox = parentExecution.sandbox || childExecution.sandbox
+        ? {
+            ...parentExecution.sandbox,
+            ...childExecution.sandbox
+        }
+        : undefined;
+    if (sandbox && !sandbox.mode) {
+        throw new SpawnfileError("validation_error", "Merged execution sandbox is missing mode");
+    }
+    const workspace = parentExecution.workspace || childExecution.workspace
+        ? {
+            ...parentExecution.workspace,
+            ...childExecution.workspace
+        }
+        : undefined;
+    if (workspace && !workspace.isolation) {
+        throw new SpawnfileError("validation_error", "Merged execution workspace is missing isolation");
+    }
+    const resolvedModel = model
+        ? {
+            auth: model.auth,
+            fallback: model.fallback,
+            primary: model.primary
+        }
+        : undefined;
+    const resolvedSandbox = sandbox
+        ? {
+            mode: sandbox.mode
+        }
+        : undefined;
+    const resolvedWorkspace = workspace
+        ? {
+            isolation: workspace.isolation
+        }
+        : undefined;
+    return {
+        ...parentExecution,
+        ...childExecution,
+        model: resolvedModel,
+        sandbox: resolvedSandbox,
+        workspace: resolvedWorkspace
+    };
+};

package/dist/manifest/renderSpawnfile.d.ts

@@ -0,0 +1,2 @@
+import type { AgentManifest, TeamManifest } from "./schemas.js";
+export declare const renderSpawnfile: (manifest: AgentManifest | TeamManifest) => string;

package/dist/manifest/renderSpawnfile.js

@@ -0,0 +1,211 @@
+import YAML from "yaml";
+const withDefinedEntries = (entries) => Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
+const hasEntries = (value) => Object.keys(value).length > 0;
+const orderRuntimeBinding = (runtime) => {
+    if (!runtime || typeof runtime === "string") {
+        return runtime;
+    }
+    return withDefinedEntries([
+        ["name", runtime.name],
+        ["options", runtime.options]
+    ]);
+};
+const orderDocs = (docs) => {
+    if (!docs) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["identity", docs.identity],
+        ["soul", docs.soul],
+        ["system", docs.system],
+        ["memory", docs.memory],
+        ["heartbeat", docs.heartbeat],
+        ["extras", docs.extras]
+    ]);
+};
+const orderDiscordSurface = (surface) => {
+    if (!surface) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["access", orderDiscordSurfaceAccess(surface.access)],
+        ["bot_token_secret", surface.bot_token_secret]
+    ]);
+};
+const orderDiscordSurfaceAccess = (access) => {
+    if (!access) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["mode", access.mode],
+        ["users", access.users],
+        ["guilds", access.guilds],
+        ["channels", access.channels]
+    ]);
+};
+const orderTelegramSurface = (surface) => {
+    if (!surface) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["access", orderTelegramSurfaceAccess(surface.access)],
+        ["bot_token_secret", surface.bot_token_secret]
+    ]);
+};
+const orderTelegramSurfaceAccess = (access) => {
+    if (!access) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["mode", access.mode],
+        ["users", access.users],
+        ["chats", access.chats]
+    ]);
+};
+const orderWhatsAppSurface = (surface) => {
+    if (!surface) {
+        return undefined;
+    }
+    return withDefinedEntries([["access", orderWhatsAppSurfaceAccess(surface.access)]]);
+};
+const orderWhatsAppSurfaceAccess = (access) => {
+    if (!access) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["mode", access.mode],
+        ["users", access.users],
+        ["groups", access.groups]
+    ]);
+};
+const orderSlackSurface = (surface) => {
+    if (!surface) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["access", orderSlackSurfaceAccess(surface.access)],
+        ["bot_token_secret", surface.bot_token_secret],
+        ["app_token_secret", surface.app_token_secret]
+    ]);
+};
+const orderSlackSurfaceAccess = (access) => {
+    if (!access) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["mode", access.mode],
+        ["users", access.users],
+        ["channels", access.channels]
+    ]);
+};
+const orderModelEntryAuth = (auth) => {
+    if (!auth) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["method", auth.method],
+        ["key", auth.key]
+    ]);
+};
+const orderModelTarget = (target) => {
+    if (!target) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["provider", target.provider],
+        ["name", target.name],
+        ["auth", orderModelEntryAuth(target.auth)],
+        ["endpoint", target.endpoint]
+    ]);
+};
+const orderExecution = (execution) => {
+    if (!execution) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        [
+            "model",
+            execution.model
+                ? withDefinedEntries([
+                    ["primary", orderModelTarget(execution.model.primary)],
+                    ["fallback", execution.model.fallback?.map(orderModelTarget)],
+                    ["auth", execution.model.auth]
+                ])
+                : undefined
+        ],
+        ["workspace", execution.workspace],
+        ["sandbox", execution.sandbox]
+    ]);
+};
+const orderSharedSurface = (shared) => {
+    if (!shared) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["env", shared.env],
+        ["mcp_servers", shared.mcp_servers],
+        ["secrets", shared.secrets],
+        ["skills", shared.skills]
+    ]);
+};
+const orderSurfaces = (surfaces) => {
+    if (!surfaces) {
+        return undefined;
+    }
+    return withDefinedEntries([
+        ["discord", orderDiscordSurface(surfaces.discord)],
+        ["telegram", orderTelegramSurface(surfaces.telegram)],
+        ["whatsapp", orderWhatsAppSurface(surfaces.whatsapp)],
+        ["slack", orderSlackSurface(surfaces.slack)]
+    ]);
+};
+const renderSections = (sections) => sections
+    .filter(hasEntries)
+    .map((section) => YAML.stringify(section))
+    .join("\n");
+const orderAgentManifestSections = (manifest) => [
+    withDefinedEntries([
+        ["spawnfile_version", manifest.spawnfile_version],
+        ["kind", manifest.kind],
+        ["name", manifest.name]
+    ]),
+    withDefinedEntries([["runtime", orderRuntimeBinding(manifest.runtime)]]),
+    withDefinedEntries([["execution", orderExecution(manifest.execution)]]),
+    withDefinedEntries([["docs", orderDocs(manifest.docs)]]),
+    withDefinedEntries([["surfaces", orderSurfaces(manifest.surfaces)]]),
+    withDefinedEntries([
+        ["skills", manifest.skills],
+        ["mcp_servers", manifest.mcp_servers],
+        ["secrets", manifest.secrets],
+        ["env", manifest.env],
+        ["policy", manifest.policy]
+    ]),
+    withDefinedEntries([["subagents", manifest.subagents]])
+];
+const orderTeamManifestSections = (manifest) => [
+    withDefinedEntries([
+        ["spawnfile_version", manifest.spawnfile_version],
+        ["kind", manifest.kind],
+        ["name", manifest.name]
+    ]),
+    withDefinedEntries([["runtime", orderRuntimeBinding(manifest.runtime)]]),
+    withDefinedEntries([["execution", orderExecution(manifest.execution)]]),
+    withDefinedEntries([
+        ["docs", orderDocs(manifest.docs)],
+        ["shared", orderSharedSurface(manifest.shared)]
+    ]),
+    withDefinedEntries([
+        ["skills", manifest.skills],
+        ["mcp_servers", manifest.mcp_servers],
+        ["secrets", manifest.secrets],
+        ["env", manifest.env],
+        ["policy", manifest.policy]
+    ]),
+    withDefinedEntries([
+        ["members", manifest.members],
+        ["structure", manifest.structure]
+    ])
+];
+export const renderSpawnfile = (manifest) => renderSections(manifest.kind === "agent"
+    ? orderAgentManifestSections(manifest)
+    : orderTeamManifestSections(manifest));

package/dist/manifest/scaffold.d.ts

@@ -0,0 +1,16 @@
+import type { AgentManifest, TeamManifest } from "./schemas.js";
+import type { ModelAuthMethod } from "../shared/index.js";
+export interface AgentScaffoldManifestOptions {
+    authMethod?: ModelAuthMethod;
+    docs: {
+        identity?: string;
+        soul?: string;
+        system: string;
+    };
+    modelName: string;
+    name?: string;
+    provider: string;
+    runtime: string;
+}
+export declare const createAgentScaffoldManifest: (options: AgentScaffoldManifestOptions) => AgentManifest;
+export declare const createTeamScaffoldManifest: () => TeamManifest;

package/dist/manifest/scaffold.js

@@ -0,0 +1,41 @@
+export const createAgentScaffoldManifest = (options) => {
+    const authMethod = options.authMethod;
+    return {
+        spawnfile_version: "0.1",
+        kind: "agent",
+        name: options.name ?? "my-agent",
+        runtime: options.runtime,
+        execution: {
+            model: {
+                ...(authMethod
+                    ? {
+                        auth: {
+                            method: authMethod
+                        }
+                    }
+                    : {}),
+                primary: {
+                    name: options.modelName,
+                    provider: options.provider
+                }
+            }
+        },
+        docs: {
+            ...(options.docs.identity ? { identity: options.docs.identity } : {}),
+            ...(options.docs.soul ? { soul: options.docs.soul } : {}),
+            system: options.docs.system
+        }
+    };
+};
+export const createTeamScaffoldManifest = () => ({
+    spawnfile_version: "0.1",
+    kind: "team",
+    name: "my-team",
+    docs: {
+        system: "TEAM.md"
+    },
+    members: [],
+    structure: {
+        mode: "swarm"
+    }
+});