feat(auth): define CLI session and credential contracts

[Stephanie (stephanieatdedalus)]

Linear Issue

Ref ENG-743

Summary

What:

Introduces the provider-neutral CLI session model and credential-storage contract needed by the Scalar-generated CLI authentication stack. It also enables the custom stack test command in CI and pins stable machine-readable credential error codes.

Why:

This is the first reviewable slice of the Clerk CLI authentication customization currently maintained in the stephanieatdedalus/dedalus-cli fork. It establishes the contracts required by the secure storage, OAuth, lifecycle, and Scalar runtime integrations that follow.

Lines added: 166

Test Plan

• npm test
• npm run typecheck
• verified from a clean detached worktree against the exact PR head

Repro / Showcase

N/A — foundational auth contracts with unit coverage.

Tests Added

• Unit tests
• Integration tests
• End-to-end (E2E) tests
• N/A (no new code paths)

Documentation

• Internal (docs/): N/A
• External: N/A for this foundational slice; the later documentation slice describes the full trust boundary.

Reviewers

• Domain: Shengming Liang (@LiangShengming)
• Readability: Vitus Larrieu (@vitus-dedalus)

Notes for Reviewers

Base is scalar-next, the Scalar-generated customization branch. This is stack 1 of 24; later prepared branches add secure credential storage, Clerk OAuth/PKCE, session lifecycle, safe output/errors, Scalar runtime wiring, and generated resource-command compatibility.

Changelog

2026-08-21

Feedback received:

• (none yet)

Changes made:

• Ported the first Scalar CLI-auth customization slice from the existing fork stack.

Browser counterpart

The validated Clerk browser handoff is reviewed in https://github.com/dedalus-labs/dedalus/pull/5530 and its browser stack. This CLI stack owns loopback callback setup, PKCE exchange, token persistence, refresh, logout, Scalar runtime injection, and generated resource-command authentication.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​proper-lockfile@​4.1.2
	npm/​@​napi-rs/​keyring@​1.3.0
	npm/​@​types/​proper-lockfile@​4.1.4

View full report

[Shengming Liang (LiangShengming)]

concern: stack-wide regeneration boundary for the later Scalar-integration layers; this does not block #34.

I confirmed the branch model is correct: official scalar-generated and scalar-next are both at fd5540f, and this PR correctly targets scalar-next. Scalar explicitly documents that custom edits belong on scalar-next while scalar-generated remains pristine.

At the prepared stack tip (7af16867), src/commands/index.ts, src/cli/runtime.ts, and src/sdk/client.ts are generator-owned files with handwritten changes. Scalar supports this through its three-way merge, so this is not a violation. The small index.ts attachment seam is reasonable; the broader runtime and SDK edits are the places most likely to conflict with future Scalar output. When those layers open, please keep the generated seam as narrow as possible, keep the runtime/SDK fixes in separately reviewable layers with focused invariants, and attach a fresh Scalar-regeneration receipt before the final stack lands. That preserves the auth work while making future generator updates easier to absorb.

Reference: https://scalar.com/products/sdk-generator/custom-code

[Shengming Liang (LiangShengming)]

question: the later operation-catalog layer adds a second Dedalus-owned generator, scripts/generate-cli-operations.mjs.

I see the concrete reason: pristine Scalar output at fd5540f leaves src/commands/index.ts with commands = [], so the current Scalar candidate cannot execute the OpenAPI resource operations without another catalog producer. The prepared stack does the important safety work already: unknown operation IDs fail closed, generate:check detects stale artifacts, and the command-surface test covers all 35 OpenAPI operations.

When #23/#24 are opened officially, please call out this ownership decision and its exit condition explicitly: this generator is a bridge for the missing Scalar command catalog, not part of the authentication architecture, and should be removable if Scalar begins emitting the operation catalog natively. Keeping that boundary explicit prevents the auth stack from silently becoming a permanent fork of Scalar command generation.