agentic-scaffold 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# 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.4 - 2026-10-29
+
+### Fixed
+
+- `agentic-scaffold-mcp mcp --help`, `-h`, `--version` and `-V` print and exit 0 without starting the MCP server. The bin read only its first argument, so the `mcp` word started the server and it waited on stdin.
+- The `agentic-scaffold-mcp` usage line names the real bin. It said `agentic-pack-mcp`.
+
+### Added
+
+- Tests run the built mcp bin with the `mcp` forms of these flags and check the usage names `agentic-scaffold-mcp`.
+
+## 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

@@ -40,10 +40,25 @@ console.log(getCostReport()); // { entries: [], dispatches: 0, units: 0 }
 - **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` and `POST /summarize`; users deploy it themselves.
+- **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.
 
 Start MCP with `npx agentic-scaffold mcp`. Preview routing with `npx agentic-scaffold dispatch --text hello --dry-run`.
 
+## Migration: Worker auth
+
+`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.
+
+## Smoke test of the published packages
+
+`scripts/npm-smoke.mjs` installs each published suite package from npm in a clean temp dir. It runs the CLI and MCP `--help` and `--version`, and imports the main export and the SDK client in Node 22. It prints a pass/fail table and exits 1 on any failure.
+
+```sh
+node scripts/npm-smoke.mjs                      # all packages
+node scripts/npm-smoke.mjs agentic-link         # one package
+```
+
+The `npm-smoke` workflow runs it every day and on demand. The table goes to the job summary.
+
 ## Limits
 
 This starter has zero vendor-specific integrations. Local dispatch creates a receipt without external delivery.
@@ -64,10 +79,11 @@ node dist/cli.js summary --text "hello world hello"
 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`.
+The MCP bin's usage line in `src/mcp-bin.ts` names `agentic-scaffold-mcp` as text, so rename it there too.
 Set the MCP manifest version and repository ID before publishing your own package.
 
 The repository includes a shared core contract and a publish workflow. Inspect that workflow before adopting its release process.
-Version 0.1.1 is an early starter release; interfaces can change.
+Version 0.1.4 is an early starter release; interfaces can change. See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

package/dist/{chunk-USJ2R2T2.js → chunk-END2G5DQ.js}

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

package/dist/{chunk-QWFNPAA4.js → chunk-QERRFPOW.js}

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

package/dist/{chunk-FYTHYRXT.js → chunk-RIM2G6BQ.js}

@@ -1,6 +1,6 @@
 import {
   DEFAULT_BRAND
-} from "./chunk-QWFNPAA4.js";
+} from "./chunk-QERRFPOW.js";
 import {
   GuardError,
   LocalRouterAdapter,
@@ -9,7 +9,7 @@ import {
   dispatchText,
   getCostReport,
   summarizeText
-} from "./chunk-USJ2R2T2.js";
+} from "./chunk-END2G5DQ.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   DEFAULT_BRAND
-} from "./chunk-QWFNPAA4.js";
+} from "./chunk-QERRFPOW.js";
 import {
   GuardError,
   LocalRouterAdapter,
@@ -10,7 +10,7 @@ import {
   dispatchText,
   getCostReport,
   summarizeText
-} from "./chunk-USJ2R2T2.js";
+} from "./chunk-END2G5DQ.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-QWFNPAA4.js";
+} from "./chunk-QERRFPOW.js";
 import {
   GuardError,
   HttpRouterAdapter,
@@ -16,7 +16,7 @@ import {
   recordCost,
   resetCosts,
   summarizeText
-} from "./chunk-USJ2R2T2.js";
+} from "./chunk-END2G5DQ.js";
 export {
   DEFAULT_BRAND,
   GuardError,

package/dist/mcp-bin.js

@@ -1,11 +1,28 @@
 #!/usr/bin/env node
 import {
   startMcp
-} from "./chunk-FYTHYRXT.js";
-import "./chunk-QWFNPAA4.js";
-import "./chunk-USJ2R2T2.js";
+} from "./chunk-RIM2G6BQ.js";
+import {
+  DEFAULT_BRAND
+} from "./chunk-QERRFPOW.js";
+import {
+  VERSION
+} from "./chunk-END2G5DQ.js";
 
 // src/mcp-bin.ts
+var argv = process.argv.slice(2);
+var args = argv[0] === "mcp" ? argv.slice(1) : argv;
+var flag = args[0];
+if (flag === "--help" || flag === "-h") {
+  console.log(`${DEFAULT_BRAND.name} ${VERSION}
+Usage: agentic-scaffold-mcp [mcp] [--help | --version]
+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-FYTHYRXT.js";
-import "./chunk-QWFNPAA4.js";
-import "./chunk-USJ2R2T2.js";
+} from "./chunk-RIM2G6BQ.js";
+import "./chunk-QERRFPOW.js";
+import "./chunk-END2G5DQ.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-USJ2R2T2.js";
+} from "./chunk-END2G5DQ.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,6 +1,6 @@
 {
   "name": "agentic-scaffold",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TypeScript scaffold for a Node.js library, CLI, and MCP server with Zod schemas, text statistics, routing adapters, and dispatch guards.",
   "keywords": [
     "typescript",
@@ -29,7 +29,8 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,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",