create-plico 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/cli.js +1 -0
- package/dist/files.d.ts +2 -0
- package/dist/files.js +82 -5
- package/dist/providers.js +1 -1
- package/dist/scaffold.js +3 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -11,3 +11,5 @@ Scaffold generator for the internal-ops starter project. Part of [Plico](https:/
|
|
|
11
11
|
`create-plico my-plico --provider anthropic|openai|google|openai-compatible` configures a model and writes the matching `.env.example` and adapter dependency. The interactive flow asks for the provider; without `--provider`, a non-interactive run configures none. The scaffold also writes a `package.json` with `dev`, `validate` and `eval` scripts, `@plico-ai/cli` as a dev dependency, and a `.gitignore` for `.plico/` and `.env`.
|
|
12
12
|
|
|
13
13
|
The generated scaffold includes the required Plico project files and directories so it is immediately valid and can complete `plico run --dry` and pass `plico eval` (it ships `evals/smoke.script.json`) after `npm install`.
|
|
14
|
+
|
|
15
|
+
Docs: [plico.sohab.dev](https://plico.sohab.dev). For AI coding agents: [llms.txt](https://plico.sohab.dev/llms.txt).
|
package/dist/cli.js
CHANGED
|
@@ -71,6 +71,7 @@ export async function main(argv, prompts = defaultScaffoldPrompts) {
|
|
|
71
71
|
...(provider ? { provider } : {}),
|
|
72
72
|
});
|
|
73
73
|
console.log(`Created Plico scaffold in ${targetDir}`);
|
|
74
|
+
console.log("Next: cd in, npm install, npm run validate. Docs: https://plico.sohab.dev (for AI agents: /llms.txt)");
|
|
74
75
|
return 0;
|
|
75
76
|
}
|
|
76
77
|
catch (error) {
|
package/dist/files.d.ts
CHANGED
|
@@ -4,6 +4,8 @@ export declare function packageFile(version: string, provider?: ScaffoldProvider
|
|
|
4
4
|
export declare function envExampleFile(provider?: ScaffoldProvider): string;
|
|
5
5
|
export declare function gitignoreFile(): string;
|
|
6
6
|
export declare function agentFile(projectName: string): string;
|
|
7
|
+
export declare function projectAgentsFile(projectName: string): string;
|
|
8
|
+
export declare function projectClaudeFile(): string;
|
|
7
9
|
export declare function triageSkillFile(): string;
|
|
8
10
|
export declare function toolsReadmeFile(): string;
|
|
9
11
|
export declare function smokeEvalFile(): string;
|
package/dist/files.js
CHANGED
|
@@ -81,6 +81,82 @@ export function agentFile(projectName) {
|
|
|
81
81
|
"",
|
|
82
82
|
].join("\n");
|
|
83
83
|
}
|
|
84
|
+
export function projectAgentsFile(projectName) {
|
|
85
|
+
return `# ${projectName}: instructions for coding agents
|
|
86
|
+
|
|
87
|
+
This is a [Plico](https://plico.sohab.dev) project: the agent is the files in this folder. Plico docs as plain Markdown: https://plico.sohab.dev/llms.txt (everything in one file: https://plico.sohab.dev/llms-full.txt).
|
|
88
|
+
|
|
89
|
+
## Layout
|
|
90
|
+
|
|
91
|
+
- \`agent.md\` is the agent's instructions. Edit it to change behaviour.
|
|
92
|
+
- \`plico.config.ts\` is the project config (\`defineConfig\` from \`@plico-ai/sdk\`): name, optional \`model\`, optional \`approvals\`.
|
|
93
|
+
- \`skills/<name>/SKILL.md\` holds a skill. It needs a \`description\` in its frontmatter.
|
|
94
|
+
- \`tools/<name>.tool.ts\` holds one tool as a default export (below).
|
|
95
|
+
- \`evals/<name>.script.json\` holds one eval case (below).
|
|
96
|
+
- \`artifacts/\` and \`memory/\` are required folders. Leave them in place.
|
|
97
|
+
|
|
98
|
+
## Add a tool
|
|
99
|
+
|
|
100
|
+
\`\`\`ts
|
|
101
|
+
import { defineTool } from "@plico-ai/sdk";
|
|
102
|
+
|
|
103
|
+
export default defineTool({
|
|
104
|
+
name: "issue_refund", // unique, snake_case
|
|
105
|
+
description: "Refund an order.",
|
|
106
|
+
inputSchema: {
|
|
107
|
+
type: "object",
|
|
108
|
+
properties: { orderId: { type: "string" } },
|
|
109
|
+
required: ["orderId"],
|
|
110
|
+
additionalProperties: false,
|
|
111
|
+
},
|
|
112
|
+
capabilities: ["payments:write"], // required, recorded only
|
|
113
|
+
approval: { required: true, reason: "Moves money." }, // required; true makes the run wait for a person
|
|
114
|
+
handler: async ({ orderId }, ctx) => ({ orderId, status: "refunded" }),
|
|
115
|
+
});
|
|
116
|
+
\`\`\`
|
|
117
|
+
|
|
118
|
+
\`capabilities\` and \`approval\` are required. For a Zod \`inputSchema\`, add \`zod\` to this project first.
|
|
119
|
+
|
|
120
|
+
## Add an eval
|
|
121
|
+
|
|
122
|
+
A case is a script plus an optional \`expect\`. It uses no model and no API key:
|
|
123
|
+
|
|
124
|
+
\`\`\`json
|
|
125
|
+
{
|
|
126
|
+
"description": "A refund waits for approval, then is approved.",
|
|
127
|
+
"script": [
|
|
128
|
+
{ "type": "tool.call", "toolName": "issue_refund", "arguments": { "orderId": "A-1" },
|
|
129
|
+
"result": { "status": "refunded" } },
|
|
130
|
+
{ "type": "approval.decide", "approved": true },
|
|
131
|
+
{ "type": "assistant.output", "content": "Refunded." }
|
|
132
|
+
],
|
|
133
|
+
"expect": { "status": "completed", "outputContains": "Refunded" }
|
|
134
|
+
}
|
|
135
|
+
\`\`\`
|
|
136
|
+
|
|
137
|
+
Steps are \`assistant.output\` (\`content\`), \`tool.call\` (\`toolName\`, \`arguments\`, \`result\` is required because evals do not run handlers, or \`"live": true\` to run the handler), \`approval.decide\` (\`approved\`, right after a tool call that needs approval) and \`artifact.write\` (\`files\`). Leave out \`approval.decide\` and the run stops as \`waiting\`, so \`"expect": { "status": "waiting" }\` tests that a tool is held. \`approved: false\` ends the run as \`failed\`.
|
|
138
|
+
|
|
139
|
+
## Check your work
|
|
140
|
+
|
|
141
|
+
\`\`\`bash
|
|
142
|
+
npm run validate # plico validate: layout, config, tool and skill names
|
|
143
|
+
npm run eval # plico eval: every case in evals/; exit 1 on any failure or no cases
|
|
144
|
+
npx plico run --dry . # runs with a scripted model; add --script <file> for your own steps
|
|
145
|
+
\`\`\`
|
|
146
|
+
|
|
147
|
+
\`plico run --dry\` exits 0 on completion, 2 when a run is waiting for approval and 1 on failure. Run \`npx plico <command> --help\` for a command's flags.
|
|
148
|
+
|
|
149
|
+
## Rules
|
|
150
|
+
|
|
151
|
+
- Keep secrets in \`.env\`, never in \`agent.md\`, tools or config. Events record tool arguments and results.
|
|
152
|
+
- Do not edit \`.plico/\`: it holds saved runs.
|
|
153
|
+
- Do not ask for a model key to test. Use \`--dry\` and evals.
|
|
154
|
+
- With a model, \`plico serve --studio .\` opens Studio, a local UI to chat, read run events and approve tool calls.
|
|
155
|
+
`;
|
|
156
|
+
}
|
|
157
|
+
export function projectClaudeFile() {
|
|
158
|
+
return "@AGENTS.md\n";
|
|
159
|
+
}
|
|
84
160
|
export function triageSkillFile() {
|
|
85
161
|
return [
|
|
86
162
|
"---",
|
|
@@ -100,13 +176,14 @@ export function toolsReadmeFile() {
|
|
|
100
176
|
"",
|
|
101
177
|
"Add TypeScript tool modules here when the project needs executable helpers.",
|
|
102
178
|
"",
|
|
103
|
-
"
|
|
179
|
+
"Each tool is one `<name>.tool.ts` file with a default export from `defineTool`.",
|
|
104
180
|
"",
|
|
105
|
-
"A tool handler receives `(input,
|
|
106
|
-
"the tool call that was in flight, so pass
|
|
107
|
-
"stable for a call, and `signal` aborts
|
|
181
|
+
"A tool handler receives `(input, ctx)`. `ctx` has `signal`, `idempotencyKey`, `artifacts` and",
|
|
182
|
+
"`context`. A run that is interrupted can repeat the tool call that was in flight, so pass",
|
|
183
|
+
"`idempotencyKey` to any API that takes one. The key is stable for a call, and `signal` aborts",
|
|
184
|
+
"when the run is cancelled.",
|
|
108
185
|
"",
|
|
109
|
-
"Set `inputSchema` to a JSON Schema object or a Zod
|
|
186
|
+
"Set `inputSchema` to a JSON Schema object or a Zod 4 schema. Plico validates each call and",
|
|
110
187
|
"sends JSON Schema to the model. Parsed Zod values, including defaults, reach the handler. Add",
|
|
111
188
|
"`zod` to this project's dependencies before importing it in a tool.",
|
|
112
189
|
"",
|
package/dist/providers.js
CHANGED
package/dist/scaffold.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { mkdir, readdir, writeFile } from "node:fs/promises";
|
|
2
2
|
import { join } from "node:path";
|
|
3
3
|
import { getProjectPaths, REQUIRED_PROJECT_DIRECTORIES } from "@plico-ai/core";
|
|
4
|
-
import { agentFile, artifactsReadmeFile, configFile, envExampleFile, gitignoreFile, memoryReadmeFile, packageFile, projectReadmeFile, smokeEvalFile, toolsReadmeFile, triageSkillFile, } from "./files.js";
|
|
4
|
+
import { agentFile, artifactsReadmeFile, configFile, envExampleFile, gitignoreFile, memoryReadmeFile, packageFile, projectAgentsFile, projectClaudeFile, projectReadmeFile, smokeEvalFile, toolsReadmeFile, triageSkillFile, } from "./files.js";
|
|
5
5
|
import { readVersion } from "./usage.js";
|
|
6
6
|
export async function createInternalOpsScaffold(options) {
|
|
7
7
|
const root = options.targetDir;
|
|
@@ -22,6 +22,8 @@ export async function createInternalOpsScaffold(options) {
|
|
|
22
22
|
await writeFile(join(projectPaths.directories.memory, "README.md"), memoryReadmeFile(), "utf8");
|
|
23
23
|
await writeFile(join(projectPaths.directories.artifacts, "README.md"), artifactsReadmeFile(), "utf8");
|
|
24
24
|
await writeFile(join(root, "README.md"), projectReadmeFile(projectName), "utf8");
|
|
25
|
+
await writeFile(join(root, "AGENTS.md"), projectAgentsFile(projectName), "utf8");
|
|
26
|
+
await writeFile(join(root, "CLAUDE.md"), projectClaudeFile(), "utf8");
|
|
25
27
|
}
|
|
26
28
|
async function ensureEmptyTarget(root) {
|
|
27
29
|
let entries;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-plico",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Scaffold a Plico agent project",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://plico.sohab.dev",
|
|
@@ -40,10 +40,10 @@
|
|
|
40
40
|
],
|
|
41
41
|
"dependencies": {
|
|
42
42
|
"@clack/prompts": "^1.6.0",
|
|
43
|
-
"@plico-ai/core": "0.1.
|
|
43
|
+
"@plico-ai/core": "0.1.2"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
|
-
"@plico-ai/runtime": "0.1.
|
|
46
|
+
"@plico-ai/runtime": "0.1.2"
|
|
47
47
|
},
|
|
48
48
|
"engines": {
|
|
49
49
|
"node": ">=22.18.0"
|