create-plico 0.1.0 → 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 CHANGED
@@ -1,13 +1,15 @@
1
1
  # create-plico
2
2
 
3
- Scaffold generator for the internal-ops starter project.
3
+ Scaffold generator for the internal-ops starter project. Part of [Plico](https://github.com/ITZSHOAIB/plico).
4
4
 
5
5
  ## Usage
6
6
 
7
- - `pnpm --filter create-plico exec create-plico my-plico`
8
- - `pnpm --filter create-plico exec create-plico`
7
+ - `npm create plico@latest my-plico`
8
+ - `npx create-plico` asks for the folder name
9
9
  - `create-plico --help` prints usage and `create-plico --version` prints the version. Any other argument that starts with `-` is rejected, so a typo never becomes a directory name.
10
10
 
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
- The generated scaffold includes the required Plico project files and directories so it is immediately valid and can complete `plico run --dry` without extra setup.
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
@@ -1,4 +1,6 @@
1
1
  import { PROVIDER_SETUP } from "./providers.js";
2
+ /** Matches the adapter ranges `@plico-ai/runtime` accepts as optional peer dependencies. */
3
+ const ADAPTER_RANGE = "^4.0.0";
2
4
  export function configFile(projectName, provider) {
3
5
  const setup = provider ? PROVIDER_SETUP[provider] : undefined;
4
6
  return [
@@ -36,7 +38,10 @@ export function packageFile(version, provider) {
36
38
  validate: "plico validate .",
37
39
  eval: "plico eval .",
38
40
  },
39
- dependencies: { "@plico-ai/sdk": `^${version}`, ...(adapter ? { [adapter]: "latest" } : {}) },
41
+ dependencies: {
42
+ "@plico-ai/sdk": `^${version}`,
43
+ ...(adapter ? { [adapter]: ADAPTER_RANGE } : {}),
44
+ },
40
45
  devDependencies: { "@plico-ai/cli": `^${version}` },
41
46
  }, null, 2)}\n`;
42
47
  }
@@ -76,6 +81,82 @@ export function agentFile(projectName) {
76
81
  "",
77
82
  ].join("\n");
78
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
+ }
79
160
  export function triageSkillFile() {
80
161
  return [
81
162
  "---",
@@ -95,13 +176,14 @@ export function toolsReadmeFile() {
95
176
  "",
96
177
  "Add TypeScript tool modules here when the project needs executable helpers.",
97
178
  "",
98
- "Keep the public contract file-first until tools are explicitly required.",
179
+ "Each tool is one `<name>.tool.ts` file with a default export from `defineTool`.",
99
180
  "",
100
- "A tool handler receives `(input, { signal, idempotencyKey })`. A run that is interrupted can repeat",
101
- "the tool call that was in flight, so pass `idempotencyKey` to any API that takes one. The key is",
102
- "stable for a call, and `signal` aborts when the run is cancelled.",
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.",
103
185
  "",
104
- "Set `inputSchema` to a JSON Schema object or a Zod 3 or 4 schema. Plico validates each call and",
186
+ "Set `inputSchema` to a JSON Schema object or a Zod 4 schema. Plico validates each call and",
105
187
  "sends JSON Schema to the model. Parsed Zod values, including defaults, reach the handler. Add",
106
188
  "`zod` to this project's dependencies before importing it in a tool.",
107
189
  "",
@@ -110,12 +192,12 @@ export function toolsReadmeFile() {
110
192
  ].join("\n");
111
193
  }
112
194
  export function smokeEvalFile() {
113
- return [
114
- "# Smoke Eval",
115
- "",
116
- "Verify the scaffold boots, validates, and presents a clear starting point.",
117
- "",
118
- ].join("\n");
195
+ return `${JSON.stringify({
196
+ description: "Scripted smoke case. It needs no model and no key, so it passes in CI. Replace the steps with calls to your own tools.",
197
+ script: [{ type: "assistant.output", content: "The project boots." }],
198
+ expect: { status: "completed", outputContains: "boots" },
199
+ }, null, 2)}
200
+ `;
119
201
  }
120
202
  export function memoryReadmeFile() {
121
203
  return [
package/dist/providers.js CHANGED
@@ -14,7 +14,7 @@ export const PROVIDER_SETUP = {
14
14
  },
15
15
  google: {
16
16
  label: "Google",
17
- model: "gemini-2.5-flash",
17
+ model: "gemini-3.5-flash",
18
18
  apiKeyEnv: "GOOGLE_GENERATIVE_AI_API_KEY",
19
19
  adapter: "@ai-sdk/google",
20
20
  },
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;
@@ -18,10 +18,12 @@ export async function createInternalOpsScaffold(options) {
18
18
  await mkdir(join(projectPaths.directories.skills, "triage"), { recursive: true });
19
19
  await writeFile(join(projectPaths.directories.skills, "triage", "SKILL.md"), triageSkillFile(), "utf8");
20
20
  await writeFile(join(projectPaths.directories.tools, "readme.md"), toolsReadmeFile(), "utf8");
21
- await writeFile(join(projectPaths.directories.evals, "smoke.md"), smokeEvalFile(), "utf8");
21
+ await writeFile(join(projectPaths.directories.evals, "smoke.script.json"), smokeEvalFile(), "utf8");
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.0",
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.0"
43
+ "@plico-ai/core": "0.1.2"
44
44
  },
45
45
  "devDependencies": {
46
- "@plico-ai/runtime": "0.1.0"
46
+ "@plico-ai/runtime": "0.1.2"
47
47
  },
48
48
  "engines": {
49
49
  "node": ">=22.18.0"