Add files using upload-large-folder tool

mods/sec-default/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "sec-default",
+  "version": "0.1.0",
+  "description": "Security default for organizations: seated outermost, it keeps the organization's classic hooks, prompt content, settings and tool policy out of reach of the plugins a person installs, and adds no policy of its own.",
+  "author": {
+    "name": "Anthropic"
+  }
+}

mods/sec-default/hooks/hooks.json

@@ -0,0 +1,4 @@
+{
+  "description": "Security default: from the outermost seat, continues past the user tier on the organization's classic hooks, prompt content, settings and subjects, refuses a user-tier tool.register under an MCP allowlist, and restores the organization's tools in tool.list",
+  "modules": ["./register.ts"]
+}

mods/sec-default/hooks/index.ts

@@ -0,0 +1,6 @@
+export * from './past-users'
+export * from './policy'
+export * from './register.js'
+export * from './tool-register-refusal'
+
+export * as default from '.'

mods/sec-default/hooks/past-users/index.ts

@@ -0,0 +1,5 @@
+export * from './past-users.js'
+export * from './provided'
+export * from './user-reachable-tiers'
+
+export * as default from '.'

mods/sec-default/hooks/past-users/past-users.ts

@@ -0,0 +1,23 @@
+import type Provided from './provided'
+import { USER_REACHABLE_TIERS } from './user-reachable-tiers'
+
+/**
+ * What the `tool.describe`, `command.describe`, `agent.offer` and
+ * `agent.spawn` hooks do: an organization's subject continues past users.
+ *
+ * The subject is the organization's unless its pinned `e.provider.tier` is
+ * `user`, `builtin` or `core`: a policy-installed plugin (`prepend`,
+ * `append`), the managed folder, a policy MCP server, or no provider at all.
+ *
+ * @param e the event's input with its pinned `provider`
+ * @param next the hook's own continuation, handed whole
+ * @returns the result from append inward, or from every tier
+ */
+export function pastUsers<E extends Provided.Provided, R>(
+  e: E,
+  next: Provided.ProvidedNext<E, R>,
+): Promise<R> {
+  const isUsers = USER_REACHABLE_TIERS.includes(e.provider?.tier)
+
+  return isUsers ? next(e) : next.to(e, 'append')
+}

mods/sec-default/hooks/policy/create-policy-memo/create-policy-memo.ts

@@ -0,0 +1,28 @@
+import type { Settings } from 'claude-code'
+
+/**
+ * A reader of managed policy that serves one read to every caller inside a
+ * window after it, rejections included (a failed read still fails closed).
+ *
+ * @param ttlMs how long a read is served after it starts
+ * @param now the clock, for a test
+ * @returns `(read) => policy`: `read` runs when nothing fresh is held
+ */
+export function createPolicyMemo(
+  ttlMs: number,
+  now: () => number = Date.now,
+): (read: () => Promise<Settings>) => Promise<Settings> {
+  let heldAt = Number.NEGATIVE_INFINITY
+  let held: Promise<Settings> | undefined
+
+  return read => {
+    const isStale = held === undefined || now() - heldAt > ttlMs
+
+    if (isStale) {
+      heldAt = now()
+      held = read()
+    }
+
+    return held ?? read()
+  }
+}

mods/sec-default/hooks/policy/decided-by-policy.ts

@@ -0,0 +1,15 @@
+import type { Settings } from 'claude-code'
+
+/**
+ * A yes/no read off managed policy that fails closed: true (protect) when
+ * the read rejects or deciding throws.
+ *
+ * @param policy the memoized policy read (createPolicyMemo over the hook's
+ * `$.settings.read({ source: "policy" })`)
+ * @param decide the answer once the policy is read
+ * @returns what decide answers, else true
+ */
+export const decidedByPolicy = (
+  policy: Promise<Settings>,
+  decide: (policy: Settings) => boolean,
+): Promise<boolean> => policy.then(decide).catch(() => true)

mods/sec-default/hooks/policy/has-mcp-allowlist.ts

@@ -0,0 +1,11 @@
+import type { Settings } from 'claude-code'
+
+/**
+ * Whether managed policy holds an MCP allowlist (allowedMcpServers set at
+ * all, empty included): the organization decides which servers add tools.
+ *
+ * @param policy the managed settings, as `$.settings.read` answers them
+ * @returns true when allowedMcpServers is in force
+ */
+export const hasMcpAllowlist = (policy: Settings) =>
+  Array.isArray(policy.allowedMcpServers)

mods/sec-default/hooks/policy/index.ts

@@ -0,0 +1,8 @@
+export * from './create-policy-memo'
+export * from './decided-by-policy.js'
+export * from './has-mcp-allowlist.js'
+export * from './managed-tools-restored'
+export * from './policy-memo-ms.js'
+export * from './source.js'
+
+export * as default from '.'

mods/sec-default/hooks/policy/managed-tools-restored/index.ts

@@ -0,0 +1,4 @@
+export * from './is-org-tool'
+export * from './managed-tools-restored.js'
+
+export * as default from '.'

mods/sec-default/hooks/policy/managed-tools-restored/managed-tools-restored.ts

@@ -0,0 +1,33 @@
+import type { Settings, ToolInfo, ValueOrDeny } from 'claude-code'
+
+import { isOrgTool } from './is-org-tool'
+
+/**
+ * A `tool.list` answer with the managed servers' tools as the organization's
+ * tiers listed them, and every other tool as the user tier left it.
+ *
+ * A refusal from either listing, or no policy to read, leaves the
+ * organization's listing standing whole (fail closed).
+ *
+ * @param policy the managed settings, or undefined when the read failed
+ * @param real the listing past the user tier (`next.to(e, "append")`)
+ * @param seen the listing through every tier (`next(e)`)
+ * @returns the merged answer
+ */
+export function managedToolsRestored(
+  policy: Settings | undefined,
+  real: ValueOrDeny<ToolInfo[]>,
+  seen: ValueOrDeny<ToolInfo[]>,
+): ValueOrDeny<ToolInfo[]> {
+  const isWhole =
+    policy === undefined || real.value === undefined || seen.value === undefined
+
+  return isWhole
+    ? real
+    : {
+        value: [
+          ...real.value.filter(tool => isOrgTool(policy, tool.name)),
+          ...seen.value.filter(tool => !isOrgTool(policy, tool.name)),
+        ],
+      }
+}

mods/sec-default/hooks/policy/policy-memo-ms.ts

@@ -0,0 +1,7 @@
+/**
+ * How long one policy read serves the decisions after it: a burst of
+ * `$.tool.list` and `$.tool.register` calls reads once.
+ *
+ * A settings change waits this long to be seen.
+ */
+export const POLICY_MEMO_MS = 500

mods/sec-default/hooks/policy/source.ts

@@ -0,0 +1,4 @@
+/**
+ * What `$.settings.read` is asked for: the managed (policy) source alone.
+ */
+export const SOURCE = { source: 'policy' } as const

mods/sec-default/hooks/register.ts

@@ -0,0 +1,61 @@
+import type { On } from 'claude-code'
+
+import { pastUsers } from './past-users'
+import Policy from './policy'
+import { TOOL_REGISTER_REFUSAL } from './tool-register-refusal'
+
+/**
+ * The built-in's hooks, seated outermost: each keeps one control an
+ * organization has today out of reach of the plugins a person installs.
+ *
+ * Three moves: continue past the user tier (`next.to(e, "append")`), refuse
+ * a user-tier caller by name, or pass. Provenance is the event's pinned
+ * `provider`; policy is `$.settings.read`, memoized per burst; fail closed.
+ *
+ * @param on the engine's registrar
+ */
+export function register(on: On) {
+  const readPolicy = Policy.createPolicyMemo(Policy.POLICY_MEMO_MS)
+
+  on('classic.*', ($, e, next) => next.to(e, 'append'))
+
+  on('prompt.section', ($, e, next) => next.to(e, 'append'))
+  on('prompt.context', ($, e, next) => next.to(e, 'append'))
+  on('skill.prompt', ($, e, next) => next.to(e, 'append'))
+  on('attribution.text', ($, e, next) => next.to(e, 'append'))
+
+  on('settings.read', ($, e, next) => next.to(e, 'append'))
+
+  on('tool.describe', ($, e, next) => pastUsers(e, next))
+  on('command.describe', ($, e, next) => pastUsers(e, next))
+  on('agent.offer', ($, e, next) => pastUsers(e, next))
+  on('agent.spawn', ($, e, next) => pastUsers(e, next))
+
+  on('tool.register', async ($, e, next) => {
+    const isOrgs =
+      next.origin.tier === 'prepend' || next.origin.tier === 'append'
+
+    if (isOrgs) {
+      return next.to(e, 'append')
+    }
+
+    const isRefused =
+      next.origin.tier === 'user' &&
+      (await Policy.decidedByPolicy(
+        readPolicy(() => $.settings.read(Policy.SOURCE)),
+        Policy.hasMcpAllowlist,
+      ))
+
+    return isRefused ? { deny: TOOL_REGISTER_REFUSAL } : next(e)
+  })
+
+  on('tool.list', async ($, e, next) =>
+    Policy.managedToolsRestored(
+      await readPolicy(() => $.settings.read(Policy.SOURCE)).catch(
+        () => undefined,
+      ),
+      await next.to(e, 'append'),
+      await next(e),
+    ),
+  )
+}

mods/sec-default/hooks/tool-register-refusal/index.ts

@@ -0,0 +1,3 @@
+export * from './tool-register-refusal.js'
+
+export * as default from '.'

mods/sec-default/hooks/tool-register-refusal/tool-register-refusal.ts

@@ -0,0 +1,6 @@
+/**
+ * Why a plugin outside policy may not add a tool while the organization's
+ * MCP allowlist is in force: the setting, then the rule.
+ */
+export const TOOL_REGISTER_REFUSAL =
+  'allowedMcpServers (managed): plugins outside policy may not add tools'

mods/sec-default/tests/register.test.ts

@@ -0,0 +1,309 @@
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+import Hooks from '../hooks'
+import Fixtures from './fixtures'
+
+tier('prepend')
+
+describe('register', () => {
+  test(
+    'under an MCP allowlist a plugin the person installed may not add a tool',
+    {
+      plugins: [
+        Fixtures.registering('suite', 'prepend'),
+        Fixtures.registering('mine'),
+        Fixtures.registering('bundled', 'builtin'),
+      ],
+    },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.ALLOWLIST }))
+
+      const registered = Fixtures.toolsRegistered(on)
+
+      await $.session.start(Fixtures.SESSION)
+
+      expect(registered).toEqual(['suite', 'bundled'])
+    },
+  )
+
+  test(
+    'with no allowlist, a plugin the person installed adds its tool',
+    { plugins: [Fixtures.registering('mine')] },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.NO_ALLOWLIST }))
+
+      const registered = Fixtures.toolsRegistered(on)
+
+      await $.session.start(Fixtures.SESSION)
+
+      expect(registered).toEqual(['mine'])
+    },
+  )
+
+  test(
+    "an organization's registration passes over a refusing user plugin",
+    {
+      plugins: [
+        Fixtures.registering('suite', 'prepend'),
+        Fixtures.denying,
+        Fixtures.registering('bundled', 'builtin'),
+      ],
+    },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.MANAGED_POLICY }))
+
+      const registered = Fixtures.toolsRegistered(on)
+
+      await $.session.start(Fixtures.SESSION)
+
+      expect(
+        registered,
+        "a built-in's registration still meets the user's deny",
+      ).toEqual(['suite'])
+    },
+  )
+
+  test(
+    'a policy that cannot be read counts as one in force',
+    { plugins: [Fixtures.registering('mine')] },
+    async ($, on) => {
+      on('settings.read', () => ({ deny: 'managed settings unreadable' }))
+
+      const registered = Fixtures.toolsRegistered(on)
+
+      await $.session.start(Fixtures.SESSION)
+
+      expect(registered).toEqual([])
+    },
+  )
+
+  test(
+    'the organization tools are listed as its tiers listed them',
+    { plugins: [Fixtures.relabeling, Fixtures.listing] },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.ALLOWLIST }))
+      on('tool.list', () => ({ value: [...Fixtures.TOOLS] }))
+
+      const { text } = await $.command.run(Fixtures.TOOLS_COMMAND)
+
+      expect(text?.split('\n')).toEqual([
+        'mcp__corp__search: Searches the corp wiki.',
+        'Bash: relabeled',
+      ])
+    },
+  )
+
+  test(
+    'a server policy delivers itself counts as a tool policy, unlisted',
+    { plugins: [Fixtures.relabeling, Fixtures.listing] },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.SERVER_POLICY }))
+      on('tool.list', () => ({ value: [...Fixtures.TOOLS] }))
+
+      const { text } = await $.command.run(Fixtures.TOOLS_COMMAND)
+
+      expect(text?.split('\n')).toEqual([
+        'mcp__corp__search: Searches the corp wiki.',
+        'Bash: relabeled',
+      ])
+    },
+  )
+
+  test(
+    "with no policy to read the organization's listing stands whole",
+    { plugins: [Fixtures.relabeling, Fixtures.listing] },
+    async ($, on) => {
+      on('settings.read', () => ({ deny: 'settings unreadable' }))
+      on('tool.list', () => ({ value: [...Fixtures.TOOLS] }))
+
+      const { text } = await $.command.run(Fixtures.TOOLS_COMMAND)
+
+      expect(text?.split('\n')).toEqual([
+        'mcp__corp__search: Searches the corp wiki.',
+        'Bash: Runs a command.',
+      ])
+    },
+  )
+
+  test(
+    'a prompt section passes over the plugins the person installed',
+    { plugins: [Fixtures.dropping, Fixtures.signing] },
+    async ($, on) => {
+      on('prompt.section', ($, e) => ({ text: e.text }))
+
+      expect(await $.prompt.section(Fixtures.MEMORY)).toEqual({
+        text: 'the org says hi (signed)',
+      })
+    },
+  )
+
+  test(
+    "a user plugin's rewrite of policy is skipped for every other reader",
+    {
+      plugins: [
+        Fixtures.stripping,
+        Fixtures.reading,
+        Fixtures.registering('mine'),
+      ],
+    },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.MANAGED_POLICY }))
+
+      const registered = Fixtures.toolsRegistered(on)
+      const { text } = await $.command.run(Fixtures.POLICY_COMMAND)
+
+      await $.session.start(Fixtures.SESSION)
+
+      expect(
+        JSON.parse(text ?? 'null'),
+        "another user plugin's read sees the allowlist the stripper hides",
+      ).toEqual(Fixtures.MANAGED_POLICY)
+
+      expect(
+        registered,
+        "sec-default's own tool.register hook still reads the allowlist",
+      ).toEqual([])
+    },
+  )
+
+  test(
+    "an organization provider's subject passes over the user plugins",
+    { plugins: [Fixtures.marking] },
+    async ($, on) => {
+      Fixtures.subjectsEchoed(on)
+
+      for (const provider of Fixtures.ORG_PROVIDERS) {
+        expect(
+          await $.tool.describe(
+            Fixtures.toolDescribed('mcp__corp__search', provider),
+          ),
+        ).toEqual({ description: 'd' })
+
+        expect(
+          (
+            await $.command.describe(
+              Fixtures.commandDescribed('suite:deploy', provider),
+            )
+          ).isHidden,
+        ).toBe(false)
+
+        expect(
+          await $.agent.offer(
+            Fixtures.agentOffered('suite:reviewer', provider),
+          ),
+        ).toEqual({ isOffered: true })
+
+        expect(await $.agent.spawn(Fixtures.agentSpawned(provider))).toEqual({
+          model: 'core',
+        })
+      }
+
+      for (const provider of Fixtures.USER_REACHABLE_PROVIDERS) {
+        expect(
+          await $.tool.describe(
+            Fixtures.toolDescribed('mcp__mine__search', provider),
+          ),
+        ).toEqual({ description: 'user: d' })
+
+        expect(
+          (
+            await $.command.describe(
+              Fixtures.commandDescribed('mine:deploy', provider),
+            )
+          ).isHidden,
+        ).toBe(true)
+
+        expect(
+          await $.agent.offer(Fixtures.agentOffered('reviewer', provider)),
+        ).toEqual({ isOffered: false })
+
+        expect(await $.agent.spawn(Fixtures.agentSpawned(provider))).toEqual({
+          model: 'user',
+        })
+      }
+    },
+  )
+
+  test(
+    'an odd provider passes over the user plugins: it fails closed',
+    { plugins: [Fixtures.marking] },
+    async ($, on) => {
+      Fixtures.subjectsEchoed(on)
+
+      for (const provider of Fixtures.ODD_PROVIDERS) {
+        expect(
+          await $.tool.describe(Fixtures.toolDescribed('Bash', provider)),
+        ).toEqual({ description: 'd' })
+
+        expect(await $.agent.spawn(Fixtures.agentSpawned(provider))).toEqual({
+          model: 'core',
+        })
+      }
+    },
+  )
+
+  test(
+    'a subject decision reads no policy; a burst of listings reads once',
+    { plugins: [Fixtures.listing] },
+    async ($, on) => {
+      const reads = Fixtures.policyReads(on, Fixtures.MANAGED_POLICY)
+
+      Fixtures.subjectsEchoed(on)
+      on('tool.list', () => ({ value: [...Fixtures.TOOLS] }))
+
+      for (const provider of Fixtures.ORG_PROVIDERS) {
+        await $.tool.describe(Fixtures.toolDescribed('mcp__corp__x', provider))
+        await $.agent.spawn(Fixtures.agentSpawned(provider))
+      }
+
+      expect(reads()).toBe(0)
+
+      await Promise.all([
+        $.command.run(Fixtures.TOOLS_COMMAND),
+        $.command.run(Fixtures.TOOLS_COMMAND),
+        $.command.run(Fixtures.TOOLS_COMMAND),
+      ])
+
+      expect(reads()).toBe(1)
+    },
+  )
+
+  test(
+    'the refusal a user-tier caller reads names the allowlist',
+    {
+      plugins: [
+        {
+          name: 'asking',
+          register(on) {
+            on('command.run', { command: 'greet' }, $ =>
+              $.tool
+                .register({
+                  name: 'greet',
+                  description: 'Says hello.',
+                  inputSchema: { type: 'object' },
+                })
+                .then(
+                  () => ({ text: 'registered' }),
+                  (error: unknown) => ({ text: String(error) }),
+                ),
+            )
+          },
+        },
+      ],
+    },
+    async ($, on) => {
+      on('settings.read', () => ({ value: Fixtures.ALLOWLIST }))
+
+      const { text } = await $.command.run({
+        command: 'greet',
+        args: '',
+        origin: { kind: 'composer' },
+        presentation: Fixtures.FULLSCREEN,
+      })
+
+      expect(text).toEndWith(
+        `asking: $.tool.register: ${Hooks.TOOL_REGISTER_REFUSAL}`,
+      )
+    },
+  )
+})

mods/telemetry/hooks/entries/checked-props/checked-props.ts

@@ -0,0 +1,41 @@
+import { checkedValue } from '../checked-value'
+import { isRecord } from '../is-record'
+import type { Method } from '../method'
+import { PROP_LIMIT } from '../prop-limit'
+import { refusal } from '../refusal'
+import { TOKEN } from '../token'
+
+/**
+ * An entry's properties as they go into the row, or a refusal naming the
+ * first thing wrong: the shape, the count, then each key and value in turn.
+ *
+ * @param props what the caller passed as `props`
+ * @param method the method the properties were passed to, named in a refusal
+ * @returns the properties by key, each value checked
+ */
+export function checkedProps(
+  props: unknown,
+  method: Method,
+): Record<string, string | number | boolean> {
+  if (!isRecord(props)) {
+    throw refusal('props: an object of properties by key', method)
+  }
+
+  const entries = Object.entries(props)
+
+  if (entries.length > PROP_LIMIT) {
+    throw refusal(`props: at most ${PROP_LIMIT} properties`, method)
+  }
+
+  const checked: Record<string, string | number | boolean> = {}
+
+  for (const [key, value] of entries) {
+    if (!TOKEN.test(key)) {
+      throw refusal('props: every key is a snake_case token', method)
+    }
+
+    checked[key] = checkedValue(key, value, method)
+  }
+
+  return checked
+}

mods/telemetry/hooks/entries/checked-props/index.ts

@@ -0,0 +1,3 @@
+export * from './checked-props.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/checked-value/checked-value.ts

@@ -0,0 +1,74 @@
+import { CHOICE_TOKEN } from '../choice-token'
+import { CHOICES_LIMIT } from '../choices-limit'
+import { isRecord } from '../is-record'
+import type { Method } from '../method'
+import { refusal } from '../refusal'
+
+/**
+ * One property's value as it goes into the metadata: a finite number, a
+ * boolean, or a Choice's value chosen from its token list.
+ *
+ * A bare string is refused: free text never reaches the row.
+ *
+ * @param key the property's key, named in a refusal
+ * @param value what the caller passed under it
+ * @param method the method the property was passed to, named in a refusal
+ * @returns the value as stored: the boolean or finite number unchanged, or the
+ *          chosen member when value is a Choice
+ */
+export function checkedValue(
+  key: string,
+  value: unknown,
+  method: Method = 'log',
+): string | number | boolean {
+  if (typeof value === 'boolean') {
+    return value
+  }
+
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) {
+      return value
+    }
+
+    throw refusal(`props.${key}: a number is finite`, method)
+  }
+
+  if (typeof value === 'string') {
+    throw refusal(
+      `props.${key}: free text is refused; a string is a Choice, ` +
+        `{ value, of: [...] }`,
+      method,
+    )
+  }
+
+  if (!isRecord(value) || !Array.isArray(value.of)) {
+    throw refusal(
+      `props.${key}: a value is a finite number, a boolean, or a Choice, ` +
+        `{ value, of: [...] }`,
+      method,
+    )
+  }
+
+  const members = value.of
+  const chosen = value.value
+
+  const isTokenList =
+    members.length > 0 &&
+    members.length <= CHOICES_LIMIT &&
+    members.every(
+      member => typeof member === 'string' && CHOICE_TOKEN.test(member),
+    )
+
+  if (!isTokenList) {
+    throw refusal(
+      `props.${key}.of: a list of 1 to ${CHOICES_LIMIT} ` + `lowercase tokens`,
+      method,
+    )
+  }
+
+  if (typeof chosen !== 'string' || !members.includes(chosen)) {
+    throw refusal(`props.${key}.value: one of the members of \`of\``, method)
+  }
+
+  return chosen
+}

mods/telemetry/hooks/entries/checked-value/index.ts

@@ -0,0 +1,3 @@
+export * from './checked-value.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/choice-token/choice-token.ts

@@ -0,0 +1,8 @@
+/**
+ * The shape of a Choice member: a lowercase token of at most 64 characters,
+ * of letters, digits, `_` and `-`.
+ *
+ * Unlike a name or a key (TOKEN), it may start with a digit (a bucket such
+ * as `110_to_143`) and carry a hyphen (a kind such as `merge-base`).
+ */
+export const CHOICE_TOKEN = /^[a-z0-9][a-z0-9_-]{0,63}$/

mods/telemetry/hooks/entries/choice-token/index.ts

@@ -0,0 +1,3 @@
+export * from './choice-token.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/choices-limit/choices-limit.ts

@@ -0,0 +1,4 @@
+/**
+ * The most members a Choice's list may have.
+ */
+export const CHOICES_LIMIT = 32

mods/telemetry/hooks/entries/choices-limit/index.ts

@@ -0,0 +1,3 @@
+export * from './choices-limit.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/core-event-prefix/core-event-prefix.ts

@@ -0,0 +1,5 @@
+/**
+ * What the CLI's own event names start with: an event already so named is
+ * sent under its own name, so a built-in's port keeps its built-in's row.
+ */
+export const CORE_EVENT_PREFIX = 'tengu_'

mods/telemetry/hooks/entries/core-event-prefix/index.ts

@@ -0,0 +1,3 @@
+export * from './core-event-prefix.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/event-prefix/event-prefix.ts

@@ -0,0 +1,7 @@
+/**
+ * What an event's name starts with unless the caller named it as the CLI's
+ * own (CORE_EVENT_PREFIX): the plugin-event convention.
+ *
+ * The calling built-in's own name is already in the event it passes.
+ */
+export const EVENT_PREFIX = 'tengu_plugin_'

mods/telemetry/hooks/entries/event-prefix/index.ts

@@ -0,0 +1,3 @@
+export * from './event-prefix.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/feature-prefix/feature-prefix.ts

@@ -0,0 +1,7 @@
+/**
+ * What every feature mark's event name starts with; the kind follows.
+ *
+ * The CLI's own feature events are named so, which puts a plugin's marks in
+ * the same table as every other feature's.
+ */
+export const FEATURE_PREFIX = 'tengu_feature_'

mods/telemetry/hooks/entries/feature-prefix/index.ts

@@ -0,0 +1,3 @@
+export * from './feature-prefix.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/fields-of/fields-of.ts

@@ -0,0 +1,16 @@
+import { CORE_EVENT_PREFIX } from '../core-event-prefix'
+import { EVENT_PREFIX } from '../event-prefix'
+import type { Fields } from '../fields'
+
+/**
+ * One checked entry as its fields: an event already named as the CLI's own
+ * keeps its name, any other goes under the plugin prefix.
+ *
+ * @param event the event's name as the caller spelled it
+ * @param props the properties as checked
+ * @returns the entry's fields, the event name as sent and the props attached
+ */
+export const fieldsOf = (event: string, props: Fields['props']): Fields => ({
+  name: event.startsWith(CORE_EVENT_PREFIX) ? event : EVENT_PREFIX + event,
+  props,
+})

mods/telemetry/hooks/entries/fields-of/index.ts

@@ -0,0 +1,3 @@
+export * from './fields-of.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/fields/fields.ts

@@ -0,0 +1,8 @@
+/**
+ * One entry after the check: the event's full name and the properties as
+ * they go into the row's metadata.
+ */
+export type Fields = {
+  name: string
+  props: Readonly<Record<string, string | number | boolean>>
+}

mods/telemetry/hooks/entries/fields/index.ts

@@ -0,0 +1,3 @@
+export type * from './fields.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/is-mark-kind/index.ts

@@ -0,0 +1,3 @@
+export * from './is-mark-kind.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/is-mark-kind/is-mark-kind.ts

@@ -0,0 +1,11 @@
+import type { TelemetryMarkKind } from '../../../types'
+import { MARK_KINDS } from '../mark-kinds'
+
+/**
+ * Whether the value names one of the three mark kinds.
+ *
+ * @param value what the caller passed as `kind`
+ * @returns whether value names one of the three mark kinds
+ */
+export const isMarkKind = (value: unknown): value is TelemetryMarkKind =>
+  MARK_KINDS.some(kind => kind === value)

mods/telemetry/hooks/entries/is-record/index.ts

@@ -0,0 +1,3 @@
+export * from './is-record.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/is-record/is-record.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the value is a plain object (not null, not an array).
+ *
+ * @param value what the caller passed
+ * @returns whether the value is a plain object, not null and not an array
+ */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)

mods/telemetry/hooks/entries/mark-fields-of/index.ts

@@ -0,0 +1,3 @@
+export * from './mark-fields-of.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/mark-fields-of/mark-fields-of.ts

@@ -0,0 +1,28 @@
+import { FEATURE_PREFIX } from '../feature-prefix'
+import type { Fields } from '../fields'
+import type { Mark } from '../mark'
+
+/**
+ * One checked mark as its fields: the CLI's own feature event,
+ * `tengu_feature_<kind>` with `feature_name`, and `error_code` when given.
+ *
+ * The mark's properties merge in as the CLI's feature events merge their
+ * extras: after `feature_name` on an ok row, and beneath `feature_name`
+ * and `error_code` on a sad or bad one.
+ *
+ * @param mark the feature, how it went, why when not ok, and its checked
+ *   properties
+ * @returns the event's name and props, ready to log
+ */
+export const markFieldsOf = ({
+  kind,
+  feature,
+  reason,
+  props,
+}: Mark): Fields => ({
+  name: FEATURE_PREFIX + kind,
+  props:
+    reason === undefined
+      ? { feature_name: feature, ...props }
+      : { ...props, feature_name: feature, error_code: reason },
+})

mods/telemetry/hooks/entries/mark-kinds/index.ts

@@ -0,0 +1,3 @@
+export * from './mark-kinds.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/mark-kinds/mark-kinds.ts

@@ -0,0 +1,6 @@
+import type { TelemetryMarkKind } from '../../../types'
+
+/**
+ * The three kinds a mark may be, in the order the feature events name them.
+ */
+export const MARK_KINDS: readonly TelemetryMarkKind[] = ['ok', 'sad', 'bad']

mods/telemetry/hooks/entries/mark/index.ts

@@ -0,0 +1,3 @@
+export type * from './mark.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/mark/mark.ts

@@ -0,0 +1,13 @@
+import type { TelemetryMarkKind } from '../../../types'
+import type { Fields } from '../fields'
+
+/**
+ * One mark past every check: the feature, how it went, why when not ok,
+ * and its properties as they go into the row.
+ */
+export type Mark = {
+  kind: TelemetryMarkKind
+  feature: string
+  reason?: string
+  props: Fields['props']
+}

mods/telemetry/hooks/entries/method/index.ts

@@ -0,0 +1,3 @@
+export type * from './method.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/method/method.ts

@@ -0,0 +1,4 @@
+/**
+ * The two methods of `$.telemetry`, named in a refusal.
+ */
+export type Method = 'log' | 'mark'

mods/telemetry/hooks/entries/prop-limit/index.ts

@@ -0,0 +1,3 @@
+export * from './prop-limit.js'
+
+export * as default from '.'

mods/telemetry/hooks/entries/prop-limit/prop-limit.ts

@@ -0,0 +1,4 @@
+/**
+ * The most properties one entry may carry.
+ */
+export const PROP_LIMIT = 16

mods/telemetry/hooks/entries/refusal/index.ts

@@ -0,0 +1,3 @@
+export * from './refusal.js'
+
+export * as default from '.'