@symplek/cli 0.0.0-stage → 0.2.0-beta.0

package/dist/templates/project/full/tests/example.test.ts.template

@@ -0,0 +1,49 @@
+import { AgentUnit, createContext, isTracked } from "@symplek/core";
+import { describe, expect, it } from "vitest";
+import { resilient, withProvenance } from "../src/tools/index.js";
+
+/**
+ * Smoke tests for {{name}}'s tool helpers.
+ *
+ * These run without an API key — they exercise the operator algebra only,
+ * not real LLM calls. Add integration tests with `vi.mock("@symplek/core/server")`
+ * once you have agents that hit a provider.
+ */
+
+describe("{{name}} resilience helpers", () => {
+  it("returns the underlying value on success", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.of("ok");
+    const result = await resilient(unit, { maxAttempts: 1 }).run(ctx);
+    expect(result.value).toBe("ok");
+  });
+
+  it("falls back to the supplied default when the unit fails", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.fail<string>(new Error("simulated failure"));
+    const result = await resilient(unit, { fallback: "safe-default" }).run(
+      ctx,
+    );
+    expect(result.value).toBe("safe-default");
+  });
+});
+
+describe("{{name}} provenance helpers", () => {
+  it("wraps the value in a TrackedResult envelope", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.of("payload");
+    const result = await withProvenance(unit, {
+      source: "agent",
+      confidence: 0.95,
+      verifiedBy: "unit-test",
+    }).run(ctx);
+
+    // The result of .tracked() is itself a TrackedResult<TrackedResult<T>>
+    // — the outer envelope is added by .run() in zero-trust mode, the inner
+    // one is what `withProvenance` applied. We confirm both layers exist.
+    expect(result.value).toBeDefined();
+    expect(isTracked(result.value)).toBe(true);
+    expect(result.value.confidence).toBeCloseTo(0.95);
+    expect(result.value.source).toBe("agent");
+  });
+});

package/dist/templates/project/full/tsconfig.json.template

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": {{strict}},
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "agents/**/*"]
+}

package/dist/templates/project/minimal/.gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log

package/dist/templates/project/minimal/agents/example.yaml.template

@@ -0,0 +1,16 @@
+# Symplek agent definition — declarative form.
+#
+# Compile to TypeScript with:
+#   pnpm exec symplek generate
+#
+# This produces `agents/{{agentName}}.ts` that you can import and call
+# from your application code. YAML lets non-engineers tune prompts without
+# touching the source.
+
+name: {{agentName}}
+description: Summarises text in one clear sentence.
+model: "{{model}}"
+
+systemPrompt: |
+  You summarise the user's input in exactly one clear sentence.
+  Never embellish. Never editorialise. Faithful to the input only.

package/dist/templates/project/minimal/package.json.template

@@ -0,0 +1,27 @@
+{
+  "name": "{{name}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@symplek/core": "^1.0.0-beta.1",
+    "zod": "^3.25.76",
+    "openai": "^4.104.0"
+  },
+  "devDependencies": {
+    "@symplek/cli": "^{{cliVersion}}",
+    "@types/node": "^22.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=20.19"
+  }
+}

package/dist/templates/project/minimal/src/index.ts.template

@@ -0,0 +1,43 @@
+import "./symplek.config.js";
+import { createContext } from "@symplek/core";
+import { Symplek } from "@symplek/core/server";
+
+/**
+ * {{name}} — a minimal Symplek agent.
+ *
+ * Demonstrates the core pattern:
+ *   1. `Symplek(prompt)` builds an AI call.
+ *   2. `.coordinate()` lifts it into the AgentUnit<T> algebra.
+ *   3. Layer safety operators on top (retry, timeout, fallback, …).
+ *   4. `.run(ctx)` executes and returns a TrackedResult.
+ *
+ * Scripts:
+ *   pnpm dev    — watch mode (re-runs on file change)
+ *   pnpm start  — one-shot
+ */
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error("[{{name}}] OPENAI_API_KEY is not set.");
+  console.error("Set it and re-run:  export OPENAI_API_KEY=sk-...");
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const ctx = createContext();
+  const input = "The quick brown fox jumps over the lazy dog.";
+
+  const result = await Symplek(`Summarise in one sentence: ${input}`)
+    .coordinate()
+    .retry(2)
+    .timeout(15_000)
+    .run(ctx);
+
+  console.log("Input:      ", input);
+  console.log("Summary:    ", result.value);
+  console.log("Confidence: ", result.confidence);
+}
+
+main().catch((err: unknown) => {
+  console.error("[{{name}}] agent failed:", err);
+  process.exit(1);
+});

package/dist/templates/project/minimal/src/symplek.config.ts.template

@@ -0,0 +1,20 @@
+/**
+ * Symplek runtime configuration for {{name}}.
+ *
+ * Imported for side effect by `src/index.ts` before any agent runs.
+ * Set OPENAI_API_KEY in your environment:
+ *
+ *   export OPENAI_API_KEY=sk-...
+ *
+ * To swap providers, change `provider` and the matching env var. Symplek
+ * supports `openai`, `anthropic`, and `google` out of the box — install
+ * the corresponding SDK (`pnpm add @anthropic-ai/sdk` etc.) and update
+ * this file.
+ */
+import { Symplek } from "@symplek/core/server";
+
+Symplek.configure({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY ?? "",
+  model: "{{model}}",
+});

package/dist/templates/project/minimal/tsconfig.json.template

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": {{strict}},
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "agents/**/*"]
+}

package/dist/templates/project/standard/.gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log

package/dist/templates/project/standard/README.md.template

@@ -0,0 +1,77 @@
+# {{name}}
+
+{{description}}
+
+Built with [Symplek](https://github.com/symplek/symplek) — composable AI agents for TypeScript.
+
+---
+
+## Setup
+
+```bash
+pnpm install                      # or npm install / yarn / bun
+export OPENAI_API_KEY=sk-...      # provider env var from src/symplek.config.ts
+pnpm dev                          # watch mode
+pnpm start                        # one-shot
+```
+
+To switch providers, edit `src/symplek.config.ts` and install the matching SDK
+(`pnpm add @anthropic-ai/sdk` for Anthropic, etc.). Symplek auto-detects which
+provider is configured at runtime.
+
+---
+
+## Project layout
+
+```
+{{name}}/
+├── src/
+│   ├── index.ts          # entry — runs the example agent
+│   ├── symplek.config.ts    # Symplek runtime configuration (provider, API key)
+│   └── tools/index.ts    # composable helpers (resilient, withProvenance)
+├── agents/
+│   └── {{agentName}}.yaml   # declarative agent — `symplek generate` compiles it
+└── tests/
+    └── example.test.ts   # vitest unit tests
+```
+
+---
+
+## What's where
+
+- **`src/symplek.config.ts`** — registers your AI provider. Edit here to swap
+  OpenAI for Anthropic, change the default model, set a base URL, etc.
+- **`src/tools/index.ts`** — your project's local helpers. Compose `AgentUnit`
+  operators into project-specific patterns here so the rest of your code stays
+  readable.
+- **`agents/`** — YAML agent definitions. Run `symplek generate` to compile them
+  into typed TypeScript wrappers next to them, as `agents/<name>.ts`.
+
+---
+
+## Scripts
+
+| Command | What it does |
+|---|---|
+| `pnpm dev` | Run the entry in watch mode via `tsx` |
+| `pnpm start` | Run once |
+| `pnpm build` | Compile TypeScript to `dist/` |
+| `pnpm typecheck` | TypeScript check without emit |
+| `pnpm test` | Run vitest once |
+| `pnpm test:watch` | Run vitest in watch mode |
+
+---
+
+## Next steps
+
+- Replace the example in `src/index.ts` with your real agent.
+- Edit `agents/{{agentName}}.yaml`, then run `symplek generate` to add typed wrappers.
+- Add more agents in `agents/`; the CLI handles wiring.
+- See [github.com/symplek/symplek](https://github.com/symplek/symplek) for the operator
+  reference (consensus, debate, dialectic, rehearse, replay, supervised, etc.).
+
+---
+
+## License
+
+ISC

package/dist/templates/project/standard/agents/example.yaml.template

@@ -0,0 +1,16 @@
+# Symplek agent definition — declarative form.
+#
+# Compile to TypeScript with:
+#   pnpm exec symplek generate
+#
+# This produces `agents/{{agentName}}.ts` that you can import and call
+# from your application code. YAML lets non-engineers tune prompts without
+# touching the source.
+
+name: {{agentName}}
+description: Summarises text in one clear sentence.
+model: "{{model}}"
+
+systemPrompt: |
+  You summarise the user's input in exactly one clear sentence.
+  Never embellish. Never editorialise. Faithful to the input only.

package/dist/templates/project/standard/package.json.template

@@ -0,0 +1,30 @@
+{
+  "name": "{{name}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@symplek/core": "^1.0.0-beta.1",
+    "zod": "^3.25.76",
+    "openai": "^4.104.0"
+  },
+  "devDependencies": {
+    "@symplek/cli": "^{{cliVersion}}",
+    "@types/node": "^22.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.19"
+  }
+}

package/dist/templates/project/standard/src/index.ts.template

@@ -0,0 +1,43 @@
+import "./symplek.config.js";
+import { createContext } from "@symplek/core";
+import { Symplek } from "@symplek/core/server";
+
+/**
+ * {{name}} — a minimal Symplek agent.
+ *
+ * Demonstrates the core pattern:
+ *   1. `Symplek(prompt)` builds an AI call.
+ *   2. `.coordinate()` lifts it into the AgentUnit<T> algebra.
+ *   3. Layer safety operators on top (retry, timeout, fallback, …).
+ *   4. `.run(ctx)` executes and returns a TrackedResult.
+ *
+ * Scripts:
+ *   pnpm dev    — watch mode (re-runs on file change)
+ *   pnpm start  — one-shot
+ */
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error("[{{name}}] OPENAI_API_KEY is not set.");
+  console.error("Set it and re-run:  export OPENAI_API_KEY=sk-...");
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const ctx = createContext();
+  const input = "The quick brown fox jumps over the lazy dog.";
+
+  const result = await Symplek(`Summarise in one sentence: ${input}`)
+    .coordinate()
+    .retry(2)
+    .timeout(15_000)
+    .run(ctx);
+
+  console.log("Input:      ", input);
+  console.log("Summary:    ", result.value);
+  console.log("Confidence: ", result.confidence);
+}
+
+main().catch((err: unknown) => {
+  console.error("[{{name}}] agent failed:", err);
+  process.exit(1);
+});

package/dist/templates/project/standard/src/symplek.config.ts.template

@@ -0,0 +1,20 @@
+/**
+ * Symplek runtime configuration for {{name}}.
+ *
+ * Imported for side effect by `src/index.ts` before any agent runs.
+ * Set OPENAI_API_KEY in your environment:
+ *
+ *   export OPENAI_API_KEY=sk-...
+ *
+ * To swap providers, change `provider` and the matching env var. Symplek
+ * supports `openai`, `anthropic`, and `google` out of the box — install
+ * the corresponding SDK (`pnpm add @anthropic-ai/sdk` etc.) and update
+ * this file.
+ */
+import { Symplek } from "@symplek/core/server";
+
+Symplek.configure({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY ?? "",
+  model: "{{model}}",
+});

package/dist/templates/project/standard/src/tools/index.ts.template

@@ -0,0 +1,73 @@
+/**
+ * Project-local helpers for {{name}}.
+ *
+ * Compose Symplek operators into patterns specific to your project here so
+ * your business code stays declarative. Each helper is one operator chain.
+ */
+import {
+  type AgentUnit,
+  isTracked,
+  type ResultSource,
+  type TrackedResult,
+} from "@symplek/core";
+
+export interface ProvenanceOptions {
+  /** Source category — one of Symplek's `ResultSource` literals. */
+  source: ResultSource;
+  /** Caller's confidence in this value, in [0, 1]. */
+  confidence: number;
+  /** Optional identifier of the verifier (audit trail). */
+  verifiedBy?: string;
+}
+
+/**
+ * Wrap an `AgentUnit<T>` so its output carries provenance metadata.
+ *
+ * Downstream callers can introspect `result.value`, `result.source`,
+ * `result.confidence` — Symplek's TrackedResult shape — without any extra
+ * plumbing.
+ */
+export function withProvenance<T>(
+  unit: AgentUnit<T>,
+  opts: ProvenanceOptions,
+): AgentUnit<TrackedResult<T>> {
+  return unit.tracked({
+    source: opts.source,
+    confidence: opts.confidence,
+    verifiedBy: opts.verifiedBy,
+  });
+}
+
+export interface ResilienceOptions<T> {
+  /** Max attempts including the first. Default 3. */
+  maxAttempts?: number;
+  /** Hard timeout in milliseconds. Default 15s. */
+  timeoutMs?: number;
+  /** Static fallback value if all attempts fail. */
+  fallback?: T;
+}
+
+/**
+ * Apply the standard resilience triad: retry on transient failure, hard
+ * timeout, fallback to a known-safe value if all else fails.
+ *
+ * @example
+ *   const safe = resilient(
+ *     Symplek(prompt).coordinate(),
+ *     { maxAttempts: 3, timeoutMs: 10_000, fallback: "" },
+ *   );
+ */
+export function resilient<T>(
+  unit: AgentUnit<T>,
+  options: ResilienceOptions<T> = {},
+): AgentUnit<T> {
+  const { maxAttempts = 3, timeoutMs = 15_000, fallback } = options;
+  let chain = unit.retry(maxAttempts).timeout(timeoutMs);
+  if (fallback !== undefined) {
+    chain = chain.orElse(fallback);
+  }
+  return chain;
+}
+
+/** Re-export Symplek's tracked-result type guard for convenience. */
+export { isTracked };

package/dist/templates/project/standard/tests/example.test.ts.template

@@ -0,0 +1,49 @@
+import { AgentUnit, createContext, isTracked } from "@symplek/core";
+import { describe, expect, it } from "vitest";
+import { resilient, withProvenance } from "../src/tools/index.js";
+
+/**
+ * Smoke tests for {{name}}'s tool helpers.
+ *
+ * These run without an API key — they exercise the operator algebra only,
+ * not real LLM calls. Add integration tests with `vi.mock("@symplek/core/server")`
+ * once you have agents that hit a provider.
+ */
+
+describe("{{name}} resilience helpers", () => {
+  it("returns the underlying value on success", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.of("ok");
+    const result = await resilient(unit, { maxAttempts: 1 }).run(ctx);
+    expect(result.value).toBe("ok");
+  });
+
+  it("falls back to the supplied default when the unit fails", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.fail<string>(new Error("simulated failure"));
+    const result = await resilient(unit, { fallback: "safe-default" }).run(
+      ctx,
+    );
+    expect(result.value).toBe("safe-default");
+  });
+});
+
+describe("{{name}} provenance helpers", () => {
+  it("wraps the value in a TrackedResult envelope", async () => {
+    const ctx = createContext();
+    const unit = AgentUnit.of("payload");
+    const result = await withProvenance(unit, {
+      source: "agent",
+      confidence: 0.95,
+      verifiedBy: "unit-test",
+    }).run(ctx);
+
+    // The result of .tracked() is itself a TrackedResult<TrackedResult<T>>
+    // — the outer envelope is added by .run() in zero-trust mode, the inner
+    // one is what `withProvenance` applied. We confirm both layers exist.
+    expect(result.value).toBeDefined();
+    expect(isTracked(result.value)).toBe(true);
+    expect(result.value.confidence).toBeCloseTo(0.95);
+    expect(result.value.source).toBe("agent");
+  });
+});

package/dist/templates/project/standard/tsconfig.json.template

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": {{strict}},
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "agents/**/*"]
+}

package/dist/utils/templates.d.ts

@@ -0,0 +1,41 @@
+/** Available project template tiers */
+export type ProjectTier = "minimal" | "standard" | "full";
+/** Available agent template types */
+export type AgentType = "general" | "researcher" | "reviewer" | "typescript";
+/** Template variable map */
+export type TemplateVars = Record<string, string>;
+/**
+ * Process a template string by replacing {{variableName}} with actual values
+ * Unmatched variables are preserved as-is
+ */
+export declare function processTemplate(content: string, vars: TemplateVars): string;
+/**
+ * Get the absolute path to a project template file
+ */
+export declare function getProjectTemplatePath(tier: ProjectTier, ...pathSegments: string[]): string;
+/**
+ * Get the absolute path to an agent template file
+ */
+export declare function getAgentTemplatePath(filename: string): string;
+/**
+ * Load a project template file and process it with variables
+ */
+export declare function loadProjectTemplate(tier: ProjectTier, pathSegments: string[], vars?: TemplateVars): string;
+/**
+ * Load an agent template file and process it with variables
+ */
+export declare function loadAgentTemplate(type: AgentType, vars?: TemplateVars): string;
+/**
+ * Get the templates root directory path
+ */
+export declare function getTemplatesRoot(): string;
+/**
+ * Get list of files for a project tier
+ * Higher tiers inherit from lower tiers
+ */
+export declare function getProjectTierFiles(tier: ProjectTier): string[];
+/**
+ * Default template variables with sensible defaults
+ */
+export declare function getDefaultVars(name: string): TemplateVars;
+//# sourceMappingURL=templates.d.ts.map

package/dist/utils/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/utils/templates.ts"],"names":[],"mappings":"AAcA,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE1D,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAE7E,4BAA4B;AAC5B,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAE3E;AAkBD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,GAAG,YAAY,EAAE,MAAM,EAAE,GACxB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EAAE,EACtB,IAAI,GAAE,YAAiB,GACtB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,YAAiB,GACtB,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CA8B/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAYzD"}