@zackbart/connecta 0.28.1 → 0.30.0

package/templates/node/src/provision-token.ts

@@ -0,0 +1,17 @@
+/** Trusted local provisioning against the same database the server uses. */
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import { openSqlite, sqliteStorage } from "@zackbart/connecta/sqlite";
+
+const name = process.argv[2];
+if (!name || process.argv.length !== 3) {
+  throw new Error('Usage: npm run provision-token -- "machine-name"');
+}
+const database = openSqlite(process.env.CONNECTA_DATABASE || "./.connecta.sqlite");
+try {
+  const manager = new AccessTokenManager(sqliteStorage(database));
+  const { token } = await manager.create(name, "local-provisioning");
+  // The secret is returned once. Keep stdout private; storage holds its hash.
+  process.stdout.write(`${token}\n`);
+} finally {
+  database.close();
+}

package/AGENTS.md

@@ -1,170 +0,0 @@
-# Working on connecta
-
-This is the canonical instruction file for coding agents. `CLAUDE.md` is a
-symlink to this file so every agent works from the same conventions.
-
-A single MCP endpoint aggregating downstream connectors (remote MCP servers and
-plain HTTP APIs) behind seven meta-tools, `execute_code` among them. Every
-deployment configures an executor, and agents reach connectors by writing
-JavaScript against it. One fetch-native core on Effect behind a Promise API,
-running on both Node and Cloudflare Workers. A program runs read-only and
-config-exempt tools; every other write is its own `call_destructive_tool` call,
-so the host's permission prompt is the only approval. The code and the guides
-describe what exists.
-
-- **[`ethos.md`](./ethos.md) is the constitution.** It states what connecta is
-  and isn't, and its decisions table carries a verdict for every shape already
-  considered — accepted, planned, refused, removed, provisional, or gated.
-  Check the table before designing or building anything: a `planned` row is a
-  "yes" that has not shipped, binding on review now and absent from the guides
-  until it lands, so never document it there as if it exists; a `refused` row
-  is a "no" with the reason attached, and a `removed` row (toolkits
-  [#178](https://github.com/zackbart/connecta/issues/178), proactive credential
-  liveness [#179](https://github.com/zackbart/connecta/issues/179), the classic
-  executor-free surface
-  [#273](https://github.com/zackbart/connecta/issues/273)) records a surface
-  that no longer exists — do not reintroduce it without a new decision.
-- There is no TODO.md — the roadmap lives in
-  [GitHub issues](https://github.com/zackbart/connecta/issues). When you find
-  TODO items (in code comments, docs, or conversation), don't accumulate them
-  in a file: turn each one into a GitHub issue that clearly defines what to do
-  — motivation, behavioral requirements, and acceptance criteria — without
-  prescribing the implementation.
-
-## Verification
-
-`npm run check` must pass before you claim anything is done — `check:docs` →
-`check:operator-ui` → `check:lint` → `check:unused` → `typecheck` → `test`
-(both vitest projects) → `test:browser` (the operator UI in Chromium; run
-`npm run test:browser:install` once per machine, since `check` is also what
-`npm pack` runs) → `build` (which prunes unreachable declarations) →
-`check:declarations` (no Effect type in what ships) → `check:bundle` (per-entry
-gzip caps in `scripts/bundle-budget.json`) → `check:examples`. It is also the
-`prepack` hook. `npm run release:check` adds `check:security` and `check:package` and is
-what CI runs on every pull request, on `main`, and again on publish; use it
-when touching packaging, dependencies, or exports.
-
-## The map
-
-- [`ethos.md`](./ethos.md) — what connecta is, what it refuses to be, the
-  decisions table, and the invariants every change must preserve. Check it
-  before building something new; "we already decided not to" is a real answer
-  there, and its planned/removed/provisional verdicts override anything staler.
-- [`documentation/`](./documentation/) — four guides for agents working on the
-  repo: `architecture.md`, `meta-tools.md`, `code-mode.md`, and `auth.md`.
-  Everything else — connectors, providers, admission, storage, the operator
-  UI, operations — is documented where it lives, in the source and its tests.
-  The guides that once covered those survive only in git history, which is
-  worth mining for rationale and worth nothing where it disagrees with
-  `ethos.md` or the code. Start with `architecture.md`.
-- [`README.md`](./README.md) — the human-facing overview.
-- [`templates/node/`](./templates/node/) — the one standalone Node deployment
-  shape copied by `connecta init`, Docker-ready rather than Docker-only. Keep
-  it small and prescribed. There are exactly two deployment shapes, this one
-  and [`examples/worker/`](./examples/worker/); a third scaffold that is a
-  diff away from one of them is the shape
-  [#344](https://github.com/zackbart/connecta/issues/344) deleted.
-
-**Read `ethos.md` before changing a subsystem, and its guide when it has one.**
-
-## Deployment setup
-
-`connecta init [directory]` is the golden path. It copies `templates/node/`,
-pins the generated deployment to the CLI package's exact version, restores the
-template `.gitignore` and the `CLAUDE.md` symlink, and refuses to merge into an
-existing path.
-`connecta doctor` verifies a running deployment's health, executor, and exact
-seven-tool surface. The template carries its own `Dockerfile` and
-`docker-compose.yml`, so the generated project is the container: setup changes
-must keep the root README, the template (source, container files, and README),
-and the `scripts/check-package.mjs` smoke — which builds and runs that
-container when Docker is available — aligned. Do not add a second initializer,
-a second container recipe, or another “recommended” project shape.
-
-## Where new code goes
-
-Two boundaries CI enforces that are not obvious from reading a file:
-
-- **Import-graph purity.** Nothing reachable from `src/index.ts` may import a
-  `node:` builtin — the core is Web-API only so it runs unchanged on Workers.
-  `src/node.ts`, `src/storage/file.ts`, and the QuickJS process-pool entry
-  (`src/executors/quickjs.ts` + child) are the Node-touching paths and must stay
-  unreachable from the root entry. `test/purity.test.ts` walks the import graph
-  and fails otherwise. Need a Node API? It goes behind an explicit Node-only
-  subpath (`/node` or `/quickjs`), never the root. `effect/testing` is banned
-  from `src/` on the same terms — its test clocks and layers have no business
-  in a runtime graph — and the purity walk catches it. The same walk keeps
-  the root entry to `effect` itself and lets only `src/runtime/run.ts` start
-  a fiber.
-- **Optional modules.** Core owns catalog discovery, execution, invocation, and
-  enforcement. UI, activity history, encrypted credentials, and bearer auth
-  implementations stay behind explicit subpaths and outside the root import
-  graph. Use the typed `ui`, `activity`, and `vault` slots; do not add a generic
-  plugin registry or runtime installation.
-- **The published surface.** Platform-specific storage adapters live in
-  `examples/worker/`, never in `src/` and never in the `exports` map. That
-  example does ship in the tarball, Cloudflare KV and D1 adapters included —
-  it is the Workers starting template a consumer copies, and copying it is the
-  point — but every `exports` target resolves into `dist/`, so those adapters
-  are readable reference source and not an importable subpath. What is
-  forbidden is a platform-bound adapter becoming importable from the package,
-  not a file appearing in the artifact. `@clerk/backend` and
-  `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
-  `./quickjs` subpaths, and `@cloudflare/codemode` is the third, peered
-  without a subpath because a Worker deployment imports it directly. None may
-  become a dependency or install with core. Enforced by `test/package-surface.test.ts` and
-  `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
-  subpath and an optional peer. The Effect core is the one deliberate
-  exception: it is the core, so it is a hard dependency rather than a peer,
-  under the rule in [Conventions](#conventions).
-
-## Where new tests go
-
-Suites live in `test/` and run as two vitest projects (`vitest.config.ts`).
-Every `*.test.ts` belongs to exactly one explicit list: runtime-portable suites
-in `WORKERS_SUITES`, Node-bound suites in `NODE_ONLY_SUITES` with a reason. The
-`node` project runs both lists; the `workers` project re-runs the portable list
-inside workerd. `test/suite-partition.test.ts` walks the directory and fails on
-an unclassified, double-classified, stale, or reasonless entry.
-
-## Conventions
-
-- **Static analysis.** `npm run check:lint` runs Oxlint's correctness category
-  only; it does not enforce style. `npm run check:unused` runs Knip's
-  unused-export and dependency gate. Keep both clean, and prefer removing dead
-  declarations over suppressing a finding.
-- **Effect inside, Promises at the edge.** The core runs on Effect v4 and
-  exports none of it; [Effect inside](./documentation/architecture.md#effect-inside)
-  has the shell/core shape, the one runner, and the cross-request rules.
-  `createConnecta`,
-  `remoteMcp()`, `api()`, custom connectors, and every published `.d.ts` stay
-  Promise-based and name no Effect type: a deployment author should never need
-  a second async paradigm to write a connector, so convert at the boundary,
-  not in the caller. Effect is a hard dependency pinned to one exact version,
-  never a range, and compatible with Alchemy's peer requirement, so a deployment
-  that uses both resolves one Effect rather than two. Modules tagged
-  `@stability unstable` are allowed behind subpaths: they can break in minor releases,
-  so an upgrade is its own deliberate pull request, never a drive-by in another
-  change. `effect/testing` stays out of `src/` (see import-graph purity). The
-  MCP edges do not move with the core — `@modelcontextprotocol/server` upward,
-  the SDK client downstream. Replacing either requires separate proof of the
-  wire contracts and request lifetimes; the stable core release is not that proof.
-- **Style.** There is no formatter. Match the surrounding code. The docs voice
-  is precise, occasionally wry, and always explains *why* — don't flatten it
-  into boilerplate.
-- **Commits.** Imperative summary naming the behavior change, with issue refs in
-  parens: `Normalize maxResultBytes at every intake point (#32) (#39)`.
-- **CHANGELOG.** Each release opens with a narrative paragraph — what this
-  release is, what breaks, what a deployment can ignore — then
-  `### Added` / `### Changed` / `### Fixed`.
-- **Provider drift.** Run `npm run providers:check` for the credential-free
-  public check across every maintained provider. It covers official MCP
-  documentation and OpenAPI contracts and never reads a provider credential.
-  Remote MCP schemas remain owned by the live `tools/list` response rather than
-  a vendored copy. Findings are read by a human and become GitHub issues;
-  nothing files itself. `scripts/drift-check.mjs` is the reference for what
-  each flag covers.
-- **Releases.** `npm run release:check`, tag `v<version>` matching
-  `package.json` exactly (the publish workflow verifies this and fails
-  otherwise), and publishing fires on GitHub **Release publication**, not on the
-  tag push.

package/dist/artifacts/connector.d.ts

@@ -1,58 +0,0 @@
-import { type ResolvedTheme } from "../branding.js";
-import type { Connector } from "../types.js";
-import { type ArtifactOperations } from "./operations.js";
-import { type ArtifactRefreshService } from "./refresh.js";
-import type { ArtifactAllowlist, ArtifactIssue, ArtifactKind, ArtifactLimits } from "./types.js";
-/** What a deployment's render check is handed: exactly what the viewer loads. */
-export interface ArtifactRenderCheckInput {
-    /** The complete frame document, data injected. */
-    document: string;
-    /** The Content-Security-Policy the viewer serves it under. */
-    csp: string;
-    kind: ArtifactKind;
-    /** Aborted when the check's 20-second deadline or the call's own passes. */
-    signal: AbortSignal;
-}
-export type ArtifactRenderCheckResult = {
-    ok: true;
-    warnings?: string[];
-} | {
-    ok: false;
-    errors: string[];
-};
-/**
- * A real render check — a headless browser, say — run on `validate_artifact`
- * and on every write that changes what a page renders. It must answer within
- * 20 seconds; a throw or a timeout fails the write as retryable `unavailable`
- * and saves nothing.
- */
-export type ArtifactRenderCheck = (input: ArtifactRenderCheckInput) => Promise<ArtifactRenderCheckResult>;
-type RenderVerdict = {
-    ok: true;
-    warnings: ArtifactIssue[];
-} | {
-    ok: false;
-    errors: ArtifactIssue[];
-} | {
-    ok: false;
-    unavailable: string;
-};
-/** Run a hook under its 20-second deadline and the call's own signal. Never throws. */
-export declare function runRenderCheck(hook: ArtifactRenderCheck, input: {
-    document: string;
-    csp: string;
-    kind: ArtifactKind;
-}, callSignal: AbortSignal | undefined): Promise<RenderVerdict>;
-export interface ArtifactsConnectorOptions {
-    operations: ArtifactOperations;
-    refresh: ArtifactRefreshService;
-    allowlist: ArtifactAllowlist;
-    limits: ArtifactLimits;
-    renderCheck?: ArtifactRenderCheck;
-    /** Where pages are served, when not the deployment's own origin. */
-    origin?: string;
-    /** Resolved deployment theme, available after the module binds to core. */
-    theme?: () => ResolvedTheme | undefined;
-}
-export declare function artifactsConnector(options: ArtifactsConnectorOptions): Connector;
-export {};