@tineira/apc-conformance 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tineira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @tineira/apc-conformance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Checks an app against the Agent Pointed Context (APC) standard: live over HTTP from a terminal (`apc-conformance`), or the whole suite in your own tests with a small adapter for your page. Node 22.15+. Docs: https://apc.tineira.com/docs
+
+## A live app, from a terminal
+
+```sh
+npx @tineira/apc-conformance@next https://your.app
+npx @tineira/apc-conformance@next https://your.app --grant https://your.app/mcp/<…>/<secret> --revoked <the MCP URL of a grant you revoked> --json
+```
+
+It reads `https://your.app/.well-known/apc.json` (its shape, its origin, its profiles, its standard) and, with `--grant` (the MCP URL of an agent connected directly), talks to the grant as an agent does: `initialize`, `tools/list` (the core tools and their arguments), `get_current_view` (the view and focus in the core's format, `attention` and `then` the same in the structured result and the text), `wait_for_focus({ timeout_s: 1 })` (it times out at 1 s, or ends at once when no page is open, with a note and no `then`) and an unknown grant answering 404. With `--revoked` it checks the revoked answer (403 `{ error: "revoked", revoked_by, revoked_at }` to every method, POST, GET and DELETE).
+
+Each check prints `PASS`, `FAIL` or `SKIP`; the exit status is 1 when one failed (2 on a usage error), and `--json` prints the report as JSON. It is safe to point at any URL: https only (`--allow-http` lets `http:` through for a dev server on the hosts `localhost`, `127.0.0.1` and `[::1]` only), grant URLs on the app's origin only, no redirect followed, a size cap on every answer and a timeout on every request (`--timeout <s>`, default 15; `wait_for_focus` is cut at 5 s). A grant URL is a secret: the report never shows it, not even inside an answer that echoes it, and an invalid `--grant` is refused without being printed.
+
+What needs the person's page cannot run over HTTP, and is reported as `SKIP`: a pin riding as `attention` until it is read, `wait_for_focus` returning a pin dropped during the wait or ending when the page closes, `then` only while the page is open, presence, Revoke pressed in the page (and a call running when it is), the mobile checks and `apc_link`. Run those in process, below.
+
+## The whole suite, in your tests
+
+```ts
+import { test } from "node:test";
+import { apcConformance } from "@tineira/apc-conformance";
+
+for (const check of apcConformance({
+  name: "My app",
+  profile: "direct",
+  connect: async () => ({ mcpUrl, grantId }), // a new agent with full access, no pin yet
+  targets: [firstTarget, secondTarget], // two things the person can point at
+  probe: { tool: "list_things", args: {} }, // one of your read tools
+  page: { setOpen, showView, pin, takePresence, revoke }, // your page, as your server sees it
+})) test(check.name, check.run);
+```
+
+`runConformance(adapter)` runs them all and returns a report; `httpConformance` / `runHttpConformance` are the HTTP checks as a library. `@tineira/apc-conformance/workers` runs a Cloudflare Durable Object on Node's SQLite with fake pages, so the suite can run against a Worker with no network.
+
+Source and changelog: https://github.com/tineira/agent-pointed-context. MIT.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * `apc-conformance`: the HTTP conformance checks (`http.ts`) against a live app, from a terminal.
+ *
+ *   npx @tineira/apc-conformance@next https://pulse.example --grant https://pulse.example/mcp/<sid>/<secret>
+ *
+ * PASS, FAIL or SKIP per check; exit 1 on any FAIL, 2 on a usage error; `--json` for the report as JSON.
+ */
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { HttpConformanceUsageError, redactSecrets, runHttpConformance } from "./http.js";
+const HELP = `apc-conformance: checks a live APC app over HTTP (https://apc.tineira.com/docs)
+
+Usage:
+  apc-conformance <app-origin> [--grant <mcp-url>] [--revoked <mcp-url>] [--json] [--allow-http] [--timeout <s>]
+
+  <app-origin>        The app's origin, e.g. https://pulse.apc.tineira.com
+  --grant <mcp-url>   The MCP URL of a live agent connected directly (Direct profile). Runs the MCP checks:
+                      initialize, tools/list, get_current_view, wait_for_focus, unknown grant 404.
+  --revoked <mcp-url> The MCP URL of a grant you revoked in the app: checks the revoked answer.
+  --json              Print the report as JSON.
+  --allow-http        Allow http:, for a dev server on the host localhost, 127.0.0.1 or [::1] only (not *.localhost).
+  --timeout <s>       Seconds per request (default 15).
+  --version, --help
+
+What it reads: {origin}/.well-known/apc.json and the MCP URLs you give, on that origin only. It never follows
+a redirect, caps every answer's size and times out every request. A grant URL is a secret: the report shows it
+with its last segment replaced by <secret>.
+
+The checks that need the person's page (a pin dropped, the page opened or closed, presence, Revoke pressed, a
+phone's touch, apc_link) are reported as SKIP: run apcConformance(adapter) from @tineira/apc-conformance in the app's
+own tests for those.
+
+Exit status: 0 when nothing failed, 1 when a check failed, 2 on a usage error.`;
+function version() {
+    try {
+        return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function format(report) {
+    const lines = [`APC conformance over HTTP: ${report.origin}`];
+    if (report.app)
+        lines.push(`${report.app.name}, standard ${report.app.standard}, profiles ${report.app.profiles.join(", ")} (checks know up to ${report.checks_standard})`);
+    lines.push("");
+    for (const r of report.results) {
+        const tag = r.status === "pass" ? "PASS" : r.status === "fail" ? "FAIL" : "SKIP";
+        lines.push(`${tag}  ${r.name}${r.status === "pass" && r.ms !== undefined ? ` (${r.ms} ms)` : ""}`);
+        if (r.detail)
+            lines.push(`      ${r.detail}`);
+        if (r.note)
+            lines.push(`      note: ${r.note}`);
+    }
+    lines.push("", `${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
+    return lines.join("\n");
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                grant: { type: "string" },
+                revoked: { type: "string" },
+                json: { type: "boolean", default: false },
+                "allow-http": { type: "boolean", default: false },
+                timeout: { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${redactSecrets(message, argv.filter((a) => a.includes("://")))}\n\n${HELP}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        process.stdout.write(`${HELP}\n`);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${version()}\n`);
+        return 0;
+    }
+    if (positionals.length !== 1) {
+        process.stderr.write(`Give exactly one app origin.\n\n${HELP}\n`);
+        return 2;
+    }
+    let timeoutMs;
+    if (values.timeout !== undefined) {
+        const s = Number(values.timeout);
+        if (!Number.isFinite(s) || s <= 0 || s > 300) {
+            process.stderr.write("--timeout is a number of seconds, from more than 0 to 300\n");
+            return 2;
+        }
+        timeoutMs = Math.round(s * 1000);
+    }
+    let report;
+    try {
+        report = await runHttpConformance({
+            origin: positionals[0],
+            ...(values.grant !== undefined ? { grant: values.grant } : {}),
+            ...(values.revoked !== undefined ? { revoked: values.revoked } : {}),
+            allowHttp: values["allow-http"],
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof HttpConformanceUsageError) {
+            process.stderr.write(`${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    process.stdout.write(`${values.json ? JSON.stringify(report, null, 2) : format(report)}\n`);
+    return report.failed > 0 ? 1 : 0;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    process.stderr.write(`apc-conformance: ${redactSecrets(message, process.argv.slice(2).filter((a) => a.includes("://")))}\n`);
+    process.exitCode = 1;
+});

package/dist/http.d.ts

@@ -0,0 +1,85 @@
+export interface HttpConformanceOptions {
+    /** The app's origin, e.g. `https://pulse.example` (a trailing slash is fine; no path). */
+    origin: string;
+    /** The MCP URL of a live grant (an agent connected directly). Without it the MCP checks are skipped. */
+    grant?: string;
+    /** The MCP URL of a grant the person revoked in the app. Without it the revoked-answer check is skipped. */
+    revoked?: string;
+    /** Lets `http:` through, on a loopback host only (localhost, 127.0.0.1, [::1]): a dev server. */
+    allowHttp?: boolean;
+    /** Per request, in ms (default 15000). */
+    timeoutMs?: number;
+    /** The global fetch when left out. Called with `redirect: "manual"`; a test can route it in process. */
+    fetch?: (request: Request) => Promise<Response>;
+}
+export type HttpCheckStatus = "pass" | "fail" | "skip";
+export interface HttpCheckResult {
+    id: string;
+    name: string;
+    status: HttpCheckStatus;
+    /** Why it failed, or why it was skipped. */
+    detail?: string;
+    /** On a pass: what it could not check (e.g. a result with no structuredContent, read from its text only). */
+    note?: string;
+    ms?: number;
+}
+export interface HttpConformanceReport {
+    origin: string;
+    /** What apc.json says, when it could be read. */
+    app?: {
+        name: string;
+        standard: string;
+        profiles: string[];
+    };
+    /** The standard this version of the checks knows. */
+    checks_standard: string;
+    passed: number;
+    failed: number;
+    skipped: number;
+    results: HttpCheckResult[];
+}
+export interface HttpCheck {
+    id: string;
+    name: string;
+    /**
+     * Resolves to a reason string when the check does not apply (skipped), to `{ note }` when it passed with a
+     * caveat; throws `ConformanceError` when it fails. Messages never carry a grant's secret.
+     */
+    run(): Promise<void | string | {
+        note: string;
+    }>;
+}
+/**
+ * The checks of the suite that need the person's page (an adapter in process), not reachable over HTTP:
+ * `apcConformance(adapter)` runs them in the app's own tests.
+ */
+export declare const IN_PROCESS_ONLY: ReadonlyArray<{
+    name: string;
+    why: string;
+}>;
+/** Why a URL the person gave cannot be used; thrown before any request is sent. */
+export declare class HttpConformanceUsageError extends Error {
+}
+/**
+ * A URL the checks may call: https (or http on a loopback host with `allowHttp`), no credentials. The input is
+ * never echoed when it does not parse: a grant URL holds a secret.
+ */
+export declare function safeUrl(raw: string, what: string, allowHttp: boolean): URL;
+/** The options, checked: the origin as an origin, and every grant URL on it. Throws `HttpConformanceUsageError`. */
+export declare function checkOptions(options: HttpConformanceOptions): {
+    origin: string;
+    grant?: URL;
+    revoked?: URL;
+};
+/** A grant's MCP URL as it may be shown: the last path segment (its secret) replaced. */
+export declare function redactGrantUrl(url: string): string;
+/**
+ * Any text with every grant's secret (the last path segment of each URL in `urls`) replaced by `<secret>`,
+ * wherever it appears (in a URL, a quoted body, an echoed error), in any letter case, as sent, decoded or
+ * percent-encoded.
+ */
+export declare function redactSecrets(text: string, urls: ReadonlyArray<string | URL | undefined>): string;
+/** The HTTP checks against a live app, in order. Throws `HttpConformanceUsageError` when the options name an unsafe URL. */
+export declare function httpConformance(options: HttpConformanceOptions): HttpCheck[];
+/** Every HTTP check, one after another, then the in-process ones as skipped: the report. */
+export declare function runHttpConformance(options: HttpConformanceOptions): Promise<HttpConformanceReport>;