@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/README.md

@@ -0,0 +1,105 @@
+# `@platformos/platformos-mcp-supervisor`
+
+An MCP server that validates platformOS code **before it is written**. It exposes one
+tool, `validate_code`, over stdio.
+
+An agent sends the buffer it is about to write; the server lints it in the context of the
+real project and answers with the findings, the fixes the engine already computed, and a
+single gate — `must_fix_before_write` — telling the agent whether writing the file would
+produce something broken.
+
+## Running it
+
+```bash
+platformos-mcp-supervisor --project /path/to/project
+```
+
+The project root may also come from `PLATFORMOS_PROJECT_DIR`. The process speaks MCP over
+stdio and logs to **stderr only** — stdout is the protocol.
+
+## The one tool
+
+`validate_code` takes either a single buffer or a changeset:
+
+```jsonc
+{ "file_path": "app/views/pages/index.liquid", "content": "…" }
+// or
+{ "files": [ { "file_path": "…", "content": "…" }, … ] }
+```
+
+**Send a coordinated edit as one call.** Buffers in one request are overlaid on the
+project together, so a partial being created alongside its caller resolves. Sent one at a
+time, that same edit is reported broken.
+
+The answer carries `status`, `must_fix_before_write`, the findings split into
+`errors` / `warnings` / `infos`, the cross-file `impact` of the edit, and — when findings
+were withheld to bound the response — `truncated`. `status: not_applicable` means the file
+was **not checked**, which is neither approval nor refusal; `not_applicable_reason` says
+why. See `src/result/types.ts` for the full contract and
+`src/transport/instructions.ts` for what the server tells an agent about reading it.
+
+## Request flow
+
+```
+input { file_path, content } | { files: [...] }
+  → validate/  decline what needs no lint (outside root, wrong type, too big)   pure
+  → lint/      ONE lintBuffers pass, every buffer overlaid at once               I/O
+               → diagnostics + the engine's fixes/suggestions + the buffer's AST
+  → enrich/    each check's documentation URL · docset signature where it helps  pure
+  → result/    status · must_fix_before_write · next_step · impact               pure
+  → response budget, applied LAST to finished results                            pure
+  → ValidateCodeResult
+```
+
+Impact reports one thing: **what your change breaks in files you are not editing**. It finds
+the edited file's dependants through `platformos-graph`, lints them twice — once with your
+changeset applied, once without — and reports only the findings the change INTRODUCED. Those
+findings are the check engine's own, so they arrive with the same message, severity,
+documentation link and fixes as any other diagnostic; nothing about "what is broken" is
+re-derived here.
+
+The project READ overlaps the primary lint, but the two impact lint passes cannot: they share
+check-node's process-wide `App`, which has no lock. So the primary lint runs first and is
+never delayed by, or lost to, impact.
+
+Two bounds keep it affordable, both measured and both reported when hit — `IMPACT_DEADLINE_MS`
+cannot bound this work, since a lint is synchronous CPU and no timer preempts it:
+`MAX_CANDIDATE_BYTES` caps the text discovery will parse, and `MAX_DEPENDANTS_LINTED` caps how
+many dependants get linted. Start the server with `--no-impact` (or
+`POS_SUPERVISOR_NO_IMPACT=1`) to switch the whole stage off; results then carry
+`impact.status: "disabled"`.
+
+It never answers "who depends on this file": `{% render var %}` names its target at runtime,
+so that question has no sound static answer and no count is published in place of one.
+
+## What this package is not
+
+It is a **leaf consumer** of the linting engine, and deliberately thin:
+
+- **It detects nothing.** Every check lives in `platformos-check-common`, where the CLI,
+  the editors and the browser build all get it too.
+- **It authors no fixes.** `Offense.fix` / `suggest` are the engine's; this package only
+  materialises them into edits against the buffer they were computed for.
+- **It ships no documentation.** What it says about a filter, tag or object is read from
+  `filters.json` / `tags.json` / `objects.json`; what it says about a check comes from that
+  check's `meta.docs`. There is no `data/` directory and a guard fails the build if one
+  appears. A gap in the docset is fixed upstream, in
+  [platformos-documentation](https://documentation.platformos.com), never patched here.
+- **It never speaks the LSP protocol.** Linting is a direct library call. (Pure helpers
+  from the language-server package — the docset markdown renderer — are allowed under an
+  allowlist; the protocol, a server and a transport are not.)
+
+These are enforced, not aspirational: `test/guards/architecture-invariants.spec.ts` fails
+the build on each. [`ARCHITECTURE.md`](./ARCHITECTURE.md) states them in full and explains
+why each exists.
+
+## Development
+
+```bash
+yarn workspace @platformos/platformos-mcp-supervisor build       # tsc -b
+yarn workspace @platformos/platformos-mcp-supervisor type-check
+yarn vitest run packages/platformos-mcp-supervisor               # unit + integration
+```
+
+The integration suite builds the package and drives the **real stdio bin** with the
+official MCP SDK client, so the transport and the JSON envelope are covered end to end.

package/dist/adapter-input.d.ts

@@ -0,0 +1,113 @@
+import type { Declined } from './result/types.js';
+export interface AdapterInput {
+    /** Absolute project root the buffer is validated against. */
+    projectDir: string;
+    /** File under edit — absolute, or relative to `projectDir`. */
+    filePath: string;
+    /** In-memory buffer contents. */
+    content: string;
+}
+/**
+ * Resolve the file under edit to an absolute path: returned as-is when already absolute,
+ * else joined onto the project root.
+ *
+ * Both branches normalize `.`/`..` segments — `join` directly, and
+ * {@link fileApplicability}'s `relative` by resolving its arguments — so a traversal
+ * cannot survive the containment check by hiding inside an unnormalized string.
+ */
+export declare function toAbsoluteFilePath(projectDir: string, filePath: string): string;
+/** Whether `validate_code` has anything to say about a file — and if not, why. */
+export type FileApplicability = {
+    applicable: true;
+} | ({
+    applicable: false;
+} & Declined);
+/**
+ * Decide whether the buffer is a file this server can validate.
+ *
+ * A declined file gets its own terminal status (`not_applicable`) rather than an `ok` or an
+ * `error`: the only honest answer is "not mine to judge", which neither blocks nor approves
+ * the write. Without this gate every path is linted, and since check-common's
+ * `toSourceCode` types an unrecognized extension as JSON, an off-project file holding `{}`
+ * comes back `ok` — the false approval this status exists to prevent.
+ *
+ * THREE INDEPENDENT RULES, in order:
+ *
+ * 1. CONTAINMENT. The resolved path must lie strictly inside `projectDir`. Checked on the
+ *    `relative()` result rather than by string prefix, which would accept a sibling root
+ *    whose name merely extends the project's (`/srv/app-backup` vs `/srv/app`). A leading
+ *    `..` means the path climbed out; an empty result means the path IS the root; an
+ *    absolute result means a different Windows drive. This is a correctness gate, not a
+ *    security boundary — the server only ever READS — so symlinks are not resolved.
+ *
+ * 2. NOT AN ASSET. Assets are deployed and served, never rendered.
+ *
+ * 3. SUPPORTED TYPE. Reuses platformos-common's `sourceCodeTypeOf`, so the gate cannot
+ *    drift away from what the linter would have looked at.
+ */
+export declare function fileApplicability(projectDir: string, filePath: string): FileApplicability;
+/**
+ * Largest buffer this server will validate, in bytes.
+ *
+ * MEASURED against the FULL LINT, not the parse alone — every enabled check walks the AST
+ * after it. `lintBuffer` over a real 162-file project, warm cache, runs ~61 ms/KiB, so this
+ * bound costs ~7 s isolated; further out the parser itself falls apart (~30 s at 1 MiB, a
+ * stack overflow at 2 MiB, a native V8 abort at 4 MiB). It still admits 1.7x the largest
+ * real source file found across local projects.
+ *
+ * THIS BOUND, NOT THE DEADLINE, IS THE GUARD against CPU-bound input: a deadline cannot
+ * interrupt a synchronous parse and its timer cannot even fire during one. `cost-model.ts`
+ * is an independent measurement; `cost-model.spec.ts` pins that the two agree.
+ */
+export declare const MAX_BUFFER_BYTES: number;
+/**
+ * A refusal when the buffer is too large to validate, else `undefined`.
+ *
+ * Measured in BYTES, not string length: `content.length` under-counts multi-byte content
+ * by up to 3x, admitting a buffer three times the intended cost.
+ */
+export declare function bufferTooLarge(content: string): Declined | undefined;
+/**
+ * The refusal for a file the project's config excludes from linting.
+ *
+ * Not an error and not an `ok`: `check()` skips ignored files silently, so "no offenses"
+ * for one means "never looked at", and reporting that as `ok` would approve an ignored page
+ * containing unparseable Liquid.
+ */
+export declare function ignoredByProjectConfig(relativePath: string): Declined;
+/**
+ * The refusal for a path that is not a platformOS source at all.
+ *
+ * ROUTINE, and the prose is deliberately mild: a project legitimately holds READMEs, `.jsx`
+ * components, CI config and build output. This must never advise moving the file anywhere —
+ * see {@link misplacedSource}, the opposite advice.
+ *
+ * Reached both from this server's pre-lint gate ({@link fileApplicability}) and from
+ * check-node's `not-a-platformos-file` classification. One factory, so the two cannot
+ * describe the same situation differently.
+ */
+export declare function notPlatformOSFile(relativePath: string): Declined;
+/**
+ * The refusal for an ASSET: an app file the toolchain has no parser for.
+ *
+ * The same machine-readable code as {@link notPlatformOSFile}, since an agent does not act
+ * differently on the two, but its own prose: an asset IS part of the app and is deployed,
+ * so calling `app/assets/logo.png` "not a platformOS file" would be false.
+ */
+export declare function assetNotLinted(relativePath: string): Declined;
+/**
+ * The refusal for a real platformOS source sitting where the platform will never load it.
+ *
+ * THE OPPOSITE ADVICE FROM {@link notPlatformOSFile}, which is why the two are separate
+ * codes: this file IS something the toolchain parses, but it is outside every deployed
+ * subtree, so it is dead code.
+ *
+ * IT DOES NOT BLOCK THE WRITE, and is not a `warning` either: someone may be authoring a
+ * module, generator template or fixture on purpose. `not_applicable` states the honest
+ * thing — nothing was checked — while the prose carries the warning.
+ *
+ * KNOWN OVER-BROAD FOR `.yml`: the classification behind it treats any parseable extension
+ * outside the deployed subtrees as misplaced, so a repository's CI or container config is
+ * told "likely misplaced". Narrowing it belongs in check-node, where classification happens.
+ */
+export declare function misplacedSource(relativePath: string): Declined;

package/dist/adapter-input.js

@@ -0,0 +1,210 @@
+/**
+ * Shared input for the request-path I/O adapters (`lint/`, `impact/`).
+ *
+ * Both adapters receive the identical `{ projectDir, filePath, content }` and
+ * must agree on the buffer's absolute path, so the shape, the absolute-path
+ * resolution, and the "is this file ours to judge?" decision all live here
+ * rather than being duplicated per adapter.
+ */
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { path as pathUtils } from '@platformos/platformos-check-common';
+import { APP_SOURCE_SUBTREES, getFileType, isParsedFileType, sourceCodeTypeOf, } from '@platformos/platformos-common';
+import { LINT_MS_PER_KIB } from './cost-model.js';
+/**
+ * Resolve the file under edit to an absolute path: returned as-is when already absolute,
+ * else joined onto the project root.
+ *
+ * Both branches normalize `.`/`..` segments — `join` directly, and
+ * {@link fileApplicability}'s `relative` by resolving its arguments — so a traversal
+ * cannot survive the containment check by hiding inside an unnormalized string.
+ */
+export function toAbsoluteFilePath(projectDir, filePath) {
+    return isAbsolute(filePath) ? filePath : join(projectDir, filePath);
+}
+/**
+ * Decide whether the buffer is a file this server can validate.
+ *
+ * A declined file gets its own terminal status (`not_applicable`) rather than an `ok` or an
+ * `error`: the only honest answer is "not mine to judge", which neither blocks nor approves
+ * the write. Without this gate every path is linted, and since check-common's
+ * `toSourceCode` types an unrecognized extension as JSON, an off-project file holding `{}`
+ * comes back `ok` — the false approval this status exists to prevent.
+ *
+ * THREE INDEPENDENT RULES, in order:
+ *
+ * 1. CONTAINMENT. The resolved path must lie strictly inside `projectDir`. Checked on the
+ *    `relative()` result rather than by string prefix, which would accept a sibling root
+ *    whose name merely extends the project's (`/srv/app-backup` vs `/srv/app`). A leading
+ *    `..` means the path climbed out; an empty result means the path IS the root; an
+ *    absolute result means a different Windows drive. This is a correctness gate, not a
+ *    security boundary — the server only ever READS — so symlinks are not resolved.
+ *
+ * 2. NOT AN ASSET. Assets are deployed and served, never rendered.
+ *
+ * 3. SUPPORTED TYPE. Reuses platformos-common's `sourceCodeTypeOf`, so the gate cannot
+ *    drift away from what the linter would have looked at.
+ */
+export function fileApplicability(projectDir, filePath) {
+    const absolute = toAbsoluteFilePath(projectDir, filePath);
+    const relativeToRoot = relative(projectDir, absolute);
+    if (relativeToRoot === '' ||
+        isAbsolute(relativeToRoot) ||
+        relativeToRoot.split(sep)[0] === '..') {
+        return {
+            applicable: false,
+            code: 'outside_project',
+            reason: `\`${filePath}\` resolves outside the project root (${projectDir}), so there is no ` +
+                `project context to validate it against. This server validates only files inside the ` +
+                `project it was started for. Nothing was checked — treat this as "unknown", not as approval.`,
+        };
+    }
+    const uri = pathUtils.toUri(absolute);
+    // 2. AN ASSET IS NEVER JUDGED. It is SERVED, not rendered, so there is no template in it
+    //    to check. A TYPE question, not an extension one: `app/assets/x.liquid` is an asset
+    //    the platform hands back verbatim, while `theme.css.liquid` is processed.
+    //    `platformos-common` owns the rule as `isParsedFileType`; asking IT is what keeps
+    //    this gate and the lint from disagreeing about a path.
+    const rootUri = pathUtils.toUri(projectDir);
+    const fileType = getFileType(uri, rootUri);
+    if (fileType !== undefined && !isParsedFileType(fileType)) {
+        return { applicable: false, ...assetNotLinted(displayPathOf(uri, projectDir)) };
+    }
+    // 3. SUPPORTED TYPE — extension-only, and deliberately NOT the anchored
+    //    `isSupportedSourceFile(uri, root)`: this asks "is this a type we parse at all", and
+    //    a `.liquid` in an undeployed subtree IS one. Anchoring here would answer
+    //    `unsupported_type` where check-node's classifier says `misplaced-source`, which is
+    //    what the agent needs to hear. See `NotApplicableReason`.
+    if (sourceCodeTypeOf(uri) === undefined) {
+        return { applicable: false, ...notPlatformOSFile(displayPathOf(uri, projectDir)) };
+    }
+    return { applicable: true };
+}
+/**
+ * A path as the agent should SEE it: project-relative, forward slashes on every platform.
+ *
+ * `node:path.relative` is right for the containment decision above but yields
+ * `app\notes.txt` on Windows; check-common's `relative` is URI-based and forward-slash by
+ * construction.
+ */
+function displayPathOf(uri, projectDir) {
+    return pathUtils.relative(uri, pathUtils.toUri(projectDir));
+}
+/**
+ * Largest buffer this server will validate, in bytes.
+ *
+ * MEASURED against the FULL LINT, not the parse alone — every enabled check walks the AST
+ * after it. `lintBuffer` over a real 162-file project, warm cache, runs ~61 ms/KiB, so this
+ * bound costs ~7 s isolated; further out the parser itself falls apart (~30 s at 1 MiB, a
+ * stack overflow at 2 MiB, a native V8 abort at 4 MiB). It still admits 1.7x the largest
+ * real source file found across local projects.
+ *
+ * THIS BOUND, NOT THE DEADLINE, IS THE GUARD against CPU-bound input: a deadline cannot
+ * interrupt a synchronous parse and its timer cannot even fire during one. `cost-model.ts`
+ * is an independent measurement; `cost-model.spec.ts` pins that the two agree.
+ */
+export const MAX_BUFFER_BYTES = 128 * 1024;
+/**
+ * A refusal when the buffer is too large to validate, else `undefined`.
+ *
+ * Measured in BYTES, not string length: `content.length` under-counts multi-byte content
+ * by up to 3x, admitting a buffer three times the intended cost.
+ */
+export function bufferTooLarge(content) {
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (bytes <= MAX_BUFFER_BYTES)
+        return undefined;
+    return {
+        code: 'too_large',
+        reason: `The buffer is ${Math.round(bytes / 1024)} KiB, above the ${Math.round(MAX_BUFFER_BYTES / 1024)} KiB limit this server will validate, so it was refused before parsing. ` +
+            `Liquid validation costs about ${LINT_MS_PER_KIB} ms per KiB and the parser stops ` +
+            `completing at all a few ` +
+            `MiB out, so checking this would risk hanging the server rather than answering. Nothing ` +
+            `was checked — consider splitting the file, which is almost certainly worth doing at this ` +
+            `size regardless.`,
+    };
+}
+/**
+ * The refusal for a file the project's config excludes from linting.
+ *
+ * Not an error and not an `ok`: `check()` skips ignored files silently, so "no offenses"
+ * for one means "never looked at", and reporting that as `ok` would approve an ignored page
+ * containing unparseable Liquid.
+ */
+export function ignoredByProjectConfig(relativePath) {
+    return {
+        code: 'ignored',
+        reason: `\`${relativePath}\` is excluded by the \`ignore\` list in this project's ` +
+            `\`.platformos-check.yml\`, so no check ran against it. Nothing was checked — this is not ` +
+            `a pass. Remove it from \`ignore\` if you want this file validated.`,
+    };
+}
+/** The subtrees the platform deploys from, as prose. DERIVED, never spelled out. */
+const DEPLOYED = APP_SOURCE_SUBTREES.map((subtree) => `${subtree}/`).join(', ');
+/**
+ * Where an agent can read the whole rule rather than infer it from one message. In the
+ * prose because `see_also` hangs off a diagnostic, and "the file is in the wrong place"
+ * produces none.
+ */
+const DIRECTORY_STRUCTURE = 'Directory structure: ' +
+    'https://documentation.platformos.com/developer-guide/platformos-workflow/directory-structure';
+/**
+ * The refusal for a path that is not a platformOS source at all.
+ *
+ * ROUTINE, and the prose is deliberately mild: a project legitimately holds READMEs, `.jsx`
+ * components, CI config and build output. This must never advise moving the file anywhere —
+ * see {@link misplacedSource}, the opposite advice.
+ *
+ * Reached both from this server's pre-lint gate ({@link fileApplicability}) and from
+ * check-node's `not-a-platformos-file` classification. One factory, so the two cannot
+ * describe the same situation differently.
+ */
+export function notPlatformOSFile(relativePath) {
+    return {
+        code: 'unsupported_type',
+        reason: `\`${relativePath}\` is not a platformOS source file, so there is nothing to check. ` +
+            `The platform deploys ${DEPLOYED} only. Nothing was checked — writing this file is ` +
+            `your call, not a validated pass. ${DIRECTORY_STRUCTURE}`,
+    };
+}
+/**
+ * The refusal for an ASSET: an app file the toolchain has no parser for.
+ *
+ * The same machine-readable code as {@link notPlatformOSFile}, since an agent does not act
+ * differently on the two, but its own prose: an asset IS part of the app and is deployed,
+ * so calling `app/assets/logo.png` "not a platformOS file" would be false.
+ */
+export function assetNotLinted(relativePath) {
+    return {
+        code: 'unsupported_type',
+        reason: `\`${relativePath}\` is an asset, not a source file the linter understands — it ` +
+            `checks Liquid, GraphQL and YAML — so no check ran against it. The file is still ` +
+            `deployed and served; there is simply nothing here to validate. Nothing was ` +
+            `checked, which is not the same as a pass.`,
+    };
+}
+/**
+ * The refusal for a real platformOS source sitting where the platform will never load it.
+ *
+ * THE OPPOSITE ADVICE FROM {@link notPlatformOSFile}, which is why the two are separate
+ * codes: this file IS something the toolchain parses, but it is outside every deployed
+ * subtree, so it is dead code.
+ *
+ * IT DOES NOT BLOCK THE WRITE, and is not a `warning` either: someone may be authoring a
+ * module, generator template or fixture on purpose. `not_applicable` states the honest
+ * thing — nothing was checked — while the prose carries the warning.
+ *
+ * KNOWN OVER-BROAD FOR `.yml`: the classification behind it treats any parseable extension
+ * outside the deployed subtrees as misplaced, so a repository's CI or container config is
+ * told "likely misplaced". Narrowing it belongs in check-node, where classification happens.
+ */
+export function misplacedSource(relativePath) {
+    return {
+        code: 'misplaced_source',
+        reason: `\`${relativePath}\` is a platformOS source file outside every subtree the platform ` +
+            `deploys (${DEPLOYED}). Nothing checked it, and nothing will load it either — a ` +
+            `partial, page or query here is dead code. Move it under one of those directories ` +
+            `unless it is deliberately a fixture or a build input. This is neither a pass nor a ` +
+            `block. ${DIRECTORY_STRUCTURE}`,
+    };
+}
+//# sourceMappingURL=adapter-input.js.map

package/dist/adapter-input.spec.d.ts

@@ -0,0 +1 @@
+export {};