agentic-scaffold 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this package are in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.3 - 2026-10-29
+
+### Removed
+
+- The Worker route `POST /summarize` is gone. Use `POST /api/v1/summarize` instead.
+  The new route needs a bearer key. See the migration section in the
+  [README](README.md#migration-worker-auth).
+
+### Security
+
+- The `zod` dependency is `^4.6.7`. zod 3.25.76 was below the fixed version for
+  GHSA-mrhx-c7xc-m3w5, which allows memory exhaustion when validating oversized
+  constrained collections. The package API is unchanged.
+- `POST /api/v1/summarize` requires a bearer key with the `text:read` scope. A missing
+  key gets 401, a missing scope gets 403, and a Worker with no `AUTH_TOKENS` secret gets
+  503. Before, the route had no auth.
+
+### Fixed
+
+- The deployed Worker builds its Auth from the `AUTH_TOKENS` string secret. Before, a
+  Cloudflare binding could not hold an Auth object, so a deployed Worker always answered
+  503. The `AUTH` env field stays as a test seam.
+- `mcp --help`, `-h`, `--version` and `-V` print and exit 0 for the cli and the mcp bin,
+  without starting the server.
+
+### Changed
+
+- The publish workflow runs one publish at a time for each ref, so two runs cannot
+  publish at once.
+- The publish workflow also publishes to ants.land. It skips a version that is already
+  there.
+- The repository has a CI workflow (Node 22: typecheck, test, build) and a `ci:local`
+  script.

package/README.md

@@ -1,108 +1,78 @@
-# Agentic scaffold
+# agentic-scaffold
 
-Canonical scaffold for a CLI plus library plus MCP server pack.
+[![npm version](https://img.shields.io/npm/v/agentic-scaffold)](https://www.npmjs.com/package/agentic-scaffold)
+[![Monthly downloads](https://img.shields.io/npm/dm/agentic-scaffold)](https://www.npmjs.com/package/agentic-scaffold)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)
 
-Clone this repo to start a new pack. It gives one core with three
-faces: a terminal command, an npm import, and an MCP server.
+[Package](https://www.npmjs.com/package/agentic-scaffold) · [Source](https://github.com/pooriaarab/agentic-scaffold) · [Support](https://github.com/pooriaarab/agentic-scaffold/issues)
 
-## What you get
+agentic-scaffold is an open-source TypeScript starter for developers who need a Node.js library, command-line interface, and Model Context Protocol (MCP) server.
 
-- One core: brand config, logs, guards, routing, dry run, cost reports.
-- Three faces over that core: CLI, library, MCP server.
-- A frozen core contract, so packs share one API.
-- A worker entry and a wrangler sample for edge deploys.
-- Build, typecheck, and tests that pass from a fresh clone.
-
-## Quick start
+## Install
 
 ```sh
-git clone https://github.com/pooriaarab/agentic-scaffold.git my-pack
-cd my-pack
-npm install
-npm run build
-npm run typecheck
-npm test
+npm install agentic-scaffold
 ```
 
-Run the command:
+Requires Node.js 18 or later. Includes TypeScript declarations and two direct dependencies: the MCP SDK and Zod.
+
+## Run your first summary
+
+No credentials, environment variables, or `.env` loader are required.
 
 ```sh
-node dist/cli.js summary --text "hello world hello"
+npx agentic-scaffold summary --text "hello world hello"
 ```
 
-Call the library:
+Success prints JSON with `chars: 17`, `words: 3`, `lines: 1`, and `hello` counted twice.
 
 ```js
-import { summarizeText } from "./dist/index.js";
-
+import { summarizeText, getCostReport } from "agentic-scaffold";
 console.log(summarizeText("hello world hello"));
+console.log(getCostReport()); // { entries: [], dispatches: 0, units: 0 }
 ```
 
-Start the MCP server:
-
-```sh
-node dist/cli.js mcp
-```
-
-## Three usecases
-
-1. You run one text summary from the terminal.
-2. You import the summary function in a script.
-3. You let an agent call the same function as an MCP tool.
+## Features and runtime surfaces
 
-## Clone checklist
+- **Text statistics:** Character, word, line, and top-word counts; no semantic summarization.
+- **Routing:** Two generic adapters: local receipts and HTTP POST with `{ text }`.
+- **Guards:** Optional dispatch caps, UTC quiet hours, and text blocklists.
+- **Utilities:** Brand configuration, stderr logging, dry-run results, and in-memory cost units.
+- **CLI:** `summary`, `dispatch`, `costs`, `mcp`; help via `--help` and version via `--version`.
+- **MCP:** Three tools: `summarize_text`, `dispatch_text`, `get_cost_report`.
+- **Worker scaffold:** Source handler for `GET /health` (open) and `POST /api/v1/summarize` (needs a bearer key with the `text:read` scope); users deploy it themselves.
 
-This repo is a template. Replace each slot in each file that holds it.
+Start MCP with `npx agentic-scaffold mcp`. Preview routing with `npx agentic-scaffold dispatch --text hello --dry-run`.
 
-- `__PACK_NAME__`: the directory name, like `my-pack`.
-- `__NPM_NAME__`: the npm name, like `agentic-<block>` (bare name, never @pooriaarab/ scoped unless the brief says scoped).
-- `__PACK_COMMAND__`: the terminal command, like `my-pack`.
-- `__PACK_DESCRIPTION__`: one plain sentence, under 100 chars.
-- `__PACK_KEYWORDS__`: plain keywords, like `notes, search, cli`.
-- `__GITHUB_USER__`: the repo owner, like `pooriaarab`.
+## Migration: Worker auth
 
-Slot files: `AGENTS.md`, `SKILL.md`, `RULES.md`, `llms.txt`,
-`server.json`, `.mcp.json`, `wrangler.jsonc`.
+`POST /summarize` is gone. Use `POST /api/v1/summarize`. It needs `Authorization: Bearer <key>` and a principal with the `text:read` scope. A missing or bad key gets 401. A key without the scope gets 403. Set the `AUTH_TOKENS` secret to a JSON object of bearer token (32 bytes or more) to `kind:name`, or to `{ "as": "kind:name", "scopes": ["text:read"] }`. A bad entry refuses the whole table. If `AUTH_TOKENS` is missing, the route answers 503. `GET /health` stays open.
 
-Then rename the scaffold identity itself:
+## Limits
 
-- `package.json`: name, bin commands, mcpName. Remove `"private": true`.
-- `src/index.ts`: the `DEFAULT_BRAND` fields.
-- This file: the pitch and the examples above.
+This starter has zero vendor-specific integrations. Local dispatch creates a receipt without external delivery.
+CLI and MCP dispatch use the local adapter by default; SDK callers can supply the HTTP adapter.
+HTTP delivery defaults to a ten-second timeout, with no retries. Cost units count text length rather than billing charges.
+Reports reset when the process exits. CLI help and MCP identity still use the starter name `agentic-pack`.
 
-At publish time, set `server.json` version to the npm version and
-`server.json` repository id from `gh api repos/OWNER/REPO --jq .id`.
-
-## Gates
-
-Run all three before you push a pack:
+## Customize a cloned starter
 
 ```sh
+git clone https://github.com/pooriaarab/agentic-scaffold.git my-pack
+cd my-pack
+npm ci
 npm run build && npm run typecheck && npm test
+node dist/cli.js summary --text "hello world hello"
 ```
 
-Then run the real installed CLI once from a tarball:
-
-```sh
-npm pack
-npx --yes --package ./pooriaarab-agentic-scaffold-0.1.0.tgz agentic-pack summary --text "hello"
-```
-
-## Release flow
-
-Push to `main` for review. Merge to `release` to publish. The
-publish workflow ships only when the version is new.
-
-## Layout
+Replace `__PACK_NAME__`, `__NPM_NAME__`, `__PACK_COMMAND__`, `__PACK_DESCRIPTION__`, `__PACK_KEYWORDS__`, and `__GITHUB_USER__` wherever they appear.
+Check `AGENTS.md`, `SKILL.md`, `RULES.md`, `llms.txt`, `server.json`, `.mcp.json`, and `wrangler.jsonc`.
+Update package identity, bin commands, `mcpName`, and `DEFAULT_BRAND` in `src/index.ts`.
+Set the MCP manifest version and repository ID before publishing your own package.
 
-- `src/index.ts`: the library face.
-- `src/cli.ts`: the terminal face.
-- `src/mcp.ts`: the MCP server. `src/mcp-bin.ts` starts it.
-- `src/worker.ts`: the edge worker face.
-- `src/core.ts`: the shared core.
-- `agentic-core.d.ts`: the frozen contract.
-- `docs/agentic-core.md`: the contract in plain words.
+The repository includes a shared core contract and a publish workflow. Inspect that workflow before adopting its release process.
+Version 0.1.3 is an early starter release; interfaces can change. See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-MIT. See `LICENSE`.
+MIT.

package/dist/{chunk-P7R4J6SZ.js → chunk-ENKHKKTS.js}

@@ -1,7 +1,7 @@
 import {
   VERSION,
   defineBrand
-} from "./chunk-E72J53UI.js";
+} from "./chunk-WGT6VR2C.js";
 
 // src/index.ts
 var DEFAULT_BRAND = defineBrand({

package/dist/{chunk-USTEVUWE.js → chunk-QLQX3SPS.js}

@@ -1,6 +1,6 @@
 import {
   DEFAULT_BRAND
-} from "./chunk-P7R4J6SZ.js";
+} from "./chunk-ENKHKKTS.js";
 import {
   GuardError,
   LocalRouterAdapter,
@@ -9,7 +9,7 @@ import {
   dispatchText,
   getCostReport,
   summarizeText
-} from "./chunk-E72J53UI.js";
+} from "./chunk-WGT6VR2C.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/{chunk-E72J53UI.js → chunk-WGT6VR2C.js}

@@ -206,7 +206,7 @@ function summarizeText(text, options = {}) {
 
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.1.1" : readPackageVersion();
+var VERSION = true ? "0.1.3" : readPackageVersion();
 
 export {
   defineBrand,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   DEFAULT_BRAND
-} from "./chunk-P7R4J6SZ.js";
+} from "./chunk-ENKHKKTS.js";
 import {
   GuardError,
   LocalRouterAdapter,
@@ -10,7 +10,7 @@ import {
   dispatchText,
   getCostReport,
   summarizeText
-} from "./chunk-E72J53UI.js";
+} from "./chunk-WGT6VR2C.js";
 
 // src/cli.ts
 import { readFileSync, realpathSync } from "fs";
@@ -36,6 +36,16 @@ function parseArgs(argv) {
     throw new UsageError(`unknown command "${first}"`);
   }
   request.command = first;
+  if (first === "mcp" && args.length > 0) {
+    if (args[0] === "--help" || args[0] === "-h") {
+      request.command = "help";
+      return request;
+    }
+    if (args[0] === "--version" || args[0] === "-V") {
+      request.command = "version";
+      return request;
+    }
+  }
   while (args.length > 0) {
     const flag = args.shift();
     if (flag === "--dry-run" && request.command === "dispatch") {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   DEFAULT_BRAND
-} from "./chunk-P7R4J6SZ.js";
+} from "./chunk-ENKHKKTS.js";
 import {
   GuardError,
   HttpRouterAdapter,
@@ -16,7 +16,7 @@ import {
   recordCost,
   resetCosts,
   summarizeText
-} from "./chunk-E72J53UI.js";
+} from "./chunk-WGT6VR2C.js";
 export {
   DEFAULT_BRAND,
   GuardError,

package/dist/mcp-bin.js

@@ -1,11 +1,26 @@
 #!/usr/bin/env node
 import {
   startMcp
-} from "./chunk-USTEVUWE.js";
-import "./chunk-P7R4J6SZ.js";
-import "./chunk-E72J53UI.js";
+} from "./chunk-QLQX3SPS.js";
+import {
+  DEFAULT_BRAND
+} from "./chunk-ENKHKKTS.js";
+import {
+  VERSION
+} from "./chunk-WGT6VR2C.js";
 
 // src/mcp-bin.ts
+var flag = process.argv[2];
+if (flag === "--help" || flag === "-h") {
+  console.log(`${DEFAULT_BRAND.name} ${VERSION}
+Usage: ${DEFAULT_BRAND.command}-mcp
+Starts the MCP server on stdio.`);
+  process.exit(0);
+}
+if (flag === "--version" || flag === "-V") {
+  console.log(VERSION);
+  process.exit(0);
+}
 startMcp().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);

package/dist/mcp.js

@@ -1,9 +1,9 @@
 import {
   createMcpServer,
   startMcp
-} from "./chunk-USTEVUWE.js";
-import "./chunk-P7R4J6SZ.js";
-import "./chunk-E72J53UI.js";
+} from "./chunk-QLQX3SPS.js";
+import "./chunk-ENKHKKTS.js";
+import "./chunk-WGT6VR2C.js";
 export {
   createMcpServer,
   startMcp

package/dist/worker.d.ts

@@ -1,8 +1,19 @@
+import { Auth } from 'agentic-identity';
+
 interface WorkerEnv {
     PACK_NAME?: string;
+    /**
+     * Secret. A JSON object of bearer token to `kind:name` (see `createTokenAuth`).
+     * Cloudflare bindings hold strings, so the Worker builds its Auth from this.
+     * Without it, protected routes answer 503.
+     */
+    AUTH_TOKENS?: string;
+    /** Test seam: an Auth port that replaces `AUTH_TOKENS`. A Cloudflare binding cannot hold an object. */
+    AUTH?: Auth;
 }
+declare const SUMMARIZE_SCOPE = "text:read";
 declare const _default: {
     fetch(request: Request, env: WorkerEnv): Promise<Response>;
 };
 
-export { type WorkerEnv, _default as default };
+export { SUMMARIZE_SCOPE, type WorkerEnv, _default as default };

package/dist/worker.js

@@ -1,9 +1,73 @@
 import {
   VERSION,
   summarizeText
-} from "./chunk-E72J53UI.js";
+} from "./chunk-WGT6VR2C.js";
 
 // src/worker.ts
+import { requirePrincipal } from "agentic-identity/http";
+
+// src/auth.ts
+import { isScope, parsePrincipal } from "agentic-identity";
+var MIN_TOKEN_BYTES = 32;
+var TOKEN_SHAPE = /^[A-Za-z0-9_-]{1,512}$/;
+var DEFAULT_SCOPES = ["text:read"];
+var warned = /* @__PURE__ */ new Set();
+function refuse(reason) {
+  if (!warned.has(reason)) {
+    warned.add(reason);
+    console.error(`AUTH_TOKENS is refused: ${reason}`);
+  }
+}
+function same(a, b) {
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+function contextOf(entry) {
+  const object = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : void 0;
+  const who = typeof entry === "string" ? entry : object?.as;
+  const cut = typeof who === "string" ? who.indexOf(":") : -1;
+  if (typeof who !== "string" || cut < 1 || cut === who.length - 1) return void 0;
+  const given = object?.scopes;
+  if (given !== void 0 && !(Array.isArray(given) && given.every(isScope))) return void 0;
+  try {
+    const { kind, id } = parsePrincipal({ kind: who.slice(0, cut), id: who.slice(cut + 1) });
+    return { principalId: id, kind, chain: [{ id, kind }], scopes: given ?? [...DEFAULT_SCOPES] };
+  } catch {
+    return void 0;
+  }
+}
+function createTokenAuth(raw) {
+  let table;
+  try {
+    const parsed = JSON.parse(raw ?? "");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not a JSON object");
+    table = /* @__PURE__ */ new Map();
+    for (const [token, entry] of Object.entries(parsed)) {
+      if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) throw new Error(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+      if (!TOKEN_SHAPE.test(token)) throw new Error("a token holds a character outside A-Z a-z 0-9 _ - or is over 512 bytes");
+      const context = contextOf(entry);
+      if (!context) throw new Error("an entry is not a valid kind:name or { as, scopes }");
+      table.set(token, context);
+    }
+  } catch (error) {
+    table = void 0;
+    refuse(error instanceof SyntaxError ? "not valid JSON" : error.message);
+  }
+  const known = table;
+  return {
+    async authenticate(request) {
+      const bearer = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+      if (bearer === void 0 || !known) return null;
+      let found = null;
+      for (const [token, context] of known) if (same(token, bearer)) found = context;
+      return found;
+    }
+  };
+}
+
+// src/worker.ts
+var SUMMARIZE_SCOPE = "text:read";
 function json(value, status = 200) {
   return new Response(JSON.stringify(value), {
     status,
@@ -16,7 +80,15 @@ var worker_default = {
     if (request.method === "GET" && url.pathname === "/health") {
       return json({ ok: true, pack: env.PACK_NAME ?? "agentic-pack", version: VERSION });
     }
-    if (request.method === "POST" && url.pathname === "/summarize") {
+    if (request.method === "POST" && url.pathname === "/api/v1/summarize") {
+      if (!env.AUTH && !env.AUTH_TOKENS) {
+        return json({ error: "auth is not configured" }, 503);
+      }
+      const auth = env.AUTH ?? createTokenAuth(env.AUTH_TOKENS);
+      const principal = await requirePrincipal(request, auth, { scope: SUMMARIZE_SCOPE });
+      if (principal instanceof Response) {
+        return principal;
+      }
       let body;
       try {
         body = await request.json();
@@ -36,5 +108,6 @@ var worker_default = {
   }
 };
 export {
+  SUMMARIZE_SCOPE,
   worker_default as default
 };

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "agentic-scaffold",
-  "version": "0.1.1",
-  "description": "Canonical scaffold for a CLI plus library plus MCP server pack.",
+  "version": "0.1.3",
+  "description": "TypeScript scaffold for a Node.js library, CLI, and MCP server with Zod schemas, text statistics, routing adapters, and dispatch guards.",
   "keywords": [
+    "typescript",
+    "Node.js",
     "cli",
     "mcp",
+    "Model Context Protocol",
+    "Zod",
     "scaffold",
     "starter",
-    "typescript"
+    "sdk",
+    "text-statistics",
+    "http",
+    "dispatch",
+    "guards"
   ],
   "license": "MIT",
   "author": "Pooria Arab",
@@ -21,7 +29,8 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -43,11 +52,13 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "ci:local": "WRANGLER_SEND_METRICS=false npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.25.0"
+    "agentic-identity": "^0.7.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",