@plico-ai/core 0.0.0-reserved.0 → 0.1.0

package/NOTICE

@@ -0,0 +1,4 @@
+Plico
+Copyright 2026 Plico contributors
+
+This product includes software developed by the Plico contributors.

package/README.md

@@ -1,6 +1,10 @@
 # @plico-ai/core
 
-Project loading and validation for Plico.
+Core project-loading and validation helpers for Plico.
 
-This is a pre-release placeholder. The first developer preview is in progress at
-https://github.com/ITZSHOAIB/plico. Docs: https://plico.sohab.dev
+## API
+
+- `loadProject(root)` loads `plico.config.ts` and returns the normalized project config
+- `validateProject(root)` validates the project shape, required files and directories, and duplicate tool names
+
+This package stays local-first and file-first. It does not know about runtime execution or provider-specific agent abstractions.

package/dist/agent-file.d.ts

@@ -0,0 +1,8 @@
+import { type Frontmatter } from "./frontmatter.js";
+import type { ValidationIssue } from "./types.js";
+/** Frontmatter keys `agent.md` understands. Later features add keys here without breaking projects. */
+export declare const AGENT_FRONTMATTER_KEYS: readonly string[];
+/** Splits `agent.md` into its frontmatter and the instructions the model sees. */
+export declare function parseAgentFile(text: string): Frontmatter;
+/** One warning per frontmatter key that `agent.md` does not understand. */
+export declare function unknownAgentKeyWarnings(path: string, data: Frontmatter["data"]): ValidationIssue[];

package/dist/agent-file.js

@@ -0,0 +1,17 @@
+import { parseFrontmatter } from "./frontmatter.js";
+/** Frontmatter keys `agent.md` understands. Later features add keys here without breaking projects. */
+export const AGENT_FRONTMATTER_KEYS = [];
+/** Splits `agent.md` into its frontmatter and the instructions the model sees. */
+export function parseAgentFile(text) {
+    return parseFrontmatter(text);
+}
+/** One warning per frontmatter key that `agent.md` does not understand. */
+export function unknownAgentKeyWarnings(path, data) {
+    return Object.keys(data)
+        .filter((key) => !AGENT_FRONTMATTER_KEYS.includes(key))
+        .map((key) => ({
+        path,
+        message: `Unknown frontmatter key "${key}" in ${path}. It is ignored and never sent to the model.`,
+        severity: "warning",
+    }));
+}

package/dist/authoring.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Project files import `@plico-ai/sdk` for `defineConfig` and `defineTool`. Those helpers return
+ * their argument unchanged, so any copy works. A project run by a global `plico` CLI may have no
+ * node_modules of its own; resolution falls back to the copy that ships with this install.
+ */
+export declare const SPECIFIER = "@plico-ai/sdk";
+/** The file URL the `@plico-ai/sdk` specifier should resolve to for a file in `fromFile`'s project. */
+export declare function resolveAuthoringModule(fromFile: string): string;
+/** Point `import "@plico-ai/sdk"` in a transpiled project file at an absolute file URL. */
+export declare function rewriteAuthoringImports(code: string, fromFile: string): string;
+/** Make `import "@plico-ai/sdk"` and `require("@plico-ai/sdk")` fall back to this install when a tool file cannot resolve it. */
+export declare function installAuthoringFallback(): void;

package/dist/authoring.js

@@ -0,0 +1,64 @@
+import Module, { createRequire, register } from "node:module";
+import { dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * Project files import `@plico-ai/sdk` for `defineConfig` and `defineTool`. Those helpers return
+ * their argument unchanged, so any copy works. A project run by a global `plico` CLI may have no
+ * node_modules of its own; resolution falls back to the copy that ships with this install.
+ */
+export const SPECIFIER = "@plico-ai/sdk";
+function ownEntry() {
+    return createRequire(import.meta.url).resolve(SPECIFIER);
+}
+/** The file URL the `@plico-ai/sdk` specifier should resolve to for a file in `fromFile`'s project. */
+export function resolveAuthoringModule(fromFile) {
+    try {
+        return pathToFileURL(createRequire(fromFile).resolve(SPECIFIER)).href;
+    }
+    catch {
+        return pathToFileURL(ownEntry()).href;
+    }
+}
+/** Point `import "@plico-ai/sdk"` in a transpiled project file at an absolute file URL. */
+export function rewriteAuthoringImports(code, fromFile) {
+    return code.replace(/(\bfrom\s*|\bimport\s*)(["'])@plico-ai\/sdk\2/g, (_match, keyword) => `${keyword}${JSON.stringify(resolveAuthoringModule(fromFile))}`);
+}
+const ESM_HOOKS = `
+let fallback;
+export function initialize(data) { fallback = data.url; }
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (error) {
+    if (specifier === "${SPECIFIER}" && error?.code === "ERR_MODULE_NOT_FOUND") {
+      return { url: fallback, shortCircuit: true };
+    }
+    throw error;
+  }
+}
+`;
+let installed = false;
+/** Make `import "@plico-ai/sdk"` and `require("@plico-ai/sdk")` fall back to this install when a tool file cannot resolve it. */
+export function installAuthoringFallback() {
+    if (installed)
+        return;
+    installed = true;
+    const entry = ownEntry();
+    register(`data:text/javascript,${encodeURIComponent(ESM_HOOKS)}`, {
+        parentURL: pathToFileURL(`${dirname(entry)}/`).href,
+        data: { url: pathToFileURL(entry).href },
+    });
+    const internals = Module;
+    const original = internals._resolveFilename;
+    internals._resolveFilename = function resolveWithFallback(request, ...rest) {
+        try {
+            return original.call(this, request, ...rest);
+        }
+        catch (error) {
+            const code = error.code;
+            if (request === SPECIFIER && code === "MODULE_NOT_FOUND")
+                return entry;
+            throw error;
+        }
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedProject } from "./types.js";
+export declare function loadProject(root: string): Promise<LoadedProject>;

package/dist/config.js

@@ -0,0 +1,307 @@
+import { readFile, stat } from "node:fs/promises";
+import { transform } from "esbuild";
+import { rewriteAuthoringImports } from "./authoring.js";
+import { configLoadMessage, missingFileMessage, ProjectConfigError } from "./errors.js";
+import { getProjectPaths, getProjectRelativePaths } from "./layout.js";
+export async function loadProject(root) {
+    const configPath = getProjectPaths(root).configFile;
+    const config = await readProjectConfig(configPath);
+    return {
+        root,
+        configPath,
+        config,
+    };
+}
+async function readProjectConfig(configPath) {
+    const relativePaths = getProjectRelativePaths();
+    try {
+        await stat(configPath);
+    }
+    catch (error) {
+        throw new ProjectConfigError(configPath, [
+            {
+                path: relativePaths.configFile,
+                message: missingFileMessage(error),
+                severity: "error",
+            },
+        ]);
+    }
+    let configModule;
+    try {
+        configModule = await importTranspiledProjectConfig(configPath);
+    }
+    catch (error) {
+        throw new ProjectConfigError(configPath, [
+            {
+                path: relativePaths.configFile,
+                message: configLoadMessage(error),
+                severity: "error",
+            },
+        ]);
+    }
+    const exportedConfig = readDefaultExport(configModule, configPath);
+    return normalizeProjectConfig(exportedConfig, configPath);
+}
+async function importTranspiledProjectConfig(configPath) {
+    const source = await readFile(configPath, "utf8");
+    const transpiled = await transform(source, {
+        loader: "ts",
+        format: "esm",
+        target: "es2022",
+        sourcefile: configPath,
+    });
+    const code = rewriteAuthoringImports(transpiled.code, configPath);
+    const encoded = Buffer.from(code, "utf8").toString("base64");
+    const moduleUrl = `data:text/javascript;base64,${encoded}`;
+    return import(moduleUrl);
+}
+function readDefaultExport(configModule, configPath) {
+    const relativePaths = getProjectRelativePaths();
+    if (!isRecord(configModule) || !Object.hasOwn(configModule, "default")) {
+        throw new ProjectConfigError(configPath, [
+            {
+                path: relativePaths.configFile,
+                message: `Missing default export in ${relativePaths.configFile}`,
+                severity: "error",
+            },
+        ]);
+    }
+    return unwrapDefaultExport(configModule.default);
+}
+function normalizeProjectConfig(value, configPath) {
+    const issues = validateProjectConfigShape(value);
+    if (issues.length > 0) {
+        throw new ProjectConfigError(configPath, issues);
+    }
+    const config = value;
+    const normalized = {
+        schemaVersion: config.schemaVersion,
+        name: config.name,
+        artifacts: { access: config.artifacts?.access ?? "read-write" },
+    };
+    if (typeof config.description === "string") {
+        normalized.description = config.description;
+    }
+    if (typeof config.template === "string") {
+        normalized.template = config.template;
+    }
+    if (config.model !== undefined) {
+        normalized.model = { provider: config.model.provider, name: config.model.name };
+        if (config.model.baseURL !== undefined)
+            normalized.model.baseURL = config.model.baseURL;
+        if (config.model.apiKeyEnv !== undefined)
+            normalized.model.apiKeyEnv = config.model.apiKeyEnv;
+        if (config.model.maxSteps !== undefined)
+            normalized.model.maxSteps = config.model.maxSteps;
+        if (config.model.retries !== undefined)
+            normalized.model.retries = config.model.retries;
+        if (config.model.retryDelayMs !== undefined)
+            normalized.model.retryDelayMs = config.model.retryDelayMs;
+    }
+    if (config.execution !== undefined) {
+        normalized.execution = {};
+        if (config.execution.leaseMs !== undefined)
+            normalized.execution.leaseMs = config.execution.leaseMs;
+    }
+    if (config.threads !== undefined) {
+        normalized.threads = {};
+        if (config.threads.title !== undefined)
+            normalized.threads.title = config.threads.title;
+    }
+    if (config.approvals !== undefined) {
+        normalized.approvals = {};
+        if (config.approvals.default !== undefined)
+            normalized.approvals.default = config.approvals.default;
+        if (config.approvals.timeoutMs !== undefined)
+            normalized.approvals.timeoutMs = config.approvals.timeoutMs;
+        if (config.approvals.tools !== undefined)
+            normalized.approvals.tools = { ...config.approvals.tools };
+    }
+    return normalized;
+}
+function validateProjectConfigShape(value) {
+    const relativePaths = getProjectRelativePaths();
+    const issues = [];
+    if (!isRecord(value) || Array.isArray(value)) {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Expected default export to be an object",
+            severity: "error",
+        });
+        return issues;
+    }
+    if (!Object.hasOwn(value, "schemaVersion")) {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Missing required field: schemaVersion",
+            severity: "error",
+        });
+    }
+    else if (!Number.isInteger(value.schemaVersion)) {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Expected schemaVersion to be an integer",
+            severity: "error",
+        });
+    }
+    if (!Object.hasOwn(value, "name")) {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Missing required field: name",
+            severity: "error",
+        });
+    }
+    else if (typeof value.name !== "string") {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Expected name to be a string",
+            severity: "error",
+        });
+    }
+    if (Object.hasOwn(value, "description") && typeof value.description !== "string") {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Expected description to be a string",
+            severity: "error",
+        });
+    }
+    if (Object.hasOwn(value, "template") && typeof value.template !== "string") {
+        issues.push({
+            path: relativePaths.configFile,
+            message: "Expected template to be a string",
+            severity: "error",
+        });
+    }
+    if (Object.hasOwn(value, "artifacts") &&
+        (!isRecord(value.artifacts) ||
+            Array.isArray(value.artifacts) ||
+            (value.artifacts.access !== "read-write" &&
+                value.artifacts.access !== "read-only" &&
+                value.artifacts.access !== "off"))) {
+        issues.push({
+            path: relativePaths.configFile,
+            message: 'Expected artifacts.access to be "read-write", "read-only", or "off"',
+            severity: "error",
+        });
+    }
+    if (Object.hasOwn(value, "model")) {
+        const model = value.model;
+        if (!isRecord(model) ||
+            Array.isArray(model) ||
+            typeof model.provider !== "string" ||
+            !model.provider.trim() ||
+            typeof model.name !== "string" ||
+            !model.name.trim() ||
+            (Object.hasOwn(model, "baseURL") &&
+                (typeof model.baseURL !== "string" || !model.baseURL.trim())) ||
+            (Object.hasOwn(model, "apiKeyEnv") &&
+                (typeof model.apiKeyEnv !== "string" || !/^[A-Za-z_]\w*$/.test(model.apiKeyEnv))) ||
+            (Object.hasOwn(model, "maxSteps") &&
+                (!Number.isSafeInteger(model.maxSteps) || Number(model.maxSteps) <= 0)) ||
+            (Object.hasOwn(model, "retries") &&
+                (!Number.isSafeInteger(model.retries) ||
+                    Number(model.retries) < 0 ||
+                    Number(model.retries) > 10)) ||
+            (Object.hasOwn(model, "retryDelayMs") &&
+                (!Number.isSafeInteger(model.retryDelayMs) ||
+                    Number(model.retryDelayMs) < 0 ||
+                    Number(model.retryDelayMs) > 60000))) {
+            issues.push({
+                path: relativePaths.configFile,
+                message: "Expected non-empty model.provider and model.name, string model.baseURL and model.apiKeyEnv (a variable name), positive model.maxSteps, retries between 0 and 10, and retryDelayMs between 0 and 60000",
+                severity: "error",
+            });
+        }
+    }
+    if (Object.hasOwn(value, "execution")) {
+        const execution = value.execution;
+        if (!isRecord(execution) ||
+            Array.isArray(execution) ||
+            (Object.hasOwn(execution, "leaseMs") &&
+                (!Number.isSafeInteger(execution.leaseMs) || Number(execution.leaseMs) <= 0))) {
+            issues.push({
+                path: relativePaths.configFile,
+                message: "Expected execution.leaseMs to be a positive integer",
+                severity: "error",
+            });
+        }
+    }
+    if (Object.hasOwn(value, "threads")) {
+        const threads = value.threads;
+        if (!isRecord(threads) ||
+            Array.isArray(threads) ||
+            (Object.hasOwn(threads, "title") && threads.title !== "keywords" && threads.title !== "model")) {
+            issues.push({
+                path: relativePaths.configFile,
+                message: 'Expected threads.title to be "keywords" or "model"',
+                severity: "error",
+            });
+        }
+    }
+    if (Object.hasOwn(value, "approvals")) {
+        const approvals = value.approvals;
+        if (!isRecord(approvals) || Array.isArray(approvals)) {
+            issues.push({
+                path: relativePaths.configFile,
+                message: "Expected approvals to be an object",
+                severity: "error",
+            });
+        }
+        else {
+            if (Object.hasOwn(approvals, "default") &&
+                approvals.default !== "none" &&
+                approvals.default !== "required") {
+                issues.push({
+                    path: relativePaths.configFile,
+                    message: 'Expected approvals.default to be "none" or "required"',
+                    severity: "error",
+                });
+            }
+            if (Object.hasOwn(approvals, "timeoutMs") &&
+                (!Number.isSafeInteger(approvals.timeoutMs) || Number(approvals.timeoutMs) <= 0)) {
+                issues.push({
+                    path: relativePaths.configFile,
+                    message: "Expected approvals.timeoutMs to be a positive integer",
+                    severity: "error",
+                });
+            }
+            if (Object.hasOwn(approvals, "tools")) {
+                const tools = approvals.tools;
+                if (!isRecord(tools) || Array.isArray(tools)) {
+                    issues.push({
+                        path: relativePaths.configFile,
+                        message: "Expected approvals.tools to be an object",
+                        severity: "error",
+                    });
+                }
+                else {
+                    for (const [name, value2] of Object.entries(tools)) {
+                        if (value2 !== "none" && value2 !== "required") {
+                            issues.push({
+                                path: relativePaths.configFile,
+                                message: `Expected approvals.tools.${name} to be "none" or "required"`,
+                                severity: "error",
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function unwrapDefaultExport(value) {
+    let current = value;
+    while (isRecord(current) && Object.hasOwn(current, "default")) {
+        const keys = Object.keys(current);
+        const looksLikeLoaderWrapper = keys.length === 1 || (keys.length === 2 && keys.includes("module.exports"));
+        if (!looksLikeLoaderWrapper) {
+            break;
+        }
+        current = current.default;
+    }
+    return current;
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationIssue } from "./types.js";
+export declare class ProjectConfigError extends Error {
+    readonly configPath: string;
+    readonly issues: ValidationIssue[];
+    constructor(configPath: string, issues: ValidationIssue[]);
+}
+export declare function missingFileMessage(error: unknown): string;
+export declare function missingFileMessageFor(path: string, error: unknown): string;
+export declare function configLoadMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,31 @@
+import { getProjectRelativePaths } from "./layout.js";
+export class ProjectConfigError extends Error {
+    configPath;
+    issues;
+    constructor(configPath, issues) {
+        super(`Invalid config at ${configPath}`);
+        this.configPath = configPath;
+        this.issues = issues;
+    }
+}
+export function missingFileMessage(error) {
+    const relativePaths = getProjectRelativePaths();
+    if (error instanceof Error && error.message.includes("ENOENT")) {
+        return `Missing required file: ${relativePaths.configFile}`;
+    }
+    return `Unable to read ${relativePaths.configFile}`;
+}
+export function missingFileMessageFor(path, error) {
+    if (error instanceof Error && error.message.includes("ENOENT")) {
+        return `Missing required file: ${path}`;
+    }
+    return `Unable to read ${path}`;
+}
+export function configLoadMessage(error) {
+    const relativePaths = getProjectRelativePaths();
+    if (error instanceof Error && error.message) {
+        const detail = error.message.trim();
+        return `Failed to load ${relativePaths.configFile}: ${detail}`;
+    }
+    return `Failed to load ${relativePaths.configFile}`;
+}

package/dist/frontmatter.d.ts

@@ -0,0 +1,11 @@
+export interface Frontmatter {
+    /** Top-level scalar keys. Nested values are not supported. */
+    data: Record<string, string>;
+    /** The text after the closing `---` line, or the whole text when there is no frontmatter. */
+    body: string;
+}
+/**
+ * Splits a leading `---` block of `key: value` lines from the rest of a Markdown file. Values may
+ * be plain, single- or double-quoted, or a `>` (folded) or `|` (literal) block.
+ */
+export declare function parseFrontmatter(text: string): Frontmatter;

package/dist/frontmatter.js

@@ -0,0 +1,37 @@
+/**
+ * Splits a leading `---` block of `key: value` lines from the rest of a Markdown file. Values may
+ * be plain, single- or double-quoted, or a `>` (folded) or `|` (literal) block.
+ */
+export function parseFrontmatter(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trimEnd() !== "---")
+        return { data: {}, body: text };
+    const end = lines.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+    if (end === -1)
+        return { data: {}, body: text };
+    const data = {};
+    const block = lines.slice(1, end).map((line) => line.trimEnd());
+    for (let index = 0; index < block.length; index++) {
+        const match = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(block[index] ?? "");
+        if (!match)
+            continue;
+        const [, key = "", rawValue = ""] = match;
+        const style = /^([>|])[+-]?$/.exec(rawValue)?.[1];
+        if (!style) {
+            data[key] = unquote(rawValue.trim());
+            continue;
+        }
+        const continuation = [];
+        while (index + 1 < block.length && /^(\s|$)/.test(block[index + 1] ?? "")) {
+            continuation.push((block[++index] ?? "").trim());
+        }
+        data[key] = (style === ">" ? continuation.filter(Boolean).join(" ") : continuation.join("\n")).trim();
+    }
+    return { data, body: lines.slice(end + 1).join("\n") };
+}
+function unquote(value) {
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.length >= 2 && value.endsWith(quote))
+        return value.slice(1, -1);
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { AGENT_FRONTMATTER_KEYS, parseAgentFile } from "./agent-file.js";
+export { installAuthoringFallback } from "./authoring.js";
+export { loadProject } from "./config.js";
+export { type Frontmatter, parseFrontmatter } from "./frontmatter.js";
+export { getProjectPaths, getProjectRelativePaths, PROJECT_LAYOUT, REQUIRED_PROJECT_DIRECTORIES, } from "./layout.js";
+export { findProjectProviderFile, findProjectThreadTitleFile, NATIVE_MODEL_PROVIDERS, } from "./model-provider.js";
+export { readSkills, type Skill, type SkillsResult } from "./skills.js";
+export { ARTIFACT_TOOL_NAMES, SKILL_TOOL_NAME } from "./tool-name-validation.js";
+export type { LoadedProject, ProjectConfig, ProjectDirectoryRole, ProjectLayout, ProjectLayoutDirectories, ProjectPaths, ProjectRelativePaths, ValidationIssue, ValidationResult, ValidationSeverity, } from "./types.js";
+export { validateProject } from "./validation.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { AGENT_FRONTMATTER_KEYS, parseAgentFile } from "./agent-file.js";
+export { installAuthoringFallback } from "./authoring.js";
+export { loadProject } from "./config.js";
+export { parseFrontmatter } from "./frontmatter.js";
+export { getProjectPaths, getProjectRelativePaths, PROJECT_LAYOUT, REQUIRED_PROJECT_DIRECTORIES, } from "./layout.js";
+export { findProjectProviderFile, findProjectThreadTitleFile, NATIVE_MODEL_PROVIDERS, } from "./model-provider.js";
+export { readSkills } from "./skills.js";
+export { ARTIFACT_TOOL_NAMES, SKILL_TOOL_NAME } from "./tool-name-validation.js";
+export { validateProject } from "./validation.js";

package/dist/layout.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectDirectoryRole, ProjectLayout, ProjectPaths, ProjectRelativePaths } from "./types.js";
+export declare const PROJECT_LAYOUT: ProjectLayout;
+export declare const REQUIRED_PROJECT_DIRECTORIES: readonly ProjectDirectoryRole[];
+export declare function getProjectRelativePaths(): ProjectRelativePaths;
+export declare function getProjectPaths(root: string): ProjectPaths;

package/dist/layout.js

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+export const PROJECT_LAYOUT = {
+    configFile: "plico.config.ts",
+    agentFile: "agent.md",
+    directories: {
+        skills: "skills",
+        tools: "tools",
+        evals: "evals",
+        artifacts: "artifacts",
+        memory: "memory",
+    },
+};
+export const REQUIRED_PROJECT_DIRECTORIES = [
+    "skills",
+    "tools",
+    "evals",
+    "artifacts",
+    "memory",
+];
+export function getProjectRelativePaths() {
+    return {
+        configFile: PROJECT_LAYOUT.configFile,
+        agentFile: PROJECT_LAYOUT.agentFile,
+        directories: { ...PROJECT_LAYOUT.directories },
+    };
+}
+export function getProjectPaths(root) {
+    const relative = getProjectRelativePaths();
+    return {
+        configFile: join(root, relative.configFile),
+        agentFile: join(root, relative.agentFile),
+        directories: {
+            skills: join(root, relative.directories.skills),
+            tools: join(root, relative.directories.tools),
+            evals: join(root, relative.directories.evals),
+            artifacts: join(root, relative.directories.artifacts),
+            memory: join(root, relative.directories.memory),
+        },
+    };
+}

package/dist/model-provider.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectConfig, ValidationIssue } from "./types.js";
+/** Providers Plico ships adapters for. Anything else comes from `providers/<name>.ts`. */
+export declare const NATIVE_MODEL_PROVIDERS: readonly string[];
+/** The file in `providers/` that supplies `provider`, or `undefined` when there is none. */
+export declare function findProjectProviderFile(root: string, provider: string): Promise<string | undefined>;
+/** The `threads/title.ts` module that names threads, or `undefined` when the project has none. */
+export declare function findProjectThreadTitleFile(root: string): Promise<string | undefined>;
+/** `plico validate` fails on a provider that is neither native nor supplied by the project. */
+export declare function validateModelProvider(root: string, model: ProjectConfig["model"], configPath: string): Promise<ValidationIssue[]>;

package/dist/model-provider.js

@@ -0,0 +1,50 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+/** Providers Plico ships adapters for. Anything else comes from `providers/<name>.ts`. */
+export const NATIVE_MODEL_PROVIDERS = [
+    "anthropic",
+    "google",
+    "openai",
+    "openai-compatible",
+];
+const PROVIDER_EXTENSIONS = [".ts", ".mts", ".js", ".mjs"];
+/** The file in `providers/` that supplies `provider`, or `undefined` when there is none. */
+export async function findProjectProviderFile(root, provider) {
+    if (!/^[\w-]+$/.test(provider))
+        return undefined;
+    for (const extension of PROVIDER_EXTENSIONS) {
+        const file = join(root, "providers", `${provider}${extension}`);
+        try {
+            await access(file);
+            return file;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** The `threads/title.ts` module that names threads, or `undefined` when the project has none. */
+export async function findProjectThreadTitleFile(root) {
+    for (const extension of PROVIDER_EXTENSIONS) {
+        const file = join(root, "threads", `title${extension}`);
+        try {
+            await access(file);
+            return file;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** `plico validate` fails on a provider that is neither native nor supplied by the project. */
+export async function validateModelProvider(root, model, configPath) {
+    if (!model || NATIVE_MODEL_PROVIDERS.includes(model.provider))
+        return [];
+    if (await findProjectProviderFile(root, model.provider))
+        return [];
+    return [
+        {
+            path: configPath,
+            message: `Unknown model provider "${model.provider}". Use ${NATIVE_MODEL_PROVIDERS.join(", ")}, or add providers/${model.provider}.ts.`,
+            severity: "error",
+        },
+    ];
+}

package/dist/skills.d.ts

@@ -0,0 +1,19 @@
+import type { ValidationIssue } from "./types.js";
+export interface Skill {
+    /** The folder name. The agent loads the skill by this name. */
+    name: string;
+    description: string;
+    /** Project-relative path, such as `skills/triage/SKILL.md`. */
+    source: string;
+    /** The skill text without its frontmatter. */
+    body: string;
+}
+export interface SkillsResult {
+    /** Skills that have a description, sorted by folder name. */
+    skills: Skill[];
+    issues: ValidationIssue[];
+}
+/** Reads every `skills/<name>/SKILL.md` file. A file that cannot be read throws. */
+export declare function readSkills(root: string): Promise<SkillsResult>;
+/** Skill problems for `plico validate`. Unreadable files are left for the run to report. */
+export declare function validateSkills(root: string): Promise<ValidationIssue[]>;

package/dist/skills.js

@@ -0,0 +1,58 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+import { getProjectPaths, getProjectRelativePaths } from "./layout.js";
+const SKILL_FILE = "SKILL.md";
+/** Reads every `skills/<name>/SKILL.md` file. A file that cannot be read throws. */
+export async function readSkills(root) {
+    const directory = getProjectPaths(root).directories.skills;
+    const relative = getProjectRelativePaths().directories.skills;
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+    const skills = [];
+    const issues = [];
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+            const name = entry.name.slice(0, -".md".length);
+            issues.push({
+                path: `${relative}/${entry.name}`,
+                message: `Skills are folders. Move ${relative}/${entry.name} to ${relative}/${name}/${SKILL_FILE}.`,
+                severity: "error",
+            });
+            continue;
+        }
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const folder = `${relative}/${entry.name}`;
+        const source = `${folder}/${SKILL_FILE}`;
+        if (!(await readdir(join(directory, entry.name))).includes(SKILL_FILE)) {
+            issues.push({
+                path: folder,
+                message: `Skill folder ${folder} needs a ${SKILL_FILE} file.`,
+                severity: "error",
+            });
+            continue;
+        }
+        const text = await readFile(join(directory, entry.name, SKILL_FILE), "utf8");
+        const { data, body } = parseFrontmatter(text);
+        const description = data.description?.trim();
+        if (!description) {
+            issues.push({
+                path: source,
+                message: `Skill ${source} needs a description. Add "description: <when to use this skill>" in a frontmatter block at the top of the file.`,
+                severity: "error",
+            });
+            continue;
+        }
+        skills.push({ name: entry.name, description, source, body });
+    }
+    return { skills, issues };
+}
+/** Skill problems for `plico validate`. Unreadable files are left for the run to report. */
+export async function validateSkills(root) {
+    try {
+        return (await readSkills(root)).issues;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/tool-name-validation.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationIssue } from "./types.js";
+export declare const ARTIFACT_TOOL_NAMES: readonly ["list_files", "read_file", "write_file", "edit_file"];
+/** The built-in tool the agent calls to read a skill's full text. */
+export declare const SKILL_TOOL_NAME = "load_skill";
+export declare function validateToolNames(root: string): Promise<ValidationIssue[]>;

package/dist/tool-name-validation.js

@@ -0,0 +1,219 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse, } from "acorn";
+import { transform } from "esbuild";
+import { SPECIFIER } from "./authoring.js";
+import { getProjectPaths, getProjectRelativePaths } from "./layout.js";
+export const ARTIFACT_TOOL_NAMES = ["list_files", "read_file", "write_file", "edit_file"];
+/** The built-in tool the agent calls to read a skill's full text. */
+export const SKILL_TOOL_NAME = "load_skill";
+export async function validateToolNames(root) {
+    const paths = getProjectPaths(root);
+    const relativePaths = getProjectRelativePaths();
+    let entries;
+    try {
+        entries = (await readdir(paths.directories.tools, { withFileTypes: true }))
+            .filter((entry) => !entry.isDirectory() && entry.name.endsWith(".tool.ts"))
+            .map((entry) => entry.name)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (isMissingDirectory(error))
+            return [];
+        throw error;
+    }
+    const names = new Map();
+    const issues = [];
+    for (const entry of entries) {
+        const source = `${relativePaths.directories.tools}/${entry}`;
+        const text = await readFile(join(paths.directories.tools, entry), "utf8");
+        const name = await readToolName(text, source);
+        if (name === undefined)
+            continue;
+        if (ARTIFACT_TOOL_NAMES.includes(name)) {
+            issues.push({
+                path: source,
+                message: `Tool name "${name}" is reserved by Plico's artifact tools`,
+                severity: "error",
+            });
+            continue;
+        }
+        if (name === SKILL_TOOL_NAME) {
+            issues.push({
+                path: source,
+                message: `Tool name "${name}" is reserved by Plico's skill loader`,
+                severity: "error",
+            });
+            continue;
+        }
+        const first = names.get(name);
+        if (first) {
+            issues.push({
+                path: source,
+                message: `Duplicate tool name "${name}" declared in ${first} and ${source}`,
+                severity: "error",
+            });
+        }
+        else {
+            names.set(name, source);
+        }
+    }
+    return issues;
+}
+/**
+ * Types are stripped first, so `as`, `satisfies` and annotations are gone before the tree is read.
+ * A file that does not parse has no readable name; the project still validates and the load step
+ * reports the syntax error.
+ */
+async function parseToolFile(text, fileName) {
+    try {
+        const { code } = await transform(text, {
+            loader: "ts",
+            format: "esm",
+            target: "esnext",
+            sourcefile: fileName,
+        });
+        return parse(code, { ecmaVersion: "latest", sourceType: "module" });
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readToolName(text, fileName) {
+    const program = await parseToolFile(text, fileName);
+    if (!program)
+        return undefined;
+    const scope = { declarations: new Map(), defineTools: new Set(), namespaces: new Set() };
+    let defaultExpression;
+    for (const statement of program.body) {
+        if (statement.type === "VariableDeclaration") {
+            for (const declaration of statement.declarations) {
+                if (declaration.id.type === "Identifier" && declaration.init) {
+                    scope.declarations.set(declaration.id.name, declaration.init);
+                }
+            }
+        }
+        else if (statement.type === "ExportDefaultDeclaration") {
+            const { declaration } = statement;
+            if (declaration.type !== "FunctionDeclaration" && declaration.type !== "ClassDeclaration") {
+                defaultExpression = declaration;
+            }
+        }
+        else if (statement.type === "ExportNamedDeclaration") {
+            // esbuild may write `export default tool` as `export { tool as default }`.
+            for (const specifier of statement.specifiers) {
+                if (moduleName(specifier.exported) === "default")
+                    defaultExpression = specifier.local;
+            }
+        }
+        else if (statement.type === "ImportDeclaration") {
+            readAuthoringImport(statement, scope);
+        }
+    }
+    const object = resolveObject(defaultExpression, scope);
+    if (!object)
+        return undefined;
+    const result = resolveObjectName(object, scope);
+    return result.kind === "known" ? result.name : undefined;
+}
+function moduleName(node) {
+    if (node.type === "Identifier")
+        return node.name;
+    return typeof node.value === "string" ? node.value : undefined;
+}
+function readAuthoringImport(statement, scope) {
+    if (statement.source.value !== SPECIFIER)
+        return;
+    for (const specifier of statement.specifiers) {
+        if (specifier.type === "ImportNamespaceSpecifier") {
+            scope.namespaces.add(specifier.local.name);
+        }
+        else if (specifier.type === "ImportSpecifier" &&
+            moduleName(specifier.imported) === "defineTool") {
+            scope.defineTools.add(specifier.local.name);
+        }
+    }
+}
+function resolveObjectName(object, scope) {
+    for (const property of [...object.properties].reverse()) {
+        if (property.type === "Property" && property.kind === "init" && !property.method) {
+            const propertyName = property.computed ? undefined : moduleName(property.key);
+            if (propertyName === "name") {
+                const name = resolveString(property.value, scope);
+                return name === undefined ? { kind: "unknown" } : { kind: "known", name };
+            }
+        }
+        if (property.type === "SpreadElement") {
+            const spreadObject = resolveObject(property.argument, scope);
+            if (!spreadObject)
+                return { kind: "unknown" };
+            const spreadName = resolveObjectName(spreadObject, scope);
+            if (spreadName.kind !== "absent")
+                return spreadName;
+        }
+    }
+    return { kind: "absent" };
+}
+function resolveString(expression, scope) {
+    let current = unwrap(expression, scope);
+    const visited = new Set();
+    while (current.type === "Identifier") {
+        if (visited.has(current.name))
+            return undefined;
+        visited.add(current.name);
+        const declaration = scope.declarations.get(current.name);
+        if (!declaration)
+            return undefined;
+        current = unwrap(declaration, scope);
+    }
+    return current.type === "Literal" && typeof current.value === "string"
+        ? current.value
+        : undefined;
+}
+function resolveObject(expression, scope) {
+    let current = expression;
+    const visited = new Set();
+    while (current) {
+        current = unwrap(current, scope);
+        if (current.type === "ObjectExpression")
+            return current;
+        if (current.type !== "Identifier")
+            return undefined;
+        if (visited.has(current.name))
+            return undefined;
+        visited.add(current.name);
+        current = scope.declarations.get(current.name);
+    }
+    return undefined;
+}
+function unwrap(expression, scope) {
+    let current = expression;
+    while (isDefineToolCall(current, scope))
+        current = current.arguments[0];
+    return current;
+}
+/**
+ * `defineTool(tool)` returns `tool` unchanged, so its name is the argument's name. Only the
+ * `defineTool` imported from "@plico-ai/sdk" counts, under any local name or through a namespace import.
+ */
+function isDefineToolCall(expression, scope) {
+    if (expression.type !== "CallExpression" || expression.arguments.length !== 1)
+        return false;
+    if (expression.arguments[0]?.type === "SpreadElement")
+        return false;
+    const { callee } = expression;
+    if (callee.type === "Identifier")
+        return scope.defineTools.has(callee.name);
+    return (callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.object.type === "Identifier" &&
+        scope.namespaces.has(callee.object.name) &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === "defineTool");
+}
+function isMissingDirectory(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export type { LoadedProject, ProjectConfig, ValidationIssue, ValidationResult, ValidationSeverity, } from "@plico-ai/contracts";
+export type ProjectDirectoryRole = keyof ProjectLayoutDirectories;
+export interface ProjectLayoutDirectories {
+    skills: "skills";
+    tools: "tools";
+    evals: "evals";
+    artifacts: "artifacts";
+    memory: "memory";
+}
+export interface ProjectLayout {
+    configFile: "plico.config.ts";
+    agentFile: "agent.md";
+    directories: ProjectLayoutDirectories;
+}
+export interface ProjectRelativePaths {
+    configFile: string;
+    agentFile: string;
+    directories: Record<ProjectDirectoryRole, string>;
+}
+export interface ProjectPaths {
+    configFile: string;
+    agentFile: string;
+    directories: Record<ProjectDirectoryRole, string>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from "./types.js";
+export declare function validateProject(root: string): Promise<ValidationResult>;

package/dist/validation.js

@@ -0,0 +1,123 @@
+import { readFile, stat } from "node:fs/promises";
+import { parseAgentFile, unknownAgentKeyWarnings } from "./agent-file.js";
+import { loadProject } from "./config.js";
+import { missingFileMessage, missingFileMessageFor, ProjectConfigError } from "./errors.js";
+import { getProjectPaths, getProjectRelativePaths, REQUIRED_PROJECT_DIRECTORIES, } from "./layout.js";
+import { validateModelProvider } from "./model-provider.js";
+import { validateSkills } from "./skills.js";
+import { validateToolNames } from "./tool-name-validation.js";
+export async function validateProject(root) {
+    const errors = [];
+    const warnings = [];
+    const relativePaths = getProjectRelativePaths();
+    const projectPaths = getProjectPaths(root);
+    let project;
+    try {
+        project = await loadProject(root);
+    }
+    catch (error) {
+        if (error instanceof ProjectConfigError) {
+            errors.push(...error.issues);
+        }
+        else {
+            errors.push({
+                path: relativePaths.configFile,
+                message: missingFileMessage(error),
+                severity: "error",
+            });
+        }
+        return {
+            ok: false,
+            issues: [...errors, ...warnings],
+            errors,
+            warnings,
+        };
+    }
+    let agentText;
+    try {
+        agentText = await readFile(projectPaths.agentFile, "utf8");
+    }
+    catch (error) {
+        errors.push({
+            path: relativePaths.agentFile,
+            message: missingFileMessageFor(relativePaths.agentFile, error),
+            severity: "error",
+        });
+    }
+    if (typeof agentText === "string") {
+        const agent = parseAgentFile(agentText);
+        warnings.push(...unknownAgentKeyWarnings(relativePaths.agentFile, agent.data));
+        agentText = agent.body;
+        if (agentText.trim().length === 0) {
+            errors.push({
+                path: relativePaths.agentFile,
+                message: `${relativePaths.agentFile} must not be empty`,
+                severity: "error",
+            });
+        }
+        else {
+            const warning = detectWeakAgentContent(agentText);
+            if (warning) {
+                warnings.push({
+                    path: relativePaths.agentFile,
+                    message: warning,
+                    severity: "warning",
+                });
+            }
+        }
+    }
+    for (const directoryRole of REQUIRED_PROJECT_DIRECTORIES) {
+        const directory = relativePaths.directories[directoryRole];
+        const directoryPath = projectPaths.directories[directoryRole];
+        try {
+            const directoryStat = await stat(directoryPath);
+            if (!directoryStat.isDirectory()) {
+                errors.push({
+                    path: directory,
+                    message: `Expected ${directory} to be a directory`,
+                    severity: "error",
+                });
+            }
+        }
+        catch {
+            errors.push({
+                path: directory,
+                message: `Missing required directory: ${directory}`,
+                severity: "error",
+            });
+        }
+    }
+    if (project.config.schemaVersion !== 1) {
+        errors.push({
+            path: relativePaths.configFile,
+            message: "Unsupported schemaVersion. Expected 1.",
+            severity: "error",
+        });
+    }
+    if (!project.config.name.trim()) {
+        errors.push({
+            path: relativePaths.configFile,
+            message: "Project name is required.",
+            severity: "error",
+        });
+    }
+    errors.push(...(await validateToolNames(root)));
+    errors.push(...(await validateSkills(root)));
+    errors.push(...(await validateModelProvider(root, project.config.model, relativePaths.configFile)));
+    return {
+        ok: errors.length === 0,
+        issues: [...errors, ...warnings],
+        errors,
+        warnings,
+        project,
+    };
+}
+function detectWeakAgentContent(agentText) {
+    const normalized = agentText.trim().toLowerCase();
+    if (normalized.includes("follow the project instructions") ||
+        normalized === "# agent" ||
+        normalized.includes("placeholder agent instructions")) {
+        return "agent.md looks like placeholder content";
+    }
+    return undefined;
+}

package/package.json

@@ -1,21 +1,47 @@
 {
   "name": "@plico-ai/core",
-  "version": "0.0.0-reserved.0",
-  "description": "Project loading and validation for Plico. Not released yet.",
+  "version": "0.1.0",
+  "description": "Plico project model: load and validate agent projects from files",
   "license": "Apache-2.0",
   "homepage": "https://plico.sohab.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ITZSHOAIB/plico.git"
+    "url": "git+https://github.com/ITZSHOAIB/plico.git",
+    "directory": "packages/core"
   },
   "keywords": [
     "plico",
-    "agent"
-  ],
-  "files": [
-    "README.md"
+    "agent",
+    "validation"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "NOTICE",
+    "dist"
+  ],
+  "dependencies": {
+    "acorn": "^8.19.0",
+    "esbuild": "~0.28.2",
+    "@plico-ai/contracts": "0.1.0",
+    "@plico-ai/sdk": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "test": "vitest run"
   }
-}
+}