instar 1.2.5 → 1.2.6

package/dist/server/CapabilityIndex.d.ts

@@ -0,0 +1,68 @@
+/**
+ * CapabilityIndex — single source of truth for the /capabilities self-discovery
+ * surface AND the discoverability lint that PR #290 introduced.
+ *
+ * Before this module: /capabilities was a hand-curated 440-line object literal
+ * in routes.ts, and the lint test in tests/unit/capabilities-discoverability.test.ts
+ * kept a parallel hand-written INTERNAL_ALLOWLIST. Two manual surfaces had to
+ * stay in sync for the discoverability promise to hold; nothing structurally
+ * enforced that sync. Echo's case study (topic 11141, 2026-05-21) called out
+ * the third manual edit point as the next obvious risk.
+ *
+ * After this module: /capabilities iterates CAPABILITY_INDEX and the lint
+ * reads the same array. Adding a new top-level route prefix to routes.ts
+ * fails CI until the author either adds an entry to CAPABILITY_INDEX (the
+ * "this is agent-facing, surface it" choice) or adds the prefix to
+ * INTERNAL_PREFIXES (the "this is operator-only, skip discovery" choice).
+ * The lint test no longer carries policy in test code — it just enforces the
+ * invariant that every prefix has been classified.
+ *
+ * Each entry has a `build(input)` function that produces the block to merge
+ * into the /capabilities response. Builders are pure (no I/O beyond what
+ * ctx already exposes) so /capabilities stays cheap to call on every probe.
+ *
+ * Spec: docs/specs/capabilities-introspection.md (PR #N — follow-up #2 of two).
+ */
+import type { SecretDrop } from './SecretDrop.js';
+import type { RouteContext } from './routes.js';
+/** Inputs every capability builder receives. Pure data — no closures. */
+export interface CapabilityBuildInput {
+    ctx: RouteContext;
+    /** Names of files under .claude/scripts/ — already enumerated by the handler. */
+    scripts: string[];
+    /** The SecretDrop instance — required for the `secrets` block's pending count. */
+    secretDrop: SecretDrop;
+}
+/** A single capability surfaced in the /capabilities response. */
+export interface CapabilityEntry {
+    /** JSON key under which this capability appears in the response body. */
+    readonly key: string;
+    /** Top-level route prefixes this capability owns. Drives the lint. */
+    readonly prefixes: readonly string[];
+    /** Human-friendly one-line description (for docs + telemetry). */
+    readonly description: string;
+    /** Produce the block to merge into the response. */
+    readonly build: (input: CapabilityBuildInput) => unknown;
+}
+export declare const CAPABILITY_INDEX: readonly CapabilityEntry[];
+/**
+ * Top-level route prefixes that are intentionally invisible to agents in
+ * the /capabilities response. Each entry is a deliberate "skip" with a
+ * one-line reason. The discoverability lint verifies that every prefix in
+ * routes.ts is either claimed by a CAPABILITY_INDEX entry OR allowlisted
+ * here — never both, never neither.
+ */
+export declare const INTERNAL_PREFIXES: ReadonlyArray<{
+    prefix: string;
+    reason: string;
+}>;
+/**
+ * Map every top-level route prefix to its CapabilityIndex key (for entries
+ * that claim prefixes). Lint uses this to verify routes.ts has full coverage.
+ */
+export declare function buildPrefixToKeyMap(): Map<string, string>;
+/** Set of all prefixes that should NOT appear in /capabilities. */
+export declare function buildInternalPrefixSet(): Set<string>;
+/** Iterate the index and produce the full capability-block object. */
+export declare function buildAllCapabilityBlocks(input: CapabilityBuildInput): Record<string, unknown>;
+//# sourceMappingURL=CapabilityIndex.d.ts.map

package/dist/server/CapabilityIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityIndex.d.ts","sourceRoot":"","sources":["../../src/server/CapabilityIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,YAAY,CAAC;IAClB,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,OAAO,CAAC;CAC1D;AAID,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAgkBtD,CAAC;AAsCF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA8C/E,CAAC;AAIF;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAUzD;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,IAAI,GAAG,CAAC,MAAM,CAAC,CAEpD;AAED,sEAAsE;AACtE,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}