agent-cfml-check 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 ## Current status
 
-Version `0.1.0` contains the first feasibility slice. The current implementation is locally verified for:
+Version `0.2.0` extends the `0.1.1` structural profile with parameter and exception tags. The implementation checks:
 
 - paired CFML tag nesting;
 - `cfelse` and `cfelseif` ownership and ordering;
@@ -17,17 +17,39 @@ Version `0.1.0` contains the first feasibility slice. The current implementation
 - explicit-root path safety, source stability checks, input validation, output limits, nesting limits, finding limits, and time limits;
 - deterministic JSON and text CLI output.
 
-Verification at repository commit `1d5c768`:
+Current repository source also recognizes `cfparam` as a bodyless tag and checks paired `cftry`, `cfcatch`, and `cffinally` structure. These changes are not included in the published `0.1.1` artifact or existing installed snapshots. They do not validate tag attributes, exception behavior, or runtime semantics. Self-closing paired tags, including `cfcatch`, return incomplete rather than an engine-validity claim.
 
-- `npm test`: 17/17 passed;
+The current local source corrects CFScript identifiers containing `cf` being
+misclassified as markup. Ordinary variables and calls remain script text; actual
+CFML tag islands still return `incomplete` with their source position. This fix
+is included in the `0.2.0` source.
+
+Historical verification for the `0.1.1` release baseline:
+
+- `npm test`: 22/22 passed;
 - `npm run typecheck`: passed;
 - `npm pack --dry-run --json`: passed;
-- capabilities, valid-fixture, and misnested-fixture CLI checks: passed.
+- capabilities, valid-fixture, and misnested-fixture CLI checks: passed;
+- temporary packed-install CLI and library import smoke checks: passed;
+- targeted Lucee `6.2.2.91` execution probe: passed;
+- Ubuntu WSL Node `18.19.1` `npm ci`, tests, and typecheck: passed.
 
-This is not yet a published package, a complete CFML parser, or evidence of Lucee/Adobe ColdFusion compatibility. Hub lifecycle and publication status remain outside this repository's locally verified implementation evidence.
+This is not a complete CFML parser or evidence of Adobe ColdFusion compatibility. A targeted Lucee `6.2.2.91` probe and an Ubuntu WSL Node `18.19.1` run for prior source do not establish a full engine or platform matrix for `0.2.0`.
 
 ## Install and use
 
+Install the published CLI globally for Codex CLI or any terminal session:
+
+```sh
+npm install --global agent-cfml-check@latest
+agent-cfml-check capabilities --json
+agent-cfml-check check --root /path/to/repository path/to/file.cfm --json
+```
+
+The global installation exposes the `agent-cfml-check` command from any working
+directory. For a checkout, use `npm ci`, `npm run build`, and the same command
+through `node dist/cli/index.js`.
+
 ```sh
 npm install
 npm test
@@ -38,7 +60,7 @@ node dist/cli/index.js check --root . fixtures/valid.cfm --json
 node dist/cli/index.js check --root . fixtures/misnested.cfm --json
 ```
 
-The package requires Node.js `>=18.18.0`. It has no runtime npm dependencies; TypeScript and Node.js type definitions are development dependencies.
+The package requires Node.js `>=18.18.0`. It has no runtime npm dependencies; Ajv, TypeScript, and Node.js type definitions are development dependencies. The package exposes `dist/index.js` and `dist/index.d.ts` through `main`, `types`, and `exports`; temporary packed-install CLI and library import smoke checks pass.
 
 The CLI supports:
 
@@ -49,6 +71,11 @@ agent-cfml-check check --root <directory> <file> [--json] [--pretty]
 
 Check limits can be overridden with `--max-source-bytes`, `--max-nesting`, `--max-findings`, `--max-output-bytes`, and `--time-limit-ms`, subject to the hard caps reported by `capabilities`.
 
+`max_output_bytes` must be at least 512, reserving a complete failure envelope.
+CLI ceilings count actual UTF-8 stdout, including indentation and the final
+newline. If pretty output cannot fit, checking returns incomplete/exit 3 and may
+emit its failure envelope as compact JSON. Default fitting output is unchanged.
+
 The checker requires one explicit root and one `.cfm` or `.cfc` file. JSON mode emits one envelope on stdout; diagnostics stay on stderr. A completed check with structural violations still exits `0` and reports `data.verdict: "violations"`. Exit `3` means unsupported syntax, insufficient evidence, or a resource limit. Exit `4` means an explicit-root or access-policy rejection. See [SPEC.md](SPEC.md) for the complete contract.
 
 ## Safety and boundaries
@@ -67,8 +94,10 @@ The supported profile is `cfml-structure-v1`. Unknown/custom/imported tags, opti
 - `src/cli/index.ts`: CLI argument parsing and rendering;
 - `schema/`: JSON Schema for result envelopes;
 - `fixtures/`: valid and misnested examples;
-- `test/`: implementation and CLI tests;
+- `test/`: implementation, CLI, and package-surface tests;
+- `skills/agent-cfml-check/SKILL.md`: repository-local Agent usage workflow;
+- `.github/workflows/ci.yml`: Node 18/20/22 CI and CLI smoke checks;
 - `dist/`: generated package output;
 - `DESIGN.md`, `EPIC.md`, `ROADMAP.md`, `TASK.md`, `GOAL.md`, `PROGRESS.md`, `GOAL_PROMPT.md`, `CHANGELOG.md`: repository design, planning, status, and maintenance documents.
 
-`package.json` currently publishes `dist`, `README.md`, `SPEC.md`, `schema`, and `fixtures`; the design, planning, progress, goal, prompt, and changelog documents remain repository-maintainer documentation. Although `src/index.ts` contains TypeScript exports, installed-package library imports are not documented as supported until `main`/`exports` are added and tested.
+`package.json` includes `dist`, `README.md`, `SPEC.md`, `schema`, and `fixtures` in the package; the design, planning, progress, goal, prompt, changelog, and Agent Skill documents remain repository-maintainer documentation. The repository exposes the TypeScript library through `main`, `types`, and `exports`. The source package version is `0.2.0`.

package/SPEC.md

@@ -1,7 +1,7 @@
 # Agent CFML Check Specification
 
-**Status:** frozen feasibility contract for implementation baseline `1d5c768`
-**Tool version:** `0.1.0`
+**Status:** frozen feasibility contract for implementation baseline `c76b8be`, extended by release hardening
+**Tool version:** `0.2.0`
 **Profile:** `cfml-structure-v1`
 **Envelope schema:** `schema/agent-cfml-check-result-v1.schema.json`
 
@@ -22,11 +22,11 @@ agent-cfml-check check --root <directory> <file> [--json] [--pretty]
 
 `capabilities` reports the profile, operations, extensions, tag catalogue, effective default limits, and exclusions. The CLI does not accept a file, root, or check-limit override for this operation.
 
-`check` requires exactly one explicit root and one `.cfm` or `.cfc` file. `--pretty` requires `--json`. `--help` prints usage and `--version` prints `0.1.0`; neither may be combined with other options.
+`check` requires exactly one explicit root and one `.cfm` or `.cfc` file. `--pretty` requires `--json`. `--help` prints usage and `--version` prints `0.2.0`; neither may be combined with other options.
 
 ### TypeScript interface
 
-`src/index.ts` exports `capabilities`, `checkFile`, `DEFAULT_LIMITS`, `HARD_LIMITS`, `normalizeLimits`, and schema types. The source exports exist, but package metadata currently lacks `main`/`exports`; installed-package library imports are not yet a verified contract.
+`src/index.ts` exports `capabilities`, `checkFile`, `DEFAULT_LIMITS`, `HARD_LIMITS`, `normalizeLimits`, and schema types. Repository package metadata declares `main: "./dist/index.js"`, `types: "./dist/index.d.ts"`, and an import/types `exports` map. Package-surface tests and a temporary packed-install CLI/library smoke check verified the previously published `0.1.1` artifact.
 
 The TypeScript `capabilities(limitsInput)` API may receive limit overrides, while the CLI `capabilities` operation rejects them.
 
@@ -34,15 +34,17 @@ The TypeScript `capabilities(limitsInput)` API may receive limit overrides, whil
 
 ### Paired bodies
 
-`cfcomponent`, `cffunction`, `cfif`, `cfloop`, `cfoutput`, `cfquery`, `cfsavecontent`, `cfscript`, and `cfsilent` require matching closing tags and cannot be self-closing.
+`cfcatch`, `cfcomponent`, `cffinally`, `cffunction`, `cfif`, `cfloop`, `cfoutput`, `cfquery`, `cfsavecontent`, `cfscript`, `cfsilent`, and `cftry` require matching closing tags in this profile. Self-closing spellings of paired tags return incomplete; this does not assert that every CFML engine rejects them.
 
 ### Branches
 
 `cfelse` and `cfelseif` must belong to the directly open `cfif`. Only one `cfelse` is accepted, and `cfelseif` cannot follow `cfelse`.
 
+`cfcatch` and `cffinally` must belong to the directly open `cftry`. A closed `cftry` must contain at least one direct `cfcatch` or `cffinally`; multiple catches are allowed, at most one `cffinally` is allowed, and catches cannot follow it. Nested `cftry` blocks have independent handlers. The scanner does not validate catch attributes, exception types, or arbitrary text and statements between handlers. Support for these tags is a source change after the published `0.1.1` artifact.
+
 ### Bodyless tags
 
-`cfargument`, `cfinclude`, `cfqueryparam`, `cfreturn`, and `cfset` are standalone. Ordinary and self-closing spellings are accepted. Closing a bodyless tag is unsupported.
+`cfargument`, `cfinclude`, `cfparam`, `cfqueryparam`, `cfreturn`, and `cfset` are standalone. Ordinary and self-closing spellings are accepted. Closing a bodyless tag is unsupported. `cfparam` support is a source change after the published `0.1.1` artifact; it does not validate attributes or runtime semantics.
 
 Tag names are case-insensitive. Unknown, custom, imported, and unlisted tags are unsupported.
 
@@ -91,9 +93,18 @@ Check data contains the profile, source path/SHA-256/byte size/UTF-8/BOM metadat
 
 Requested limits must be positive safe integers and cannot exceed hard caps. Reaching a limit returns a fail-closed result rather than partial data.
 
+`max_output_bytes` has a minimum of 512 to reserve the compact failure envelope
+at every hard-limit combination. CLI accounting includes the selected rendering
+and final newline. An oversized result is withheld as incomplete with exit 3;
+pretty mode falls back to compact failure JSON if indentation cannot fit.
+
 ## 7. Input and safety behavior
 
-The source reader requires `.cfm` or `.cfc`, an existing root and file, realpath containment, a regular file, valid UTF-8, no NUL byte, and an effective source-size limit. It checks size and modification time before and after reading and rejects a changed snapshot. Symlink escapes are rejected.
+The source reader requires `.cfm` or `.cfc`, an existing root and file, realpath containment, a regular file, valid UTF-8, no NUL byte, and an effective source-size limit. Static symlink escapes are rejected before admission.
+
+Reading is bound to a regular-file descriptor opened with no-follow and nonblocking flags where supported. Before consuming bytes, the reader compares admitted and opened device/inode identity, mode, size and nanosecond modification/change timestamps, checks the current pathname state, and rechecks the canonical path. Observed leaf or ancestor substitutions return the existing `SOURCE_CHANGED`/incomplete/exit 3 result. The same descriptor and pathname state are checked after reading, and the descriptor is closed on success or rejection.
+
+Oversized metadata is rejected before body reads. Actual reads are bounded to the admitted size plus one byte for growth detection and cannot exceed the selected source-byte limit plus one. Over-limit growth returns `LIMIT_EXCEEDED`/incomplete/exit 3 before UTF-8 decoding. These checks reject observed mutation; they do not provide an atomic filesystem snapshot or operating-system path confinement.
 
 Known envelope error codes include `INVALID_ARGUMENT`, `INVALID_LIMIT`, `UNSUPPORTED_EXTENSION`, `ROOT_NOT_FOUND`, `FILE_NOT_FOUND`, `PATH_UNRESOLVED`, `FILE_OUTSIDE_ROOT`, `LIMIT_EXCEEDED`, `SOURCE_CHANGED`, `BINARY_INPUT`, `ENCODING_UNSUPPORTED`, `UNSUPPORTED_SYNTAX`, and `INTERNAL_ERROR`.
 
@@ -111,6 +122,6 @@ JSON mode emits one envelope on stdout; failure diagnostics are also written to
 
 ## 9. Evidence boundary
 
-The profile does not validate full CFML grammar, expression/type/runtime semantics, HTML, SQL, include expansion, directory/project context, Lucee/Adobe execution, unknown/custom/imported tags, or CFML tag islands inside `cfscript`. Package publication, Hub lifecycle, cross-platform compatibility, and installed-package library imports are also outside current verified evidence.
+The profile does not validate full CFML grammar, expression/type/runtime semantics, HTML, SQL, include expansion, directory/project context, Lucee/Adobe execution, unknown/custom/imported tags, or CFML tag islands inside `cfscript`. The prior `0.1.1` artifact was published and registry-verified. A targeted Lucee `6.2.2.91` probe and Ubuntu WSL Node `18.19.1` verification for prior source do not establish a full engine matrix for `0.2.0`.
 
-The repository tests cover CF-01 through CF-13, pure-script `.cfc` handling, and three CLI behaviors. Current local evidence is 17/17 tests, typecheck pass, package dry-run pass, and Windows CLI smoke checks. JSON Schema validation, engine comparison, non-Windows verification, and publication remain pending.
+The repository tests cover CF-01 through CF-13, pure-script `.cfc` handling, CLI behavior, package exports, and the parameter and exception tag additions. Full Lucee/Adobe engine comparison and a broader platform matrix remain unverified.

package/dist/cli/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { capabilities, checkFile } from "../core/checker.js";
+import { capabilities, checkFile, fitOutput } from "../core/checker.js";
 import { DEFAULT_LIMITS } from "../core/limits.js";
 import { ToolFailure } from "../schema/errors.js";
+import { TOOL_ID, TOOL_VERSION } from "../schema/types.js";
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 const HELP = `agent-cfml-check — deterministic, read-only structural checks for a bounded CFML subset
@@ -121,26 +122,33 @@ export function main(argv = process.argv.slice(2)) {
             return 0;
         }
         if (args.version) {
-            process.stdout.write(`${"0.1.0"}\n`);
+            process.stdout.write(`${TOOL_VERSION}\n`);
             return 0;
         }
         const result = args.operation === "capabilities"
             ? { envelope: capabilities(args.limits), exit_code: 0 }
             : checkFile({ root: args.root, file: args.file, limits: args.limits });
-        if (args.json)
-            process.stdout.write(`${JSON.stringify(result.envelope, null, args.pretty ? 2 : undefined)}\n`);
-        else
-            process.stdout.write(renderText(result.envelope));
-        if (result.envelope.status !== "ok")
-            for (const error of result.envelope.errors)
+        const serialize = (value) => args.json
+            ? `${JSON.stringify(value, null, args.pretty ? 2 : undefined)}\n`
+            : renderText(value);
+        const envelope = args.operation === "check"
+            ? fitOutput(result.envelope, result.envelope.meta.limits, serialize)
+            : result.envelope;
+        let output = serialize(envelope);
+        // A compact failure retains the complete envelope when indentation cannot fit.
+        if (args.json && Buffer.byteLength(output) > envelope.meta.limits.max_output_bytes)
+            output = `${JSON.stringify(envelope)}\n`;
+        process.stdout.write(output);
+        if (envelope.status !== "ok")
+            for (const error of envelope.errors)
                 process.stderr.write(`error: ${error.code}: ${error.message}\n`);
-        return result.exit_code;
+        return envelope.status === "incomplete" ? 3 : result.exit_code;
     }
     catch (error) {
         const failure = error instanceof ToolFailure ? error : new ToolFailure("INTERNAL_ERROR", "The CLI failed without a safe result", 1);
         const envelope = {
             schema_version: "1.0.0",
-            tool: { id: "agent-cfml-check", version: "0.1.0" },
+            tool: { id: TOOL_ID, version: TOOL_VERSION },
             status: "error",
             complete: false,
             data: null,

package/dist/core/checker.d.ts

@@ -1,4 +1,5 @@
 import type { CapabilitiesData, CheckData, CheckLimits, Envelope, CheckOptions } from "../schema/types.js";
+export declare function fitOutput<T>(envelope: Envelope<T>, limits: CheckLimits, serialize?: (value: Envelope<T>) => string): Envelope<T>;
 export declare function capabilities(limitsInput?: Partial<CheckLimits>): Envelope<CapabilitiesData>;
 export declare function checkFile(options: CheckOptions): {
     envelope: Envelope<CheckData>;

package/dist/core/checker.js

@@ -11,14 +11,12 @@ function meta(limits) {
 function emptyEnvelope(status, limits, errors) {
     return { schema_version: "1.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status, complete: false, data: null, errors, warnings: [], meta: meta(limits) };
 }
-function fitOutput(envelope, limits) {
-    const serialized = JSON.stringify(envelope);
+export function fitOutput(envelope, limits, serialize = (value) => `${JSON.stringify(value)}\n`) {
+    const serialized = serialize(envelope);
     if (Buffer.byteLength(serialized, "utf8") <= limits.max_output_bytes)
         return envelope;
     const fallback = emptyEnvelope("incomplete", limits, [{ code: "LIMIT_EXCEEDED", message: "The output limit was reached; result data was withheld" }]);
-    if (Buffer.byteLength(JSON.stringify(fallback), "utf8") <= limits.max_output_bytes)
-        return fallback;
-    return { schema_version: "1.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: "incomplete", complete: false, data: null, errors: [{ code: "LIMIT_EXCEEDED", message: "Output limit exceeded" }], warnings: [], meta: meta(limits) };
+    return fallback;
 }
 export function capabilities(limitsInput) {
     const limits = normalizeLimits(limitsInput);
@@ -82,13 +80,12 @@ export function checkFile(options) {
             ],
             findings: scanned.findings,
         };
-        return {
-            envelope: fitOutput({ schema_version: "1.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: "ok", complete: true, data, errors: [], warnings: [], meta: meta(limits) }, limits),
-            exit_code: 0,
-        };
+        const envelope = fitOutput({ schema_version: "1.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: "ok", complete: true, data, errors: [], warnings: [], meta: meta(limits) }, limits);
+        return { envelope, exit_code: envelope.status === "incomplete" ? 3 : 0 };
     }
     catch (error) {
         const failure = error instanceof ToolFailure ? error : new ToolFailure("INTERNAL_ERROR", "The checker failed without a safe result", 1);
-        return { envelope: fitOutput(emptyEnvelope(failure.exitCode === 3 ? "incomplete" : "error", limits, [{ code: failure.code, message: failure.message }]), limits), exit_code: failure.exitCode };
+        const envelope = fitOutput(emptyEnvelope(failure.exitCode === 3 ? "incomplete" : "error", limits, [{ code: failure.code, message: failure.message }]), limits);
+        return { envelope, exit_code: envelope.status === "incomplete" ? 3 : failure.exitCode };
     }
 }

package/dist/core/lexer.js

@@ -10,13 +10,18 @@ export const PAIRED_TAGS = new Set([
     "cfcomponent",
     "cffunction",
     "cfscript",
+    "cftry",
+    "cfcatch",
+    "cffinally",
 ]);
 export const BRANCH_TAGS = new Set(["cfelseif", "cfelse"]);
-export const BODYLESS_TAGS = new Set(["cfset", "cfreturn", "cfinclude", "cfargument", "cfqueryparam"]);
+export const BODYLESS_TAGS = new Set(["cfset", "cfreturn", "cfinclude", "cfargument", "cfqueryparam", "cfparam"]);
 function isNameCharacter(character) {
     return character !== undefined && /[A-Za-z0-9_:-]/u.test(character);
 }
 function startsCfTag(source, index) {
+    if (source[index] !== "<")
+        return false;
     const afterSlash = source[index + 1] === "/" ? index + 2 : index + 1;
     return source.slice(afterSlash, afterSlash + 2).toLowerCase() === "cf" && isNameCharacter(source[afterSlash + 2]);
 }
@@ -291,7 +296,22 @@ function processTag(context, token, stack, findings) {
             throw new ToolFailure("UNSUPPORTED_SYNTAX", `Paired tag "${token.name}" cannot be self-closing`, 3);
         if (stack.length >= context.max_nesting)
             throw new ToolFailure("LIMIT_EXCEEDED", "The tag nesting limit was reached; no partial success is returned", 3);
-        stack.push({ name: token.name, start: token.start, end: token.end, branch_else_seen: false });
+        if (token.name === "cfcatch" || token.name === "cffinally") {
+            const current = stack[stack.length - 1];
+            if (current?.name !== "cftry") {
+                addFinding(context, findings, finding(context, "INVALID_BRANCH", `${token.name} must belong to the directly open cftry`, token.start, token.end));
+            }
+            else {
+                if (current.try_finally_seen) {
+                    const message = token.name === "cffinally" ? "cftry cannot contain more than one cffinally" : "cfcatch cannot appear after cffinally";
+                    addFinding(context, findings, finding(context, "INVALID_BRANCH", message, token.start, token.end, current));
+                }
+                current.try_handler_seen = true;
+                if (token.name === "cffinally")
+                    current.try_finally_seen = true;
+            }
+        }
+        stack.push({ name: token.name, start: token.start, end: token.end, branch_else_seen: false, try_handler_seen: false, try_finally_seen: false });
         return;
     }
     if (token.name === "cfscript" && stack[stack.length - 1]?.name !== "cfscript") {
@@ -310,6 +330,9 @@ function processTag(context, token, stack, findings) {
         addFinding(context, findings, finding(context, "MISMATCHED_CLOSE", `Closing tag "${token.name}" does not match open "${current.name}"`, token.start, token.end, current));
         return;
     }
+    if (current.name === "cftry" && !current.try_handler_seen) {
+        addFinding(context, findings, finding(context, "INVALID_BRANCH", "cftry must contain a directly nested cfcatch or cffinally", token.start, token.end, current));
+    }
     stack.pop();
 }
 export function scanCfml(source, limits) {

package/dist/core/limits.js

@@ -28,5 +28,9 @@ export function normalizeLimits(requested) {
         }
         values[key] = value;
     }
+    // Reserve enough space for the compact failure envelope at every hard limit.
+    if (values.max_output_bytes < 512) {
+        throw new ToolFailure("INVALID_LIMIT", "max_output_bytes must be at least 512", 2);
+    }
     return values;
 }

package/dist/core/source-reader.js

@@ -1,10 +1,14 @@
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { TextDecoder } from "node:util";
 import { ToolFailure } from "../schema/errors.js";
 function escapesRoot(root, candidate) {
     const relative = path.relative(root, candidate);
-    return relative.startsWith("..") || path.isAbsolute(relative);
+    return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+function sameFileState(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 export function loadSource(options) {
     if (!/\.(?:cfm|cfc)$/iu.test(options.file)) {
@@ -32,19 +36,55 @@ export function loadSource(options) {
     if (escapesRoot(realRoot, resolvedPath)) {
         throw new ToolFailure("FILE_OUTSIDE_ROOT", "The selected file resolves outside the explicit root", 4);
     }
-    const before = statSync(resolvedPath);
+    const before = statSync(resolvedPath, { bigint: true });
     if (!before.isFile())
         throw new ToolFailure("FILE_NOT_FOUND", "The selected path is not a regular file", 2);
-    if (before.size > options.limits.max_source_bytes) {
+    if (before.size > BigInt(options.limits.max_source_bytes)) {
         throw new ToolFailure("LIMIT_EXCEEDED", `Source exceeds the ${options.limits.max_source_bytes}-byte limit`, 3);
     }
-    const bytes = readFileSync(resolvedPath);
-    const after = statSync(resolvedPath);
-    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
-        throw new ToolFailure("SOURCE_CHANGED", "The source changed while it was being read", 3);
+    let descriptor;
+    let bytes;
+    const changed = () => new ToolFailure("SOURCE_CHANGED", "The admitted source changed before or during reading", 3);
+    const exceeded = () => new ToolFailure("LIMIT_EXCEEDED", "Source exceeds the configured byte limit", 3);
+    try {
+        // Admission must describe the descriptor we read, including ancestor replacements.
+        descriptor = openSync(resolvedPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const opened = fstatSync(descriptor, { bigint: true });
+        if (!opened.isFile())
+            throw changed();
+        if (opened.size > BigInt(options.limits.max_source_bytes))
+            throw exceeded();
+        const current = lstatSync(resolvedPath, { bigint: true });
+        if (!current.isFile() || !sameFileState(before, opened) || !sameFileState(opened, current) ||
+            realpathSync(resolvedPath) !== resolvedPath)
+            throw changed();
+        const buffer = Buffer.alloc(Number(opened.size) + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const count = readSync(descriptor, buffer, length, buffer.length - length, length);
+            if (count === 0)
+                break;
+            length += count;
+            if (length > options.limits.max_source_bytes)
+                throw exceeded();
+        }
+        const after = fstatSync(descriptor, { bigint: true });
+        if (after.size > BigInt(options.limits.max_source_bytes))
+            throw exceeded();
+        if (!sameFileState(opened, after) || after.size !== BigInt(length) ||
+            !sameFileState(after, lstatSync(resolvedPath, { bigint: true })) ||
+            realpathSync(resolvedPath) !== resolvedPath)
+            throw changed();
+        bytes = buffer.subarray(0, length);
+    }
+    catch (error) {
+        if (error instanceof ToolFailure)
+            throw error;
+        throw changed();
     }
-    if (bytes.byteLength > options.limits.max_source_bytes) {
-        throw new ToolFailure("LIMIT_EXCEEDED", `Source exceeds the ${options.limits.max_source_bytes}-byte limit`, 3);
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
     }
     if (bytes.includes(0))
         throw new ToolFailure("BINARY_INPUT", "Binary or NUL-containing input is not supported", 2);

package/dist/schema/types.d.ts

@@ -1,5 +1,5 @@
 export declare const TOOL_ID: "agent-cfml-check";
-export declare const TOOL_VERSION: "0.1.0";
+export declare const TOOL_VERSION: "0.2.0";
 export declare const PROFILE_ID: "cfml-structure-v1";
 export interface Position {
     line: number;

package/dist/schema/types.js

@@ -1,3 +1,3 @@
 export const TOOL_ID = "agent-cfml-check";
-export const TOOL_VERSION = "0.1.0";
+export const TOOL_VERSION = "0.2.0";
 export const PROFILE_ID = "cfml-structure-v1";

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "agent-cfml-check",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic, read-only structural checks for a bounded CFML subset.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yapweijun1996/AI-Agent-Tools.git",
+    "directory": "packages/cfml-check"
+  },
+  "homepage": "https://github.com/yapweijun1996/AI-Agent-Tools/tree/main/packages/cfml-check#readme",
+  "bugs": {
+    "url": "https://github.com/yapweijun1996/AI-Agent-Tools/issues"
+  },
   "type": "module",
   "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "engines": {
     "node": ">=18.18.0"
   },
@@ -20,11 +37,17 @@
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "test": "npm run build && tsc -p tsconfig.test.json && node --test .test-dist/test/check.test.js .test-dist/test/cli.test.js",
+    "test": "npm run build && npm run test:prepared",
+    "test:prepared": "tsc -p tsconfig.test.json && node --test .test-dist/test/check.test.js .test-dist/test/cli.test.js .test-dist/test/package.test.js .test-dist/test/schema.test.js",
     "prepack": "npm run build"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "ajv": "^8.20.0",
     "typescript": "^5.7.0"
   }
 }

package/schema/agent-cfml-check-result-v1.schema.json

@@ -118,7 +118,7 @@
         "max_source_bytes": { "type": "integer", "minimum": 1 },
         "max_nesting": { "type": "integer", "minimum": 1 },
         "max_findings": { "type": "integer", "minimum": 1 },
-        "max_output_bytes": { "type": "integer", "minimum": 1 },
+        "max_output_bytes": { "type": "integer", "minimum": 512 },
         "time_limit_ms": { "type": "integer", "minimum": 1 }
       },
       "additionalProperties": false