@zerotal/arch 1.7.5 → 1.8.1

package/src/probe/topics.ts

@@ -304,3 +304,43 @@ export async function installedPackages(root = process.cwd()): Promise<Installed
 function controllerLabel(rawName: string): string {
   return rawName.startsWith("FileRoute<") ? "file" : rawName;
 }
+
+/**
+ * The `@zerotal/*` packages this app *declares*, with their installed versions.
+ *
+ * {@link installedPackages} answers "what is on disk here", which is the right
+ * answer for a version report and the wrong one for guidance. Two things get into
+ * `node_modules/@zerotal` besides an app's own dependencies: transitive ones, and
+ * whatever an install layout decides to hoist — and layouts disagree. The same
+ * commit of one app resolved seventeen packages on a developer's machine and
+ * eleven on its server, because the server hoisted the shared ones to the
+ * workspace root instead.
+ *
+ * That is not a cosmetic difference when the list decides what an agent is told.
+ * `@zerotal/queue` arriving as a transitive dependency does not mean the app runs
+ * jobs, and a block explaining where jobs live is confidently wrong for an app
+ * that has none. It also made the generated file unstable between machines, so a
+ * check comparing it against the project could not tell drift from a difference
+ * of layout.
+ *
+ * Direct dependencies only, which is both deterministic and the honest reading of
+ * "what this app has": you import what you declare.
+ */
+export async function declaredPackages(root = process.cwd()): Promise<InstalledPackage[]> {
+  let declared: Set<string>;
+  try {
+    const manifest = (await Bun.file(`${root}/package.json`).json()) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    declared = new Set([
+      ...Object.keys(manifest.dependencies ?? {}),
+      ...Object.keys(manifest.devDependencies ?? {}),
+    ]);
+  } catch {
+    // No manifest to read — every installed package is as good a guess as any.
+    return installedPackages(root);
+  }
+
+  return (await installedPackages(root)).filter((pkg) => declared.has(pkg.name));
+}

package/src/provider/ArchProvider.ts

@@ -1,5 +1,6 @@
 import { ServiceProvider } from "@zerotal/core";
 import type { AppEnvironment, DoctorCheck } from "@zerotal/core";
+import type { ProjectShape } from "../install/shape.ts";
 import { SERVER_ENTRY_PATH } from "../install/mcpConfig.ts";
 
 /**
@@ -96,6 +97,153 @@ export class ArchProvider extends ServiceProvider {
           }
         },
       },
+      {
+        id: "arch-agents-current",
+        label: "Agent instructions",
+        run: async () => agentsFileCheck(process.cwd()),
+      },
     ];
   }
 }
+
+/**
+ * Is the generated block still true?
+ *
+ * It was a description of the framework, which changed about as often as the
+ * framework did. It is now also a description of *this project* — which packages
+ * are installed, who owns the schema, which strictness flags are on — and every
+ * one of those moves without anyone thinking about `AGENTS.md`. Add a migration
+ * directory, turn `synchronize` off, install a package, upgrade the framework:
+ * the file still reads as current and is quietly describing the app you had.
+ *
+ * That is worse than having no file. Guidance nobody wrote is obviously absent;
+ * guidance that is confidently out of date gets followed.
+ *
+ * A warning rather than a failure: a stale instruction file misleads a person or
+ * an agent, and does not stop the application working. `doctor` earns the right
+ * to gate a deploy by failing only for things that would break one.
+ *
+ * Takes its root rather than reading `process.cwd()`, so it is testable without
+ * moving the process into a fixture.
+ *
+ * @internal
+ */
+export async function agentsFileCheck(
+  root: string,
+): Promise<{ status: "ok" | "warn"; message: string; fix?: string }> {
+  const file = Bun.file(`${root}/AGENTS.md`);
+  if (!(await file.exists())) {
+    return {
+      status: "warn",
+      message:
+        "No AGENTS.md, so an agent working here has no instructions and none of the " +
+        "project-specific facts the MCP tools cannot infer.",
+      fix: "bun zt arch:install",
+    };
+  }
+
+  const [{ buildGuidelines }, { detectShape }, { declaredPackages }, markers] = await Promise.all([
+    import("../install/guidelines.ts"),
+    import("../install/shape.ts"),
+    import("../probe/topics.ts"),
+    import("../install/markers.ts"),
+  ]);
+
+  const current = _blockOf(await file.text(), markers.BLOCK_START, markers.BLOCK_END);
+  if (current === undefined) {
+    return {
+      status: "warn",
+      message:
+        "AGENTS.md has no generated block, so nothing here describes the framework or how " +
+        "this app is set up.",
+      fix: "bun zt arch:install",
+    };
+  }
+
+  const packages = (await declaredPackages(root)).map((pkg) => pkg.name);
+  const shape = await detectShape(root);
+  const expected = buildGuidelines({
+    packages,
+    serverName: await _serverName(root),
+    shape,
+  });
+
+  if (current.trim() !== expected.trim()) {
+    return {
+      status: "warn",
+      message:
+        "AGENTS.md describes a different project than this one — its packages, its setup or " +
+        "its framework version have moved since it was written.",
+      fix: "bun zt arch:update",
+    };
+  }
+
+  // Skills rot the same way and are easier to miss: nothing reads them until an
+  // agent decides one is relevant, and by then it is being followed.
+  const stale = await _staleSkills(root, packages, shape);
+  if (stale.length > 0) {
+    return {
+      status: "warn",
+      message: `AGENTS.md is current, but ${stale.length} skill file(s) are not: ${stale.join(", ")}.`,
+      fix: "bun zt arch:update",
+    };
+  }
+
+  return { status: "ok", message: "AGENTS.md and skills match this project" };
+}
+
+/** Skill files that are missing, or generated and no longer what they would be. */
+async function _staleSkills(
+  root: string,
+  packages: string[],
+  shape: ProjectShape,
+): Promise<string[]> {
+  const { selectSkills, renderSkill, skillPaths, SKILL_MARKER } =
+    await import("../install/skills.ts");
+  const { detectAgents } = await import("../install/detect.ts");
+  const { agents } = await detectAgents(root);
+
+  const stale: string[] = [];
+  for (const skill of selectSkills(packages, shape)) {
+    for (const path of skillPaths(skill.name, agents)) {
+      const file = Bun.file(`${root}/${path}`);
+      if (!(await file.exists())) {
+        stale.push(path);
+        continue;
+      }
+      const text = await file.text();
+      // A file somebody took ownership of is theirs, current or not.
+      if (!text.includes(SKILL_MARKER)) continue;
+      if (text !== renderSkill(skill, shape)) stale.push(path);
+    }
+  }
+  return stale;
+}
+
+/** The generated body, unfenced, or `undefined` when there is no block. */
+function _blockOf(text: string, start: string, end: string): string | undefined {
+  const from = text.indexOf(start);
+  const to = text.indexOf(end);
+  if (from === -1 || to === -1 || to < from) return undefined;
+  return text.slice(from + start.length, to);
+}
+
+/**
+ * The key the server is registered under, read back from `.mcp.json`.
+ *
+ * The block names it, so comparing against a guessed name would report every
+ * project that renamed its server as permanently stale. Read rather than
+ * `require`d, which would cache the first answer and miss a rename.
+ */
+async function _serverName(root: string): Promise<string> {
+  try {
+    const document = (await Bun.file(`${root}/.mcp.json`).json()) as {
+      mcpServers?: Record<string, unknown>;
+      servers?: Record<string, unknown>;
+    };
+    const names = Object.keys(document.mcpServers ?? document.servers ?? {});
+    return names[0] ?? "zerotal";
+  } catch {
+    return "zerotal";
+  }
+}