@kici-dev/compiler 0.0.0 → 0.1.2

package/dist/remote/uploader.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Summary of files included in the overlay tarball.
+ */
+interface UploadSummary {
+    /** Total files in tarball */
+    fileCount: number;
+    /** Untracked (new) files */
+    newFiles: number;
+    /** Modified files (staged + unstaged) */
+    modifiedFiles: number;
+    /** Files deleted locally */
+    deletedFiles: number;
+    /** Tarball size in bytes (compressed) */
+    compressedSize: number;
+    /** HEAD SHA */
+    sha: string;
+}
+/**
+ * Manifest describing the overlay contents.
+ * Used by the agent to apply the overlay on top of a fresh clone.
+ */
+export interface OverlayManifest {
+    /** HEAD SHA the overlay is based on */
+    sha: string;
+    /** Files deleted locally (need to be removed on agent) */
+    deletions: string[];
+    /** SHA256 checksums of each included file */
+    checksums: Record<string, string>;
+}
+/**
+ * Options for uploading a tarball.
+ */
+interface UploadOptions {
+    /** Path to the tarball file */
+    tarballPath: string;
+    /** Pre-signed URL to upload to */
+    signedUrl: string;
+    /** Orchestrator's X25519 public key for encryption */
+    orchestratorPublicKey: Buffer;
+    /** Progress callback (bytes uploaded, total bytes) */
+    onProgress?: (bytes: number, total: number) => void;
+}
+/**
+ * Result of a successful upload.
+ */
+interface UploadResult {
+    /** Upload identifier */
+    uploadId: string;
+    /** CLI's ephemeral public key (needed by agent for decryption) */
+    cliPublicKey: Buffer;
+    /** Encrypted tarball size in bytes */
+    encryptedSize: number;
+}
+/**
+ * Create an overlay tarball from a git repo, including only changed files.
+ *
+ * For repos with a remote: collects only dirty files (staged, unstaged, untracked).
+ * For repos without a remote: collects ALL tracked + untracked files (full tarball).
+ *
+ * The tarball includes a `manifest.json` with the HEAD SHA, deletions list,
+ * and SHA256 checksums for integrity verification.
+ *
+ * @param repoRoot - Path to the git repository root
+ * @param options - Optional configuration
+ * @returns Tarball path, upload summary, and overlay manifest
+ */
+export declare function createOverlayTarball(repoRoot: string, options?: {
+    kiciIgnorePath?: string;
+}): Promise<{
+    tarballPath: string;
+    summary: UploadSummary;
+    manifest: OverlayManifest;
+    hasRemote: boolean;
+}>;
+/**
+ * Returns a human-readable size warning if above threshold, or null.
+ */
+export declare function getSizeWarning(compressedSize: number): string | null;
+/**
+ * Upload an encrypted tarball to a pre-signed URL.
+ *
+ * Encrypts the tarball with X25519 ECDH, uploads via HTTP PUT,
+ * and retries up to 3 times on network failures (not on 4xx).
+ */
+export declare function uploadTarball(opts: UploadOptions): Promise<UploadResult>;
+export {};
+//# sourceMappingURL=uploader.d.ts.map

package/dist/remote/uploader.js

@@ -0,0 +1,197 @@
+import "../chunk-gOLHoazu.js";
+import { encryptTarball } from "./encryption.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { formatBytes, sha256, sha256File } from "@kici-dev/shared";
+import os from "node:os";
+import picomatch from "picomatch";
+import { create } from "tar";
+//#region src/remote/uploader.ts
+/** Size threshold for warning (50MB) */
+const SIZE_WARN_THRESHOLD = 50 * 1024 * 1024;
+/** Size threshold for hard error (500MB) */
+const SIZE_ERROR_THRESHOLD = 500 * 1024 * 1024;
+/** Maximum upload retry attempts */
+const MAX_RETRIES = 3;
+/**
+* Run a git command and return trimmed stdout lines.
+* Returns empty array if command produces no output.
+*/
+function gitLines(cmd, cwd) {
+	try {
+		const output = execSync(cmd, {
+			cwd,
+			encoding: "utf-8"
+		}).trim();
+		if (!output) return [];
+		return output.split("\n").filter((l) => l.length > 0);
+	} catch {
+		return [];
+	}
+}
+/**
+* Load .kiciignore patterns from a file.
+* Returns a picomatch matcher function or null if file doesn't exist.
+*/
+async function loadKiciIgnore(kiciIgnorePath) {
+	try {
+		const patterns = (await fs.readFile(kiciIgnorePath, "utf-8")).split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
+		if (patterns.length === 0) return null;
+		const matcher = picomatch(patterns);
+		return (file) => matcher(file);
+	} catch {
+		return null;
+	}
+}
+/**
+* Create an overlay tarball from a git repo, including only changed files.
+*
+* For repos with a remote: collects only dirty files (staged, unstaged, untracked).
+* For repos without a remote: collects ALL tracked + untracked files (full tarball).
+*
+* The tarball includes a `manifest.json` with the HEAD SHA, deletions list,
+* and SHA256 checksums for integrity verification.
+*
+* @param repoRoot - Path to the git repository root
+* @param options - Optional configuration
+* @returns Tarball path, upload summary, and overlay manifest
+*/
+async function createOverlayTarball(repoRoot, options) {
+	const sha = execSync("git rev-parse HEAD", {
+		cwd: repoRoot,
+		encoding: "utf-8"
+	}).trim();
+	const hasRemote = gitLines("git remote", repoRoot).length > 0;
+	let allFiles;
+	if (hasRemote) {
+		const unstaged = gitLines("git diff --name-only HEAD", repoRoot);
+		const staged = gitLines("git diff --name-only --cached HEAD", repoRoot);
+		const untracked = gitLines("git ls-files --others --exclude-standard", repoRoot);
+		allFiles = [...new Set([
+			...unstaged,
+			...staged,
+			...untracked
+		])];
+	} else {
+		const tracked = gitLines("git ls-files", repoRoot);
+		const untracked = gitLines("git ls-files --others --exclude-standard", repoRoot);
+		allFiles = [...new Set([...tracked, ...untracked])];
+	}
+	const kiciIgnore = await loadKiciIgnore(options?.kiciIgnorePath ?? path.join(repoRoot, ".kiciignore"));
+	if (kiciIgnore) allFiles = allFiles.filter((f) => !kiciIgnore(f));
+	const existingFiles = [];
+	const deletedFiles = [];
+	await Promise.all(allFiles.map(async (file) => {
+		const fullPath = path.join(repoRoot, file);
+		try {
+			await fs.access(fullPath);
+			existingFiles.push(file);
+		} catch {
+			deletedFiles.push(file);
+		}
+	}));
+	const untrackedSet = new Set(gitLines("git ls-files --others --exclude-standard", repoRoot));
+	const newFiles = existingFiles.filter((f) => untrackedSet.has(f));
+	const modifiedFiles = existingFiles.filter((f) => !untrackedSet.has(f));
+	const checksums = {};
+	await Promise.all(existingFiles.map(async (file) => {
+		checksums[file] = await sha256File(path.join(repoRoot, file));
+	}));
+	const manifest = {
+		sha,
+		deletions: deletedFiles,
+		checksums
+	};
+	const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "kici-overlay-"));
+	const manifestPath = path.join(tmpDir, "manifest.json");
+	await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+	const manifestRelDir = ".kici-overlay-tmp";
+	const manifestRepoDir = path.join(repoRoot, manifestRelDir);
+	await fs.mkdir(manifestRepoDir, { recursive: true });
+	await fs.copyFile(manifestPath, path.join(manifestRepoDir, "manifest.json"));
+	const tarballPath = path.join(tmpDir, "overlay.tar.gz");
+	try {
+		const filesToInclude = [...existingFiles, path.join(manifestRelDir, "manifest.json")];
+		if (filesToInclude.length > 0) await create({
+			gzip: true,
+			file: tarballPath,
+			cwd: repoRoot
+		}, filesToInclude);
+		else await create({
+			gzip: true,
+			file: tarballPath,
+			cwd: repoRoot
+		}, []);
+	} finally {
+		await fs.rm(manifestRepoDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	const compressedSize = (await fs.stat(tarballPath)).size;
+	if (compressedSize > SIZE_ERROR_THRESHOLD) throw new Error(`Tarball size ${formatBytes(compressedSize)} exceeds 500MB limit. Use --dangerously-allow-large-upload to override.`);
+	return {
+		tarballPath,
+		summary: {
+			fileCount: existingFiles.length,
+			newFiles: newFiles.length,
+			modifiedFiles: modifiedFiles.length,
+			deletedFiles: deletedFiles.length,
+			compressedSize,
+			sha
+		},
+		manifest,
+		hasRemote
+	};
+}
+/**
+* Returns a human-readable size warning if above threshold, or null.
+*/
+function getSizeWarning(compressedSize) {
+	if (compressedSize >= SIZE_WARN_THRESHOLD && compressedSize < SIZE_ERROR_THRESHOLD) return `Warning: tarball size is ${formatBytes(compressedSize)} (above 50MB warning threshold)`;
+	return null;
+}
+/**
+* Upload an encrypted tarball to a pre-signed URL.
+*
+* Encrypts the tarball with X25519 ECDH, uploads via HTTP PUT,
+* and retries up to 3 times on network failures (not on 4xx).
+*/
+async function uploadTarball(opts) {
+	const { tarballPath, signedUrl, orchestratorPublicKey, onProgress } = opts;
+	const { encryptedPath, cliPublicKey } = await encryptTarball(tarballPath, orchestratorPublicKey);
+	const encryptedData = await fs.readFile(encryptedPath);
+	const encryptedSize = encryptedData.length;
+	let lastError = null;
+	for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) try {
+		const response = await fetch(signedUrl, {
+			method: "PUT",
+			body: encryptedData,
+			headers: {
+				"Content-Type": "application/octet-stream",
+				"Content-Length": encryptedSize.toString()
+			}
+		});
+		if (response.status >= 400 && response.status < 500) throw new Error(`Upload failed with status ${response.status}: ${response.statusText}`);
+		if (!response.ok) throw new Error(`Upload failed with status ${response.status}: ${response.statusText}`);
+		onProgress?.(encryptedSize, encryptedSize);
+		const uploadId = (response.headers.get("etag")?.replace(/"/g, "") ?? "") || sha256(encryptedData).slice(0, 16);
+		await fs.unlink(encryptedPath).catch(() => {});
+		return {
+			uploadId,
+			cliPublicKey,
+			encryptedSize
+		};
+	} catch (err) {
+		lastError = err instanceof Error ? err : new Error(String(err));
+		if (lastError.message.includes("status 4")) throw lastError;
+		if (attempt < MAX_RETRIES) await new Promise((resolve) => setTimeout(resolve, 1e3 * attempt));
+	}
+	await fs.unlink(encryptedPath).catch(() => {});
+	throw new Error(`Upload failed after ${MAX_RETRIES} attempts: ${lastError?.message}`);
+}
+//#endregion
+export { createOverlayTarball, getSizeWarning, uploadTarball };
+
+//# sourceMappingURL=uploader.js.map

package/dist/review-comment-created.json

@@ -0,0 +1,36 @@
+{
+  "action": "created",
+  "comment": {
+    "id": 1,
+    "body": "Consider refactoring this",
+    "path": "src/index.ts",
+    "line": 42,
+    "user": {
+      "login": "reviewer"
+    }
+  },
+  "pull_request": {
+    "number": 42,
+    "title": "Test PR",
+    "state": "open",
+    "head": {
+      "ref": "feature-branch",
+      "sha": "abc123"
+    },
+    "base": {
+      "ref": "main",
+      "sha": "def456"
+    }
+  },
+  "repository": {
+    "name": "test-repo",
+    "full_name": "test-org/test-repo",
+    "owner": {
+      "login": "test-org"
+    },
+    "default_branch": "main"
+  },
+  "sender": {
+    "login": "reviewer"
+  }
+}

package/dist/review-submitted.json

@@ -0,0 +1,35 @@
+{
+  "action": "submitted",
+  "review": {
+    "id": 1,
+    "state": "approved",
+    "body": "LGTM",
+    "user": {
+      "login": "reviewer"
+    }
+  },
+  "pull_request": {
+    "number": 42,
+    "title": "Test PR",
+    "state": "open",
+    "head": {
+      "ref": "feature-branch",
+      "sha": "abc123"
+    },
+    "base": {
+      "ref": "main",
+      "sha": "def456"
+    }
+  },
+  "repository": {
+    "name": "test-repo",
+    "full_name": "test-org/test-repo",
+    "owner": {
+      "login": "test-org"
+    },
+    "default_branch": "main"
+  },
+  "sender": {
+    "login": "reviewer"
+  }
+}

package/dist/star-created.json

@@ -0,0 +1,15 @@
+{
+  "action": "created",
+  "repository": {
+    "name": "test-repo",
+    "full_name": "test-org/test-repo",
+    "owner": {
+      "login": "test-org"
+    },
+    "default_branch": "main",
+    "stargazers_count": 100
+  },
+  "sender": {
+    "login": "test-user"
+  }
+}

package/dist/status.json

@@ -0,0 +1,26 @@
+{
+  "state": "success",
+  "context": "ci/test",
+  "sha": "abc123def456",
+  "description": "Build succeeded",
+  "target_url": "https://ci.example.com/builds/1",
+  "branches": [
+    {
+      "name": "main",
+      "commit": {
+        "sha": "abc123def456"
+      }
+    }
+  ],
+  "repository": {
+    "name": "test-repo",
+    "full_name": "test-org/test-repo",
+    "owner": {
+      "login": "test-org"
+    },
+    "default_branch": "main"
+  },
+  "sender": {
+    "login": "test-user"
+  }
+}

package/dist/tag-push.json

@@ -0,0 +1,20 @@
+{
+  "ref": "refs/tags/v1.0.0",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "abc123def456",
+  "repository": {
+    "name": "test-repo",
+    "full_name": "test-org/test-repo",
+    "owner": {
+      "login": "test-org"
+    },
+    "default_branch": "main"
+  },
+  "pusher": {
+    "name": "test-user"
+  },
+  "sender": {
+    "login": "test-user"
+  },
+  "commits": []
+}

package/dist/templates/agents-md.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Template body for .kici/AGENTS.md, written by `kici init` (unless opted out
+ * via --no-agents-md). The format follows the cross-tool AGENTS.md convention
+ * picked up by Claude Code, Cursor, Aider, and other coding agents that scan
+ * the working tree for an authoring context file.
+ */
+export declare const agentsMdTemplate = "# KiCI workflow authoring guide\n\nThis project uses KiCI \u2014 a TypeScript-native CI/CD workflow engine \u2014 instead\nof YAML-based CI. Workflows live in `.kici/workflows/*.ts`, are compiled\ninto a portable lock file, and executed by self-hosted agents.\n\n## Where the API surface lives\n\n- Public SDK types: `node_modules/@kici-dev/sdk/dist/index.d.ts` \u2014 read this\n  for the canonical signatures of `workflow`, `job`, `step`, `pr`,\n  `push`, `schedule`, `matrix`, `rule`, `dynamicJob`, etc.\n- Bundled offline reference for coding agents: `kici docs llm` prints the\n  full markdown documentation bundle to stdout. `kici docs llm --index`\n  prints just the curated link index (llms.txt format).\n- Online docs:\n  - <https://kici.dev/docs/> \u2014 published docs site.\n  - <https://kici.dev/llms.txt> \u2014 curated index for LLM consumers.\n  - <https://kici.dev/llms-full.txt> \u2014 full markdown bundle.\n  - Key pages: `user/sdk-reference`, `user/workflow-patterns`,\n    `user/testing-guide`, `user/hooks`, `user/secrets`.\n\n## The five core patterns\n\n1. **Push trigger** \u2014 `on: push({ branches: 'main' })`. Pair with `paths`\n   to scope to subtrees.\n\n   ```ts\n   import { workflow, job, step, push } from '@kici-dev/sdk';\n\n   export default workflow('build', {\n     on: push({ branches: 'main' }),\n     jobs: [\n       job('build', {\n         runsOn: 'ubuntu-latest',\n         steps: [step('install', async ({ $ }) => { await $`pnpm install`; })],\n       }),\n     ],\n   });\n   ```\n\n2. **PR + matrix** \u2014 `pr({ target: 'main' })` plus a matrix over node\n   versions. The matrix expands at dispatch time.\n\n   ```ts\n   import { workflow, job, step, pr, matrix } from '@kici-dev/sdk';\n\n   export default workflow('test-matrix', {\n     on: pr({ target: 'main' }),\n     jobs: [\n       job('test', {\n         runsOn: 'ubuntu-latest',\n         strategy: { matrix: matrix({ node: ['20', '22', '24'] }) },\n         steps: [\n           step('test', async ({ $, matrix }) => {\n             await $`node --version`;\n             await $`pnpm install`;\n             await $`pnpm test`;\n             return { node: matrix.node };\n           }),\n         ],\n       }),\n     ],\n   });\n   ```\n\n3. **Lifecycle hooks** \u2014 `onFailure` / `onSuccess` / `onCancel` on a\n   job or workflow run after the main steps in their own scope.\n\n4. **Secrets** \u2014 declared scopes resolve at dispatch:\n\n   ```ts\n   step('deploy', async ({ $, secrets }) => {\n     await $`./scripts/deploy.sh`.env({ DEPLOY_TOKEN: secrets.production.DEPLOY_TOKEN });\n   });\n   ```\n\n   Run `kici secrets list` to enumerate the contexts available for testing.\n\n5. **Dynamic jobs** \u2014 `dynamicJob` and `dynamicGroup` build the DAG at\n   runtime from a step's outputs. Don't try to compute job names at top level;\n   the lock file would be wrong.\n\n## Anti-patterns\n\n- **Do NOT write `.yml` / `.yaml` CI files** \u2014 KiCI replaces that entire\n  layer. There is no compatibility shim.\n- **Do NOT `import` from any `@kici-dev/*` package's `/dist/...`\n  subpath** \u2014 those are not part of the public API and break across versions.\n  Import from the package root.\n- **Do NOT `await` outside step bodies.** The top-level workflow file is\n  loaded by the compiler synchronously; async I/O at module scope means the\n  lock file emits before it resolves and the workflow appears empty.\n- **Do NOT mutate shared variables between jobs.** Each job runs in its own\n  agent process. Use `needs` + step outputs to thread values.\n- **Do NOT hand-edit `kici.lock.json`.** Regenerate it via `kici compile`.\n\n## Local commands a coding agent should run\n\n| Command                         | Purpose                                     |\n| ------------------------------- | ------------------------------------------- |\n| `pnpm kici compile --check`     | Validate workflow source without writing.   |\n| `pnpm kici test pr:open --debug`| Preview which workflows match an event.     |\n| `pnpm kici run local push`      | Execute workflows locally with no orchestrator. |\n| `pnpm kici docs llm`            | Print the full LLM documentation bundle.    |\n| `pnpm kici docs llm --index`    | Print the curated link index.               |\n\nIf `pnpm kici` isn't in scripts, fall back to `npx kici`.\n\n## Loop\n\n1. Read the SDK types from `node_modules/@kici-dev/sdk/dist/index.d.ts`.\n2. Pipe `kici docs llm` into the agent's context if it doesn't already have\n   the full bundle.\n3. Edit a workflow under `.kici/workflows/`.\n4. Run `kici compile --check` (zero exit means valid).\n5. Run `kici test <event>` to preview matching.\n6. Run `kici run local <event>` to execute locally before pushing.\n";
+//# sourceMappingURL=agents-md.d.ts.map

package/dist/templates/agents-md.js

@@ -0,0 +1,130 @@
+import "../chunk-gOLHoazu.js";
+//#region src/templates/agents-md.ts
+/**
+* Template body for .kici/AGENTS.md, written by `kici init` (unless opted out
+* via --no-agents-md). The format follows the cross-tool AGENTS.md convention
+* picked up by Claude Code, Cursor, Aider, and other coding agents that scan
+* the working tree for an authoring context file.
+*/
+const agentsMdTemplate = `# KiCI workflow authoring guide
+
+This project uses KiCI — a TypeScript-native CI/CD workflow engine — instead
+of YAML-based CI. Workflows live in \`.kici/workflows/*.ts\`, are compiled
+into a portable lock file, and executed by self-hosted agents.
+
+## Where the API surface lives
+
+- Public SDK types: \`node_modules/@kici-dev/sdk/dist/index.d.ts\` — read this
+  for the canonical signatures of \`workflow\`, \`job\`, \`step\`, \`pr\`,
+  \`push\`, \`schedule\`, \`matrix\`, \`rule\`, \`dynamicJob\`, etc.
+- Bundled offline reference for coding agents: \`kici docs llm\` prints the
+  full markdown documentation bundle to stdout. \`kici docs llm --index\`
+  prints just the curated link index (llms.txt format).
+- Online docs:
+  - <https://kici.dev/docs/> — published docs site.
+  - <https://kici.dev/llms.txt> — curated index for LLM consumers.
+  - <https://kici.dev/llms-full.txt> — full markdown bundle.
+  - Key pages: \`user/sdk-reference\`, \`user/workflow-patterns\`,
+    \`user/testing-guide\`, \`user/hooks\`, \`user/secrets\`.
+
+## The five core patterns
+
+1. **Push trigger** — \`on: push({ branches: 'main' })\`. Pair with \`paths\`
+   to scope to subtrees.
+
+   \`\`\`ts
+   import { workflow, job, step, push } from '@kici-dev/sdk';
+
+   export default workflow('build', {
+     on: push({ branches: 'main' }),
+     jobs: [
+       job('build', {
+         runsOn: 'ubuntu-latest',
+         steps: [step('install', async ({ $ }) => { await $\`pnpm install\`; })],
+       }),
+     ],
+   });
+   \`\`\`
+
+2. **PR + matrix** — \`pr({ target: 'main' })\` plus a matrix over node
+   versions. The matrix expands at dispatch time.
+
+   \`\`\`ts
+   import { workflow, job, step, pr, matrix } from '@kici-dev/sdk';
+
+   export default workflow('test-matrix', {
+     on: pr({ target: 'main' }),
+     jobs: [
+       job('test', {
+         runsOn: 'ubuntu-latest',
+         strategy: { matrix: matrix({ node: ['20', '22', '24'] }) },
+         steps: [
+           step('test', async ({ $, matrix }) => {
+             await $\`node --version\`;
+             await $\`pnpm install\`;
+             await $\`pnpm test\`;
+             return { node: matrix.node };
+           }),
+         ],
+       }),
+     ],
+   });
+   \`\`\`
+
+3. **Lifecycle hooks** — \`onFailure\` / \`onSuccess\` / \`onCancel\` on a
+   job or workflow run after the main steps in their own scope.
+
+4. **Secrets** — declared scopes resolve at dispatch:
+
+   \`\`\`ts
+   step('deploy', async ({ $, secrets }) => {
+     await $\`./scripts/deploy.sh\`.env({ DEPLOY_TOKEN: secrets.production.DEPLOY_TOKEN });
+   });
+   \`\`\`
+
+   Run \`kici secrets list\` to enumerate the contexts available for testing.
+
+5. **Dynamic jobs** — \`dynamicJob\` and \`dynamicGroup\` build the DAG at
+   runtime from a step's outputs. Don't try to compute job names at top level;
+   the lock file would be wrong.
+
+## Anti-patterns
+
+- **Do NOT write \`.yml\` / \`.yaml\` CI files** — KiCI replaces that entire
+  layer. There is no compatibility shim.
+- **Do NOT \`import\` from any \`@kici-dev/*\` package's \`/dist/...\`
+  subpath** — those are not part of the public API and break across versions.
+  Import from the package root.
+- **Do NOT \`await\` outside step bodies.** The top-level workflow file is
+  loaded by the compiler synchronously; async I/O at module scope means the
+  lock file emits before it resolves and the workflow appears empty.
+- **Do NOT mutate shared variables between jobs.** Each job runs in its own
+  agent process. Use \`needs\` + step outputs to thread values.
+- **Do NOT hand-edit \`kici.lock.json\`.** Regenerate it via \`kici compile\`.
+
+## Local commands a coding agent should run
+
+| Command                         | Purpose                                     |
+| ------------------------------- | ------------------------------------------- |
+| \`pnpm kici compile --check\`     | Validate workflow source without writing.   |
+| \`pnpm kici test pr:open --debug\`| Preview which workflows match an event.     |
+| \`pnpm kici run local push\`      | Execute workflows locally with no orchestrator. |
+| \`pnpm kici docs llm\`            | Print the full LLM documentation bundle.    |
+| \`pnpm kici docs llm --index\`    | Print the curated link index.               |
+
+If \`pnpm kici\` isn't in scripts, fall back to \`npx kici\`.
+
+## Loop
+
+1. Read the SDK types from \`node_modules/@kici-dev/sdk/dist/index.d.ts\`.
+2. Pipe \`kici docs llm\` into the agent's context if it doesn't already have
+   the full bundle.
+3. Edit a workflow under \`.kici/workflows/\`.
+4. Run \`kici compile --check\` (zero exit means valid).
+5. Run \`kici test <event>\` to preview matching.
+6. Run \`kici run local <event>\` to execute locally before pushing.
+`;
+//#endregion
+export { agentsMdTemplate };
+
+//# sourceMappingURL=agents-md.js.map

package/dist/templates/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Template aggregator for kici init command
+ *
+ * Re-exports all templates for easy consumption by the init command.
+ */
+export { helloWorldWorkflow } from './workflows/hello-world.js';
+export { prChecksWorkflow } from './workflows/pr-checks.js';
+export { generatePackageJson } from './package-json.js';
+export { tsconfigTemplate } from './tsconfig-json.js';
+export { agentsMdTemplate } from './agents-md.js';
+/**
+ * Workflow file paths for init command
+ *
+ * Maps workflow names to their source file paths.
+ * Used by init command to read and copy workflow templates.
+ */
+export declare const workflowPaths: {
+    readonly 'hello-world': string;
+    readonly 'pr-checks': string;
+};
+/**
+ * Real workflow objects map
+ *
+ * Maps workflow names to their compiled workflow objects.
+ * Used for testing and type validation.
+ */
+export declare const workflows: {
+    readonly 'hello-world': import("@kici-dev/sdk").Workflow;
+    readonly 'pr-checks': import("@kici-dev/sdk").Workflow;
+};
+/**
+ * All templates aggregated
+ *
+ * Provides a single object with all template types.
+ */
+export declare const templates: {
+    readonly workflowPaths: {
+        readonly 'hello-world': string;
+        readonly 'pr-checks': string;
+    };
+    readonly tsconfig: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/index.js

@@ -0,0 +1,48 @@
+import "../chunk-gOLHoazu.js";
+import { helloWorldWorkflow } from "./workflows/hello-world.js";
+import { prChecksWorkflow } from "./workflows/pr-checks.js";
+import { tsconfigTemplate } from "./tsconfig-json.js";
+import { generatePackageJson } from "./package-json.js";
+import { agentsMdTemplate } from "./agents-md.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/templates/index.ts
+/**
+* Template aggregator for kici init command
+*
+* Re-exports all templates for easy consumption by the init command.
+*/
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+* Workflow file paths for init command
+*
+* Maps workflow names to their source file paths.
+* Used by init command to read and copy workflow templates.
+*/
+const workflowPaths = {
+	"hello-world": path.join(__dirname, "workflows", "hello-world.ts"),
+	"pr-checks": path.join(__dirname, "workflows", "pr-checks.ts")
+};
+/**
+* Real workflow objects map
+*
+* Maps workflow names to their compiled workflow objects.
+* Used for testing and type validation.
+*/
+const workflows = {
+	"hello-world": helloWorldWorkflow,
+	"pr-checks": prChecksWorkflow
+};
+/**
+* All templates aggregated
+*
+* Provides a single object with all template types.
+*/
+const templates = {
+	workflowPaths,
+	tsconfig: tsconfigTemplate
+};
+//#endregion
+export { agentsMdTemplate, generatePackageJson, helloWorldWorkflow, prChecksWorkflow, templates, tsconfigTemplate, workflowPaths, workflows };
+
+//# sourceMappingURL=index.js.map

package/dist/templates/package-json.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Package.json template generator for kici init command
+ *
+ * Generates package.json for .kici/ directory in TypeScript mode.
+ * SDK is a devDependency resolved from the npm registry
+ * (or a private Verdaccio instance when .npmrc scopes the registry).
+ * The compiler is invoked via npx (not installed as a dependency).
+ */
+/**
+ * Generate package.json content for .kici/ directory
+ *
+ * @param devMode - When true, uses a prerelease-compatible version range
+ *   (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds (e.g. 0.0.1-2856).
+ *   Semver `^0.0.1` does NOT match prereleases, causing 404s on Verdaccio.
+ * @returns JSON string with proper formatting (2-space indent, trailing newline)
+ */
+export declare function generatePackageJson(devMode?: boolean): string;
+//# sourceMappingURL=package-json.d.ts.map