@pikku/inspector 0.12.106 → 0.12.108

package/knowledge/decisions/index.md

@@ -1,38 +0,0 @@
----
-type: overview
-title: Decisions
-description: Rules chosen in inspector, and what each one rules out
----
-
-# Decisions
-
-A rule that was chosen, and what it rules out.
-
-<!-- pikku:knowledge-index -->
-- [A channel with auth false marks its connect and disconnect handlers sessionless](a-channel-with-auth-false-marks-its-connect-and-disconnect-sessionless.md) — The inspector synthesises metadata for a channel's connect and disconnect functions and sets sessionless from the channel's auth
-- [A declared scope id never shadows a definition](a-declared-scope-id-never-shadows-a-definition.md) — A bare declareScopes id is added only when no definition already holds it, so an addon's richer scope tree is kept
-- [A workflow DSL step's virtual user is the literal name written in its options object](a-dsl-step-virtual-user-is-the-literal-name-in-its-options.md) — The DSL extractor reads a step's virtual user from a property access or string-keyed element access in the options literal, and leaves it undefined when the value is not static
-- [A feature flag's anyOf is read from the AST, and an empty anyOf is refused](a-feature-flags-anyof-is-read-from-the-ast-and-an-empty-list-is-refused.md) — add-feature-flag reads the scope names in anyOf statically, refuses a non-array or empty anyOf, and refuses a flag name containing the scope separator
-- [A string array with one computed entry reads as absent, not as its literal entries](a-non-literal-string-array-reads-as-absent.md) — stringArrayProperty returns undefined unless every element of the array is a string literal
-- [A permission whose data parameter starts with an underscore takes no data](a-permission-with-an-underscore-data-parameter-takes-no-data.md) — An underscore-prefixed data parameter marks a permission as auth-only, and pikkuAuth always has no data
-- [A provider-login virtual user is never runnable, even when declared runnable](a-provider-login-virtual-user-is-never-runnable.md) — Runnable is derived from the account, so a virtual user with a provider login cannot be driven, and an explicit runnable true does not change that
-- [A remote addon's bound credential or secret id must name a wired slot, or validation reports a critical error](a-remote-addon-bound-credential-or-secret-must-be-wired.md) — validateRemoteAddonAuth checks that a literal auth.credentialId or auth.secretId on a wireRemoteAddon names a declared credential or secret, and runs in every inspector pass
-- [A route's own auth overrides its group's, and auth false on a route makes an inline function sessionless](a-route-auth-overrides-its-groups-auth.md) — The route's auth is used when it is true or false, the group's inherited value otherwise; a resolved false sets sessionless on an inline function
-- [A route requires a session when any auth signal says so](a-route-requires-a-session-when-any-auth-signal-says-so.md) — Four places can demand a session for an HTTP route and they combine with OR; a scope gate counts as a session demand
-- [A webhook source with a verify step declares a singleton credential for its secret](a-webhook-source-with-verify-gets-a-singleton-secret-credential.md) — When a webhook source has a verify step, the inspector registers a string credential named by the source unless the author sets credential
-- [A wire with auth disabled cannot point at a pikkuFunc](a-wire-with-auth-disabled-cannot-point-at-a-pikkufunc.md) — A route or wiring with auth false that names a session-requiring pikkuFunc is reported as critical, and the function is not accepted
-- [Addons may not call wiring helpers or declare middleware or permissions](addon-contracts-cannot-wire-or-declare-handlers.md) — Addon packages are banned from transport wirings, and their define* contracts may not carry middleware or permissions
-- [An addon declaration names the secrets and credentials the app lends it](addon-declarations-name-the-secrets-and-credentials-the-app-lends-it.md) — secretGrants and credentialGrants are declared on the addon instance as lists of names the addon reads
-- [An inline wiring function is sessionless unless its helper is pikkuFunc](an-inline-wiring-function-is-sessionless-unless-built-with-pikkufunc.md) — The inspector derives sessionless for a function inlined into a wiring from the name of the helper that built it
-- [better-auth's admin plugin is refused in favour of pikkuBan](better-auth-admin-plugin-is-refused.md) — Wiring admin() in pikkuBetterAuth throws at build time, and the error names pikkuBan() as the replacement
-- [A define-screens scopes list must be string literals, or the build reports a critical error](define-screens-scopes-must-be-string-literals.md) — add-define-screens reads each screen's scopes by AST and reports ADDON_SCREENS_NOT_STATIC when the value is not an array of string literals
-- [A non-literal global grant is recorded as its source text, not dropped](inspector-records-a-non-literal-global-grant-as-source-text.md) — globalSecrets and globalCredentials on a wireAddon keep a computed value as the expression's source text
-- [Only one pikkuBetterAuth export is allowed per codebase](only-one-pikku-better-auth-export-per-codebase.md) — pikkuBetterAuth must be an exported const, and a second definition is refused with the first file named
-- [An undeclared scope and a secret service passed under another name are critical diagnostics](scope-references-and-secret-aliases-are-critical-diagnostics.md) — Post-processing reports a function that requires an undeclared scope, and a function-facing service that is a SecretService under another name
-- [Scope segments may not be wildcards or contain colons](scope-segments-may-not-be-wildcards-or-contain-colons.md) — The inspector refuses an empty scope segment, a segment containing the separator, and a literal wildcard segment
-- [Shorthand permission entries are extracted, so the audit never reads a guarded function as open](shorthand-permission-entries-are-extracted.md) — extractPermissionPikkuNames reads { canAdminOrg } shorthand entries in a permissions record as names, as the runtime does
-- [System roles must declare literal, unqualified scopes](system-roles-declare-literal-unqualified-scopes.md) — A system role needs a literal scopes array of string literals, and its name may not contain the scope separator
-- [The inspector records an agent's permissions only to aggregate the services they need, never to check access](the-inspector-records-agent-permissions-only-to-aggregate-services.md) — addAgent adds the agent's permission names to usedPermissions, and post-process reads that set only to collect each permission's services
-- [Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only](vault-secrets-reach-no-sink-and-pii-stays-out-of-logs-and-webhooks.md) — check-classified-sinks rejects revealed secrets in every listed sink and PII only in the logger, console and webhook sinks
-- [Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call](webhook-gateway-wrappers-are-sessionless-and-gateway-auth-runs-inside-the-handler.md) — The inspector and the runtime both register a webhook gateway's POST and verify routes as sessionless with auth false, so the route never demands a session and the gateway's own auth flag is applied only when the handler runs
-<!-- /pikku:knowledge-index -->

package/knowledge/decisions/inspector-records-a-non-literal-global-grant-as-source-text.md

@@ -1,20 +0,0 @@
----
-type: decision
-title: A non-literal global grant is recorded as its source text, not dropped
-description: globalSecrets and globalCredentials on a wireAddon keep a computed value as the expression's source text
-tags: [inspector, addons, grants]
----
-
-# A non-literal global grant is recorded as its source text, not dropped
-
-In `packages/inspector/src/add/add-wire-addon.ts`, the `globalSecrets` and
-`globalCredentials` properties of a `wireAddon` call are read in the same loop as the
-other options (lines 216-225). A string literal is stored as its text. Any other
-expression is stored as `prop.initializer.getText()` (lines 219-221 and 223-225).
-
-The comment at lines 217-218 gives the reason: "The grant is real at runtime whatever the
-reason evaluates to, so a non-literal is recorded as its source text rather than dropped."
-
-**What this rules out:** discarding a global grant because its value is computed. The
-inspector does not evaluate the expression, so the recorded text is what a later reader
-sees.

package/knowledge/decisions/only-one-pikku-better-auth-export-per-codebase.md

@@ -1,19 +0,0 @@
----
-type: decision
-title: Only one pikkuBetterAuth export is allowed per codebase
-description: pikkuBetterAuth must be an exported const, and a second definition is refused with the first file named
-tags: [inspector, auth, better-auth]
----
-
-# Only one pikkuBetterAuth export is allowed per codebase
-
-`addAuth` in `packages/inspector/src/add/add-auth.ts` requires `pikkuBetterAuth(...)`
-to be assigned to an exported `const` (lines 242-248). The message says the CLI has
-to import it.
-
-A second definition is refused as critical `DUPLICATE_AUTH_DEFINITION` (lines
-250-256). The message says "Only one pikkuBetterAuth(...) is allowed per codebase"
-and names both the new file and the first one.
-
-**What this rules out:** two better-auth configurations in one codebase, so the
-CLI always has a single auth definition to read.

package/knowledge/decisions/scope-references-and-secret-aliases-are-critical-diagnostics.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: An undeclared scope and a secret service passed under another name are critical diagnostics
-description: Post-processing reports a function that requires an undeclared scope, and a function-facing service that is a SecretService under another name
-tags: [inspector, scopes, secrets, post-process]
----
-
-# An undeclared scope and a secret service passed under another name are critical diagnostics
-
-Both checks run from `packages/inspector/src/inspector.ts`: `validateNoSecretAliasServices` at line
-539, and `validateScopeReferences` at line 579.
-
-`validateScopeReferences` in `packages/inspector/src/utils/post-process.ts` (lines 1671-1703) checks each
-function's scopes against the set declared with `defineScope`. A trailing `:*` is stripped before the
-lookup (line 1684). A bare `*` is reported (lines 1686-1692), and an undeclared scope is reported with
-the list of available scopes (lines 1694-1700). Both are `logger.critical` with `ErrorCode.INVALID_VALUE`.
-
-`validateNoSecretAliasServices` (lines 1484-1522) reports a function-facing service whose type is a
-`SecretService` under another name. The comment at lines 1479-1482 says a name-based rule would miss
-`pikkuServices(async ({ secrets }) => ({ cfg: secrets }))`, so the check uses the type.
-
-**What this rules out:** a function that requires a scope no `defineScope` declares, and a function
-receiving a secret service under a different name.

package/knowledge/decisions/scope-segments-may-not-be-wildcards-or-contain-colons.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: Scope segments may not be wildcards or contain colons
-description: The inspector refuses an empty scope segment, a segment containing the separator, and a literal wildcard segment
-tags: [inspector, scopes]
----
-
-# Scope segments may not be wildcards or contain colons
-
-`isValidSegment` in `packages/inspector/src/add/add-scope.ts` checks one segment at a
-time and reports each failure as critical:
-
-- an empty segment is refused (lines 21-27);
-- a segment containing `:` is refused, with the message telling the author to nest
-  with the `scopes` property instead (lines 28-35);
-- a segment equal to `*` is refused, because `*` is reserved for granting a scope
-  and its descendants (lines 36-43).
-
-`declareScopes` ids are split on `:` and every segment is checked (line 161). Nested
-`scopes` keys are checked the same way (line 77).
-
-**What this rules out:** a declared scope that is itself a wildcard, and a scope
-name that hides a second level of nesting inside one segment.

package/knowledge/decisions/shorthand-permission-entries-are-extracted.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Shorthand permission entries are extracted, so the audit never reads a guarded function as open
-description: extractPermissionPikkuNames reads { canAdminOrg } shorthand entries in a permissions record as names, as the runtime does
-tags: [inspector, permissions, audit]
----
-
-# Shorthand permission entries are extracted, so the audit never reads a guarded function as open
-
-`extractPermissionPikkuNames` in `packages/inspector/src/utils/permissions.ts` (line 15) reads a
-permissions value in two shapes. An array is walked element by element (lines 44-48). An object
-literal is walked property by property (lines 49-62).
-
-For a `PropertyAssignment` the initializer is extracted (line 53). For a
-`ShorthandPropertyAssignment`, such as `permissions: { canAdminOrg }`, the property name is
-extracted (lines 54-60).
-
-The comment at lines 55-59 says the runtime resolves the shorthand the same way as the longhand
-form, and that dropping it once reported a guarded function as having no permissions.
-
-**What this rules out:** an audit that skips shorthand permission entries and so shows a guarded
-function as open.

package/knowledge/decisions/system-roles-declare-literal-unqualified-scopes.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: System roles must declare literal, unqualified scopes
-description: A system role needs a literal scopes array of string literals, and its name may not contain the scope separator
-tags: [inspector, roles, scopes]
----
-
-# System roles must declare literal, unqualified scopes
-
-`addSystemRole` in `packages/inspector/src/add/add-system-role.ts` applies these rules
-to each `defineSystemRole` entry:
-
-- `scopes` must be present and must be an array literal. A missing or non-literal
-  `scopes` is reported as critical and the role is dropped (lines 37-54, and the
-  skip at 143-146). The message asks for `scopes: []` when a role grants nothing
-  (line 40).
-- Each element of `scopes` must be a string literal. A non-literal element is
-  reported as critical and skipped (lines 57-66). The reason given is that scopes
-  are read by AST, so a computed value cannot be checked (line 63).
-- A role name containing `:` is refused (lines 126-133), because `:` delimits scope
-  ids and "a role named like a scope reads as one" (line 130).
-- An empty role name is refused (lines 118-124).
-
-The doc comment on `extractScopes` (lines 20-23) says the empty array and the
-absent property are kept distinct on purpose.
-
-**What this rules out:** a role whose scopes cannot be checked statically, and a
-role name that looks like a scope id.

package/knowledge/decisions/the-inspector-records-agent-permissions-only-to-aggregate-services.md

@@ -1,14 +0,0 @@
----
-type: decision
-title: The inspector records an agent's permissions only to aggregate the services they need, never to check access
-description: addAgent adds the agent's permission names to usedPermissions, and post-process reads that set only to collect each permission's services
-tags: inspector, agents, permissions
----
-
-# The inspector records an agent's permissions only to aggregate the services they need, never to check access
-
-`addAgent` resolves the agent's permissions and adds their names to `state.serviceAggregation.usedPermissions` (`packages/inspector/src/add/add-agent.ts:612`, `:618-620`). `post-process.ts` reads the same set at `packages/inspector/src/utils/post-process.ts:160`, and at `:206-209` it adds each used permission's `services` to the service list.
-
-Within the inspector source those are the only readers. `serialize-inspector-state.ts` copies the set in and out (`packages/inspector/src/utils/serialize-inspector-state.ts:294`, `:522`, `:746`). Nothing in the inspector compares a caller against the set.
-
-**What this rules out:** reading the inspector's agent permission list as evidence that an agent is guarded, and adding an access decision to the inspector's aggregation step.

package/knowledge/decisions/vault-secrets-reach-no-sink-and-pii-stays-out-of-logs-and-webhooks.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only
-description: check-classified-sinks rejects revealed secrets in every listed sink and PII only in the logger, console and webhook sinks
-tags: [inspector, pii, secrets, lint]
----
-
-# Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only
-
-The sink table in `packages/inspector/src/utils/check-classified-sinks.ts` (lines 44-59) lists
-which methods count as sinks and what each one rejects:
-
-- `Logger`, every method, rejects `secret` and `pii` (line 49);
-- `WebhookService.send` rejects `secret` and `pii` (line 50);
-- `QueueService.add` rejects `secret` only (line 51);
-- `EmailService.send` rejects `secret` only (line 52);
-- `AuditService` `audit` and `write` reject `secret` only (lines 53-57);
-- `AuditLog.write` rejects `secret` only (line 58).
-
-`console` is handled separately and rejects both (line 62).
-
-The comment at lines 23-38 gives the reasons. A vault secret is wrong in every sink (lines 23-24).
-PII is wrong only where it leaves the operator's control or lands somewhere never meant to hold
-it. Lines 37-38 say a queue payload "stays on the operator's own infrastructure", and lines 33-34
-say an email is addressed to the data subject.
-
-Lines 40-42 say `private` is absent from the table on purpose.
-
-**What this rules out:** a revealed secret reaching any listed sink, and PII reaching a logger,
-the console or a webhook. PII is allowed into queues, email and audit by this table.

package/knowledge/decisions/webhook-gateway-wrappers-are-sessionless-and-gateway-auth-runs-inside-the-handler.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call
-description: The inspector and the runtime both register a webhook gateway's POST and verify routes as sessionless with auth false, so the route never demands a session and the gateway's own auth flag is applied only when the handler runs
-tags: inspector, gateway, webhook, auth, sessionless
----
-
-# Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call
-
-**Build time.** For a webhook gateway, `addGateway` writes two function metas, `gateway__<name>__post` and `gateway__<name>__verify`, and their HTTP routes (`packages/inspector/src/add/add-gateway.ts:105-109`). Each function meta is written with `sessionless: true` (`add-gateway.ts:117-122`). The comment on the wrapper says "no middleware here — the gateway POST wrapper runs it itself" (`add-gateway.ts:111`).
-
-The gateway's own `auth` flag is not used there. It is recorded only on the gateway meta, as `auth` on `state.gateways.meta[name]` (`add-gateway.ts:135`).
-
-**Run time.** `wireWebhookGateway` in `packages/core/src/wirings/gateway/gateway-runner.ts` mirrors this. The POST and verify handlers are both registered with `auth: false` (`gateway-runner.ts:117`, `:141`), and so are their routes (`gateway-runner.ts:130`, `:154`).
-
-The POST wrapper, `createWebhookPostHandler` (`gateway-runner.ts:163`), does three things in order:
-
-1. If the adapter has `verifyWebhook` and it verifies the request, it returns the adapter's response immediately (`gateway-runner.ts:175-179`). The handler is not reached.
-2. It parses the body; an unparseable body returns `{ ok: true }` (`gateway-runner.ts:182-185`).
-3. It invokes the handler through `runPikkuFunc('gateway', name, handlerFuncId, { ..., auth: config.auth, ... })` (`gateway-runner.ts:196-204`), with gateway middleware running first (`gateway-runner.ts:207-211`).
-
-So the session check for a webhook is applied from `CoreGateway.auth`, inside the runner call at `gateway-runner.ts:201`. It is not applied on the HTTP route, which is `auth: false` and sessionless.
-
-The synthetic handler registration that this call goes through, and how it inherits the wired function's metadata, is described in [Gateway handlers run through the function runner gate](../../../core/knowledge/decisions/security/gateway-handlers-run-through-the-function-runner-gate.md).
-
-**What this rules out:** adding `auth: true` to the POST or verify route to "harden" a webhook. That would reject every platform call, which carries no user session. It also rules out assuming that the route-level metadata shows whether a gateway needs a session. Check `CoreGateway.auth` and the handler's own declaration instead.

package/knowledge/index.md

@@ -1,14 +0,0 @@
----
-type: overview
-title: Knowledge
-description: Why the inspector reads and refuses declarations the way it does
----
-
-# Knowledge
-
-Why the inspector reads and refuses declarations the way it does — the reasoning that is not visible in the code.
-
-<!-- pikku:knowledge-index -->
-- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
-- [questions](questions/index.md) — something asked and not yet answered
-<!-- /pikku:knowledge-index -->

package/knowledge/questions/does-a-non-literal-remote-addon-auth-get-checked.md

@@ -1,26 +0,0 @@
----
-type: question
-title: Does a non-literal auth on wireRemoteAddon get checked?
-description: A non-literal auth value is recorded exactly like an omitted one, so the consumer's credential and secret checks never run for it
-tags: [inspector, addon, auth]
----
-
-# Does a non-literal auth on wireRemoteAddon get checked?
-
-`addWireRemoteAddon` in `packages/inspector/src/add/add-wire-remote-addon.ts` reads
-`auth` only when it is an object literal (lines 42-46). Otherwise `hasAuth` stays
-`false` (line 31) and `authCredentialId` and `authSecretId` stay undefined.
-
-The comment at lines 27-30 says `hasAuth` separates "public" (omitted) from "bound
-via a custom resolve()" (present, with no static id). A non-literal `auth` value
-therefore looks the same as an omitted one. The declaration is written at lines
-71-78, with `hasAuth` at line 75.
-
-Nothing in the inspector reads `hasAuth`. Its only other mentions are the type at
-`packages/inspector/src/types.ts:749` and serialization at
-`packages/inspector/src/utils/serialize-inspector-state.ts:172`. The post-process
-checks run only when an id is set: the credential id at
-`packages/inspector/src/utils/post-process.ts:841` and the secret id at line 847.
-
-Question: should a non-literal `auth` be treated as a binding the consumer has to
-satisfy, or as public? The code currently does neither and logs nothing.

package/knowledge/questions/index.md

@@ -1,16 +0,0 @@
----
-type: overview
-title: Questions
-description: Things asked of inspector and not yet answered
----
-
-# Questions
-
-Something asked and not yet answered. The choice stays, the doubt gets recorded.
-
-<!-- pikku:knowledge-index -->
-- [Does a non-literal auth on wireRemoteAddon get checked?](does-a-non-literal-remote-addon-auth-get-checked.md) — A non-literal auth value is recorded exactly like an omitted one, so the consumer's credential and secret checks never run for it
-- [Should an incomplete oauth2 block be dropped without a log?](is-an-incomplete-oauth2-block-dropped-without-a-log.md) — An oauth2 block missing any required field is silently left undefined, and an empty scopes array passes the check
-- [Should an app function named like scenario instrumentation be silently skipped?](should-app-functions-named-like-scenario-instrumentation-be-refused.md) — Five instrumentation names are skipped by name in every project, so an app's own function with one of those names disappears without a log
-- [Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?](should-the-openapi-document-default-every-operation-to-a-bearer-or-api-key.md) — The OpenAPI serializer emits one top-level security default for all operations and does not read the auth or session metadata of any route
-<!-- /pikku:knowledge-index -->

package/knowledge/questions/is-an-incomplete-oauth2-block-dropped-without-a-log.md

@@ -1,23 +0,0 @@
----
-type: question
-title: Should an incomplete oauth2 block be dropped without a log?
-description: An oauth2 block missing any required field is silently left undefined, and an empty scopes array passes the check
-tags: [inspector, credentials, oauth]
----
-
-# Should an incomplete oauth2 block be dropped without a log?
-
-In `packages/inspector/src/add/add-credential.ts`, `oauth2` is set only when
-`appCredentialSecretId`, `authorizationUrl`, `tokenUrl` and `scopes` are all truthy
-(lines 144-155). There is no `else` branch, and nothing in that block calls the
-logger. The credential is still recorded, with `oauth2` undefined.
-
-`scopes` comes from `getArrayPropertyValue`, which returns `string[] | null`
-(`packages/inspector/src/utils/get-property-value.ts:22`). An array literal returns
-its string elements even when there are none (lines 31-35). An empty array is
-truthy, so `scopes: []` passes the check.
-
-Question: should a half-filled `oauth2` block be reported as critical, as the other
-other validation in the same file is (logger calls at lines 49, 57 and 65)? And should `scopes: []` be
-allowed to satisfy the check at all? The code currently does neither, and no
-comment or test in this path says why.

package/knowledge/questions/should-app-functions-named-like-scenario-instrumentation-be-refused.md

@@ -1,28 +0,0 @@
----
-type: question
-title: Should an app function named like scenario instrumentation be silently skipped?
-description: Five instrumentation names are skipped by name in every project, so an app's own function with one of those names disappears without a log
-tags: [inspector, scenarios, functions]
----
-
-# Should an app function named like scenario instrumentation be silently skipped?
-
-`SCENARIO_INSTRUMENTATION_FUNCTIONS` in
-`packages/inspector/src/add/scenario-instrumentation.ts` lists five names (lines
-22-28). `isScenarioInstrumentationFunction` matches them on the id before any `@`
-(lines 40-42).
-
-In `packages/inspector/src/add/add-functions.ts`, a function whose id or name matches
-is returned before it is registered (lines 571-576). No logger call happens there.
-The file's comment says the function is "not application code" and must not be
-registered.
-
-The file comment gives the reason for matching by name: it keeps an existing
-project's checked-in `scenarios.gen.ts` from deploying (lines 12-15). Lines 17-20
-say `pikkuScenarioGradeRun` is reserved "so an application cannot claim it". No
-comment says the same about the other four names.
-
-Question: should an application's own function named `pikkuScenarioResetStubs`,
-`pikkuScenarioGetStubCalls`, `pikkuScenarioTakeLiveCoverage` or
-`pikkuScenarioResetLiveCoverage` be refused with a critical, as the reserved name
-would be, rather than dropped silently?

package/knowledge/questions/should-the-openapi-document-default-every-operation-to-a-bearer-or-api-key.md

@@ -1,22 +0,0 @@
----
-type: question
-title: Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?
-description: The OpenAPI serializer emits one top-level security default for all operations and does not read the auth or session metadata of any route
-tags: [inspector, openapi, auth]
----
-
-# Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?
-
-`generateOpenAPISpec` in `packages/inspector/src/utils/serialize-openapi-json.ts` writes two security
-schemes, `ApiKeyAuth` (an `x-api-key` header) and `BearerAuth`, unless the caller supplies its own
-(lines 254-264). It then writes a top-level `security` array with one entry for each scheme
-(lines 266-273), unless the caller supplies one.
-
-In OpenAPI a top-level `security` applies to every operation that does not set its own. This file
-does not write per-operation `security`, and a search of the file for `requiresSession` and
-`sessionless` finds nothing. So an operation for a route marked `auth: false` would carry the same
-default as one that requires a session.
-
-Question: should `auth: false` routes and sessionless functions be written with an empty
-`security` list, and should the default be applied per operation? The code does not say whether the
-default is meant for the whole API or only as a placeholder.

package/run-tests.sh

@@ -1,68 +0,0 @@
-#!/bin/bash
-
-# Enable nullglob to handle cases where no files match the pattern
-shopt -s nullglob
-
-# Initialize variables for options
-watch_mode=false
-coverage_mode=false
-
-# Parse command-line options
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --watch)
-      watch_mode=true
-      shift
-      ;;
-    --coverage)
-      coverage_mode=true
-      shift
-      ;;
-    *)
-      echo "Unknown option: $1"
-      exit 1
-      ;;
-  esac
-done
-
-# Define the pattern to match your test files
-pattern="src/*.test.ts"
-
-# Expand the pattern into an array of files
-files=($(find src -type f -name "*.test.ts"))
-
-# Check if any files matched the pattern
-if [ ${#files[@]} -eq 0 ]; then
-  echo "No test files found matching pattern: $pattern"
-  if [ "${STRICT_TEST_DISCOVERY}" = "1" ]; then
-    exit 1
-  fi
-  exit 0
-fi
-
-# Construct the bun command
-#
-# --parallel gives every test file its own worker process, which is what node's
-# `--test` did. Several suites keep module-level caches (a TypeScript program, a
-# temp fixture directory) that a shared process would leak between files.
-#
-# --timeout because bun caps a test at 5s by default where node had no cap, and
-# the suites that build real TypeScript programs run well past that.
-bun_cmd=(bun test --parallel --timeout 120000)
-
-# Append options based on flags
-if [ "$watch_mode" = true ]; then
-  # --watch reruns in one process; parallel workers have nothing to watch.
-  bun_cmd=(bun test --watch --timeout 120000)
-fi
-
-if [ "$coverage_mode" = true ]; then
-  # --coverage-dir=. keeps lcov.info at the package root: CI merges every
-  # package's report by prefixing its SF paths with the file's own directory,
-  # so a nested coverage/ directory would re-root them one level too deep.
-  bun_cmd+=(--coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir=.)
-  export PIKKU_TEST_COVERAGE=1
-fi
-
-# Execute the bun command with the expanded list of files
-"${bun_cmd[@]}" "${files[@]}"