@intentic/sandbox-contract 1.235.0 → 1.236.0

package/src/chores/index.ts

@@ -8,6 +8,7 @@ export { updateBrief } from "./extension-update.js";
 export type { UpdateBrief } from "./extension-update.js";
 export { PROBES, probeSpec } from "./probes.js";
 export type { ProbeSpec } from "./probes.js";
+export { WORKSPACE_ROOT_EXCLUDE_ENV } from "./workspace-scope.js";
 export { componentStem, frameworksOf, IDIOM_RULES, idiomRule, normalizePath, UI_FRAMEWORKS, usesTailwind } from "./stack.js";
 export type { IdiomRule, UiFramework } from "./stack.js";
 export { assessChore, assessReport, ledgerKey, unseenVerdicts } from "./verdict.js";

package/src/chores/probes.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "vitest";
+import { choreById } from "./chores.js";
 import { probeSpec } from "./probes.js";
 import { IDIOM_RULES } from "./stack.js";
+import { WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG, WORKSPACE_ROOT_RG_EXCLUDE_ARG } from "./workspace-scope.js";
 
 /* The parsers are the part of this library that faces someone else's output, so they are tested the way that
  * output actually arrives: real shapes, then the shapes that have historically broken things, a tool that
@@ -143,6 +145,11 @@ describe(`knip`, () => {
 });
 
 describe(`jscpd`, () => {
+    test(`the root-scoped command carries the reference-shelf prune argument`, () => {
+        expect(probeSpec(`jscpd`).command).toContain(WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG);
+        expect(choreById(`duplication`)?.automation?.guard).toContain(WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG);
+    });
+
     test(`takes the percentage of scanned lines and the biggest clones, longest first`, () => {
         const facts = parse(
             `jscpd`,
@@ -322,6 +329,11 @@ describe(`ui`, () => {
 describe(`the sweep's composed command`, () => {
     const stages = (): string[] => probeSpec(`ui`).command.split(`; `);
 
+    test(`both ripgrep entry points carry the root-scoped prune argument`, () => {
+        expect(probeSpec(`ui`).available).toContain(WORKSPACE_ROOT_RG_EXCLUDE_ARG);
+        expect(probeSpec(`ui`).command.split(WORKSPACE_ROOT_RG_EXCLUDE_ARG)).toHaveLength(3 + IDIOM_RULES.length);
+    });
+
     /* Given no path, ripgrep searches STDIN whenever stdin is not a TTY, which is exactly how a probe is spawned.
      * The sweep exited 0, printed its marker and matched nothing, in every repository, forever, which the marker
      * line cannot catch because the sweep really did run. It reproduces from a child process and never from an

package/src/chores/probes.ts

@@ -10,6 +10,7 @@ import {
     UI_FRAMEWORKS,
     TAILWIND_PACKAGES,
 } from "./stack.js";
+import { WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG, WORKSPACE_ROOT_RG_EXCLUDE_ARG } from "./workspace-scope.js";
 
 /* THE PROBES, the measurements that cost a subprocess, declared once so the daemon that runs them and the panel
  * that explains them cannot disagree about what "outdated" meant.
@@ -348,7 +349,8 @@ const RULE_FILE_LIMIT = 500;
  * path reaches the chores no matter which tool produced it. */
 const SCAN_ROOT = `.`;
 
-const globArgs = (globs: readonly string[]): string => [...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`).join(` `);
+const globArgs = (globs: readonly string[]): string =>
+    [...[...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`), WORKSPACE_ROOT_RG_EXCLUDE_ARG].join(` `);
 
 // `path:count` from `rg --count-matches`, normalised. Split at the LAST colon: a path may contain one, a count is
 // always the digits at the end.
@@ -526,7 +528,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // `--threshold 100` so jscpd never fails the command on its own opinion of what is too much duplication,
         // that judgement is the chore's, made from the percentage, not the tool's exit code.
         command:
-            `pnpm dlx jscpd --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
+            `pnpm dlx jscpd ${WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG} --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
             `cat ${JSCPD_DIR}/jscpd-report.json 2>/dev/null`,
         parse: parseJscpd,
     },
@@ -576,7 +578,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // Any manifest in the repo declaring a UI framework or Tailwind, not just the root's, a monorepo keeps
         // React in the app package and the root manifest is a handful of build tools.
         available:
-            `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ` +
+            `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ${WORKSPACE_ROOT_RG_EXCLUDE_ARG} ` +
             `-e '[\\x22](${[...UI_FRAMEWORKS.flatMap((framework) => framework.packages), ...TAILWIND_PACKAGES].join(`|`)})[\\x22]\\s*:' . >/dev/null`,
         unavailable: `no package here declares a UI framework or Tailwind`,
         command: scanCommand(),

package/src/chores/workspace-scope.ts

@@ -0,0 +1,12 @@
+/* Maintenance probes normally run inside one discovered repository, where a `refs/` directory is ordinary
+ * project content. They also run once against the workspace root, where the same first segment is the reserved
+ * reference shelf and can hold hundreds of thousands of files. The daemon sets this variable only for that
+ * root scope; shell commands opt into the matching prune argument without baking the shelf's name into the
+ * browser-safe contract package. */
+export const WORKSPACE_ROOT_EXCLUDE_ENV = `INTENTIC_WORKSPACE_ROOT_EXCLUDE`;
+
+// Unquoted parameter expansion is intentional: when the variable is absent it contributes zero arguments;
+// when present, each expression expands to one whitespace-free CLI argument. The daemon supplies the value
+// from @intentic/workspace-ignore, never from user input.
+export const WORKSPACE_ROOT_RG_EXCLUDE_ARG = `\${${WORKSPACE_ROOT_EXCLUDE_ENV}:+--glob=!/\${${WORKSPACE_ROOT_EXCLUDE_ENV}}/**}`;
+export const WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG = `\${${WORKSPACE_ROOT_EXCLUDE_ENV}:+--ignore=\${${WORKSPACE_ROOT_EXCLUDE_ENV}}/**}`;

package/src/contracts/extensions.contract.ts

@@ -12,7 +12,7 @@ import {
     ExtensionUpdatePolicyInputSchema,
     ExtensionUpdatePreviewSchema,
     ExtensionUpdatesCheckedSchema,
-    ExtensionUsageInputSchema,
+    ExtensionUsageBatchSchema,
     WorkspaceExtensionCreatedSchema,
     WorkspaceExtensionCreateSchema,
 } from "../schemas/extension-updates.js";
@@ -80,16 +80,17 @@ export const extensionsContract = {
         .output(OkSchema),
     // The host reporting which declared routes it just let through. Written by the browser because that is where
     // the permission gate runs (apiImpl.ts), the daemon sees an extension's traffic as ordinary authenticated
-    // requests and cannot tell which extension, or which declared entry, any of it belongs to.
+    // requests and cannot tell which extension, or which declared entry, any of it belongs to. Every extension's
+    // accumulated counts ride together so the bookkeeping is one request rather than a burst of them.
     recordUsage: oc
         .route({
             method: "POST",
-            path: "/extensions/{id}/usage",
-            summary: "Record what an extension just used",
+            path: "/extensions/usage",
+            summary: "Record what extensions just used",
             description:
-                "Written by the app rather than measured by the daemon, because the permission gate runs in the browser: from the sandbox's side an extension's traffic is indistinguishable from anyone else's. This is how the record of which powers an extension actually exercises gets kept.",
+                "One batch written by the app rather than measured by the daemon, because the permission gate runs in the browser: from the sandbox's side extension traffic is indistinguishable from anyone else's. This is how the record of which powers each extension actually exercises gets kept without one reporting request per extension.",
         })
-        .input(ExtensionUsageInputSchema)
+        .input(ExtensionUsageBatchSchema)
         .output(OkSchema),
     /* Whether this extension is fit for somebody else to run, the checks answerable from its files alone. Read
      * on demand rather than carried on the list: it reads the bundle off disk per extension, and it is looked at

package/src/contracts/workspace.contract.ts

@@ -53,13 +53,14 @@ export const workspaceContract = {
         .output(WorkspaceTreeSchema),
     // Lazy-load one directory's children, the tree returns ignored dirs (node_modules, .git, …) without children,
     // and the client fetches them here on expand so a giant node_modules can't blow the tree walk's entry budget.
+    // Bounded depth is for consumers that need a small subtree as data rather than one explorer row at a time.
     children: oc
         .route({
             method: "GET",
             path: "/workspace/children",
-            summary: "One folder's contents",
+            summary: "A bounded folder listing",
             description:
-                "The entries directly inside a single folder. This is how you open a folder the full tree walk deliberately left closed, such as an installed-packages directory with a hundred thousand files in it.",
+                "The entries inside a folder as one flat list. Direct children are the default, which is how the explorer opens a folder the full tree walk left closed; callers that need a small subtree can ask for up to five levels without a request per directory.",
         })
         .input(WorkspaceChildrenQuerySchema)
         .output(WorkspaceChildrenSchema),

package/src/events.ts

@@ -495,8 +495,8 @@ const PlanCardSchema = z.object({
     kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
     requestId: z.string().describe("What to send back when you answer."),
     text: z.string().describe("The plan itself."),
-    // Present when the plan text POINTS at a document instead of being one: the model wrote the real plan to a
-    // file and summarised it here. Absent when the text already is the whole plan, which is the ordinary case.
+    // Present when the adjacent plan prose POINTS at a document instead of being one: the model wrote the real
+    // plan to a file and summarised it there. Absent when the text already is the whole plan.
     document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
 });
 const QuestionCardSchema = z.object({