commit 92f7df83c46ae45ed1fe2e0c0f0c1bfd2cb5dac7 Author: caelum0x Date: Thu Nov 12 18:10:58 2026 +0300 scribase CLI + TypeScript SDK (public edge repo) Extracted from the private caelum0x/scribase monorepo's packages/scribase-js with a fresh, single-commit history (no core history leaks). The npx scribase CLI and the typed /v1 API client, unchanged except: prepublishOnly simplified (the monorepo-only tarball gitleaks gate dropped), repository/homepage/bugs fields added, and one test that cross-checked embedded template strings against the monorepo's templates/ directory removed (nothing it tested changed; that directory isn't shipped here). diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5732301 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +# Changelog + +## 0.3.0 (2026-11-11, not yet published) + +- `npx scribase connect [tool...]` writes the Scribase MCP server into every + AI coding tool this machine has (Claude Code via `claude mcp add`, Cursor, + VS Code, Codex, Windsurf, Zed) in one idempotent command. `--dry-run` shows + what would change; `--tool ` (repeatable) configures exactly those + tools regardless of detection. Never writes a token or secret — every + client's own MCP OAuth flow runs on first use instead. + +## 0.2.0 (2026-11-11) + +- `npx scribase init` is temporary-first: with no sign-in it creates a 72-hour + temporary project and prints a claim link; `--account`, `--watch` and + `scribase doctor` are new. +- `npx scribase init` prints the project URL and, for a temporary project, the + claim link as soon as the backend is live, before the Vercel push and the + client-library install. +- `scribase add ` (analytics, deploy, flags, uptime, ai, billing, + consent, …) wires one capability into the project and prints proof JSON of + the first real event. +- `scribase ota deploy|rollback|status` for over-the-air updates, and + `scribase migrate` runs the real plan/lint/apply route. +- `init` detects SvelteKit and scaffolds its `$env/static/public` client; the + generated plain-Node client auto-loads `.env`. +- The default region id is `eu-frankfurt` (it names the city, not a hosting + provider). Projects created with the earlier `oci-eu-frankfurt-1` label keep + working unchanged. +- `prepublishOnly` runs `scripts/check-npm-tarball.mjs --gitleaks`: the publish + stops if the tarball holds an env file, a key file, a file outside the allow + list, or a secret-looking string. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b5f531 --- /dev/null +++ b/README.md @@ -0,0 +1,246 @@ +# scribase + +Supabase gives you a database and sign-in. Scribase is the whole backend for +your app: Postgres, Auth, Storage, Realtime, Functions and migrations behind +one flat price per project, with copy-on-write branching and an agent-native +CLI/SDK/MCP surface built in from day one. + +This repo is the `npx scribase` CLI and the typed, fetch-based TypeScript +client for the [Scribase](https://scribase.com) management `/v1` API, both +shipped as the single `scribase` npm package. It talks to the same public +`https://api.scribase.com` endpoint the dashboard and console use — nothing +in this repo runs a database or a control plane itself. + +- **Zero runtime dependencies.** A thin, typed wrapper over `fetch`. +- **Contract-first core.** `src/types.gen.ts` is emitted from + `api/openapi.yaml` (orgs, memberships, projects, environments, operations, + audit, imports, migrations, exports). Newer surfaces (backups, restores, + usage, database, queues, functions, account, …) are typed by hand in + `src/resources/*.ts` against the exact bodies `crates/control-api` renders; + each type's doc comment names the server function it mirrors. +- **Async-operation aware.** Every mutation returns an `Operation` to poll, and + the client gives you `wait(...)` helpers so "accepted" becomes "done". +- **Idempotency + retries built in.** Mutating calls attach an + `Idempotency-Key` automatically; 429/503/network failures back off and retry. + +Requires Node >= 22.13 (built-in `fetch`, `crypto.randomUUID`) or any runtime +with the Fetch and Web Crypto globals. + +## `npx scribase init` + +The package also ships a `scribase` binary, made for coding agents (Claude +Code, Codex, Cursor, Windsurf) and people alike: + +```bash +npx scribase init --json # not signed in: a 72-hour temporary project with a claim link + # signed in (SCRIBASE_ACCESS_TOKEN or `scribase login`): your account +npx scribase init --account # not signed in, but use an account (approve in the browser) +npx scribase init --watch # also wait for the app's first request +npx scribase sql "create table notes (id bigint generated always as identity primary key, body text)" + # run SQL on this folder's project, in one transaction +npx scribase doctor # check env vars, keys and the connection; one fix per problem +``` + +A new project's database is empty, so init's first next step creates a small +`notes` table with `npx scribase sql` (row level security on, read-only for +the public key) and the second queries it with `supabase.from('notes')`. +`sql` holds back statements that remove data until you add `--confirm`. + +Init prints "Live in N s" with the measured time. The claim link carries +`?ref=`, a random id stored in `~/.config/scribase/install-id` +(`SCRIBASE_NO_REF=1` sends none). Claiming (sign up + card check) keeps the +same URL and keys. + +It detects Next.js, Expo, Vite or plain Node, creates (or reuses) a project, +writes the env file with that framework's variable names +(`NEXT_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_URL`, `VITE_SUPABASE_URL`, +`SUPABASE_URL`, and the anon key; the service-role key only where it cannot +reach a client bundle), installs `@supabase/supabase-js`, writes a small +client module and prints one JSON object (`ok`, `api_url`, `env_vars`, +`client_file`, `claim_url`, `next_steps`, or `ok: false` with an error `code` +and a `next` step). Run it again and it reuses the same project. + +When the folder is linked to Vercel (`.vercel/project.json` or +`VERCEL_PROJECT_ID`), init also sets the URL and keys on that Vercel project for +development, preview and production, using `VERCEL_TOKEN` or the signed-in +`vercel` CLI, and reports `vercel: { status, targets }` (`updated`, +`not_linked`, `no_credentials`, `failed`). It never fails init; `--no-vercel` +turns it off. + +## Install + +```bash +npm install scribase +# or +pnpm add scribase +``` + +Working on this repository directly? Clone it and build from source instead: + +```bash +git clone https://github.com/caelum0x/scribase-cli.git +cd scribase-cli +npm install +npm run build +npx ./dist/cli/index.js --help # or: npm link, then `scribase --help` +npm install file:../path/to/scribase-cli # in your app, instead of the npm registry +``` + + +## Quick start + +```ts +import { ScribaseClient } from 'scribase'; + +const scribase = new ScribaseClient({ + baseUrl: 'https://api.scribase.com', // your installation's management endpoint + token: process.env.SCRIBASE_ACCESS_TOKEN ?? '', +}); + +// Bootstrap an org (idempotent; caller becomes owner), then a project. +await scribase.organizations.put('acme', { display_name: 'Acme, Inc.' }); +await scribase.projects.put('acme', 'store', { region: 'us-east', postgres_major: 17 }); + +// Provision production. Mutations are asynchronous. +const { operation } = await scribase.environments.create({ + organization_id: 'acme', + project_id: 'store', + environment_id: 'production', + kind: 'production', + data_mode: 'snapshot', + region: 'us-east', + postgres_major: 17, +}); +await scribase.operations.wait(operation.id, 'acme', { + onUpdate: (op) => console.info(`provision: ${op.state}`), +}); +``` + +## Resources + +Every method maps to one real route in `crates/control-api/src/http.rs`. + +| Accessor | Methods → endpoints | +|---|---| +| `client.organizations` | `put`/`get` `/v1/organizations/{id}`, `update` (`PATCH`, rename), `list` `/v1/organizations`, `putMembership`/`listMemberships` `…/memberships`, `scheduleDeletion` (`DELETE`), `get`/`putNotificationSettings`, `listApiKeys`/`createApiKey`/`revokeApiKey` `…/api-keys`, `listPolicies`, `listMcpTools` | +| `client.projects` | `put`/`get` `…/projects/{id}`, `list` `…/projects`, `listDomains` `…/domains` | +| `client.environments` | `list`/`create` `/v1/environments`, `get`/`delete` `…/{env}`, `suspend`/`resume`/`renew`, `connection` (server-side only), `logs` | +| `client.previews` | built on environments: `create`/`list`/`get`/`delete`/`renew` — TTL-swept, `sanitized` by default | +| `client.backups` | `list`/`create` `…/environments/{env}/backups`, `get` `…/projects/{p}/backups/{id}?environment=`, `verify` `…/environments/{env}/backups/{id}/verify`, `restore` `…/backups/{id}/restore` | +| `client.restores` | `start` — restore-shaped form of `backups.restore`; `list`/`get` `…/environments/{env}/restores[/{id}]`, `waitForCompletion` | +| `client.export` | `create` `…/environments/{env}/exports`, `createForProject` `…/projects/{p}/export`, `list` `…/projects/{p}/exports`, `getManifest` `…/exports/{id}`, `downloadUrl`/`download` (signed `…/exports/{id}/download`) | +| `client.migrations` | `run` `…/migrations` — plan → lint → apply | +| `client.imports` | `create`/`dryRun` `/v1/imports`, `history`/`report` `…/imports` | +| `client.usage` | `get` `…/environments/{env}/usage`, `capsNearingLimit`, `billing` `…/organizations/{org}/billing` | +| `client.database` | `tables` `…/database/tables`, `query` `…/database/query` (read-only) | +| `client.queues` | `list`, `peek`, `create`/`send`/`read`/`archive`/`delete`/`purge` | +| `client.functions` | `list`, `deploy`, `invoke` | +| `client.auth` | `listUsers`, `listProviders`, `listPolicies` | +| `client.storage` / `client.realtime` / `client.metrics` / `client.insights` | read surfaces for the console | +| `client.branches` | `list`/`register`/`diff`/`merge`/`linkPullRequest` | +| `client.account` | `get`/`update` (`PATCH`) `/v1/account`, `security`, `revokeSession`/`removeFactor`, `enrollFactor`/`verifyFactor` (TOTP), `challenge` (MFA step-up), `listTokens`/`createToken`/`revokeToken` | +| `client.operations` | `get` `/v1/operations/{id}`, `wait` | +| `client.audit` | `list`, `paginate` over `…/audit-events` | + +## The two money surfaces + +**Verified restore.** Backups become restorable only once the backup worker has +verified them (`status: 'available'`); the control plane refuses anything else. +A restore always lands in a *different* environment, and the finished record +carries its own evidence: relation count, RLS relation count, and the SHA-256 +of the evidence document. + +```ts +import { isRestorable, restoreEvidence } from 'scribase'; + +const production = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; +const [latest] = (await scribase.backups.list(production)).filter(isRestorable); +if (latest) { + // Restore into a scratch preview, never over production, to prove the backup. + const { restore } = await scribase.backups.restore(production, latest.backup_id, 'restore-check'); + console.info(restore.id, restore.status); // 'pending' until the restore worker finishes + const proof = restoreEvidence(restore); // non-null once status === 'restored' +} +``` + +**Runnable export.** No lock-in: assemble a complete, runnable stack with a +signed manifest. The call is synchronous and returns the manifest directly. + +```ts +const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; +const { manifest, bundleRef } = await scribase.export.create(ref, { format: 'compose' }); +// `manifest.artifacts[]` carries per-file sha256; `manifest.signature` signs the +// manifest; `bundleRef` is where the control plane wrote the bundle. +``` + +## Migrate an existing project + +The dry-run is the sales tool: it prints exactly what will move and what won't, +before anything is written. Acceptance is binding — existing users log in +afterward *without resetting passwords*. + +```ts +const source = { + source: 'supabase' as const, + sourceProjectRef: 'abcdefgh', + sourceConnectionString: process.env.SOURCE_DB_URL ?? '', + sourceServiceKey: process.env.SOURCE_SERVICE_KEY ?? '', // sent once, never logged + destination: { organizationId: 'acme', projectId: 'store', environmentId: 'production' }, +}; +const plan = await scribase.imports.dryRun(source); // nothing is written +const report = await scribase.imports.run(source); // starts it in the background, follows progress, returns the verified report +// or: const job = await scribase.imports.createFrom(source); then scribase.imports.progress(job.import_id) +``` + +## Apply migrations safely + +`plan → lint → apply`. A blocking lint finding (`missing_rls`, `public_grant`, +`permissive_policy`, `no_with_check`, `security_definer`) refuses the migration +before a single statement runs. + +```ts +const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; +const result = await scribase.migrations.run(ref, { + migrations: [{ version: '20260921120000', name: 'add_notes', up: 'create table ...' }], + apply: true, +}); +// result.plan, result.lintFindings, result.applied +``` + +## Pagination + +```ts +for await (const event of scribase.audit.paginate('acme', { limit: 200 })) { + console.info(event.sequence, event.action); +} +``` + +## Errors + +Every failure is a typed subclass of `ScribaseError`. API errors carry the +parsed RFC 9457 `problem+json` body: + +```ts +import { ConflictError, QuotaExceededError } from 'scribase'; + +try { + await scribase.environments.create(spec); +} catch (error) { + if (error instanceof QuotaExceededError) { + // buy a capacity pack; retry after error.retryAfterSeconds + } else if (error instanceof ConflictError) { + console.error(error.problem.code, error.requestId); + } +} +``` + +## Regenerating types + +`src/types.gen.ts` is generated; never edit it by hand. `scripts/generate.ts` +reads the `api/openapi.yaml` contract from Scribase's main (private) repo, so +regenerating it is a Scribase-team-only step — it is not needed to build, +test or use this package, since `types.gen.ts` already ships checked in. + +## License + +Apache-2.0. diff --git a/package.json b/package.json new file mode 100644 index 0000000..c72d386 --- /dev/null +++ b/package.json @@ -0,0 +1,65 @@ +{ + "name": "scribase", + "version": "0.3.0", + "description": "The npx scribase CLI and a typed, fetch-based TypeScript client for the Scribase /v1 API: an agent-first, flat-priced application cloud that works with the Supabase client libraries.", + "license": "Apache-2.0", + "type": "module", + "sideEffects": false, + "engines": { + "node": ">=22.13" + }, + "main": "./dist/index.js", + "module": "./dist/index.js", + "types": "./dist/index.d.ts", + "bin": { + "scribase": "./dist/cli/index.js" + }, + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./importers": { + "types": "./dist/importers/index.d.ts", + "import": "./dist/importers/index.js" + } + }, + "files": [ + "dist", + "README.md", + "CHANGELOG.md", + "LICENSE" + ], + "repository": { + "type": "git", + "url": "git+https://github.com/caelum0x/scribase-cli.git" + }, + "homepage": "https://scribase.com", + "bugs": { + "url": "https://github.com/caelum0x/scribase-cli/issues" + }, + "scripts": { + "build": "tsc -p tsconfig.json", + "generate": "tsx scripts/generate.ts", + "typecheck": "tsc -p tsconfig.json --noEmit", + "test": "node --import tsx/esm --test tests/client.test.ts tests/resources.test.ts tests/importers.test.ts tests/cli.test.ts tests/login.test.ts tests/vercel.test.ts tests/front-door.test.ts tests/sql.test.ts tests/migrate.test.ts tests/add.test.ts tests/ota.test.ts tests/connect.test.ts", + "prepublishOnly": "npm run build" + }, + "keywords": [ + "scribase", + "supabase", + "supabase-alternative", + "postgres", + "backend", + "control-plane", + "sdk", + "agent-native" + ], + "dependencies": {}, + "devDependencies": { + "@types/node": "^22.10.0", + "tsx": "^4.19.0", + "typescript": "^5.7.0", + "yaml": "^2.6.0" + } +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml new file mode 100644 index 0000000..653d404 --- /dev/null +++ b/pnpm-lock.yaml @@ -0,0 +1,339 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + devDependencies: + '@types/node': + specifier: ^22.10.0 + version: 22.20.4 + tsx: + specifier: ^4.19.0 + version: 4.23.15 + typescript: + specifier: ^5.7.0 + version: 5.9.3 + yaml: + specifier: ^2.6.0 + version: 2.9.1 + +packages: + + '@esbuild/aix-ppc64@0.28.2': + resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [aix] + + '@esbuild/android-arm64@0.28.2': + resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==} + engines: {node: '>=18'} + cpu: [arm64] + os: [android] + + '@esbuild/android-arm@0.28.2': + resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==} + engines: {node: '>=18'} + cpu: [arm] + os: [android] + + '@esbuild/android-x64@0.28.2': + resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==} + engines: {node: '>=18'} + cpu: [x64] + os: [android] + + '@esbuild/darwin-arm64@0.28.2': + resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [darwin] + + '@esbuild/darwin-x64@0.28.2': + resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==} + engines: {node: '>=18'} + cpu: [x64] + os: [darwin] + + '@esbuild/freebsd-arm64@0.28.2': + resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [freebsd] + + '@esbuild/freebsd-x64@0.28.2': + resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==} + engines: {node: '>=18'} + cpu: [x64] + os: [freebsd] + + '@esbuild/linux-arm64@0.28.2': + resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==} + engines: {node: '>=18'} + cpu: [arm64] + os: [linux] + + '@esbuild/linux-arm@0.28.2': + resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==} + engines: {node: '>=18'} + cpu: [arm] + os: [linux] + + '@esbuild/linux-ia32@0.28.2': + resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==} + engines: {node: '>=18'} + cpu: [ia32] + os: [linux] + + '@esbuild/linux-loong64@0.28.2': + resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==} + engines: {node: '>=18'} + cpu: [loong64] + os: [linux] + + '@esbuild/linux-mips64el@0.28.2': + resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==} + engines: {node: '>=18'} + cpu: [mips64el] + os: [linux] + + '@esbuild/linux-ppc64@0.28.2': + resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [linux] + + '@esbuild/linux-riscv64@0.28.2': + resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==} + engines: {node: '>=18'} + cpu: [riscv64] + os: [linux] + + '@esbuild/linux-s390x@0.28.2': + resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==} + engines: {node: '>=18'} + cpu: [s390x] + os: [linux] + + '@esbuild/linux-x64@0.28.2': + resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==} + engines: {node: '>=18'} + cpu: [x64] + os: [linux] + + '@esbuild/netbsd-arm64@0.28.2': + resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [netbsd] + + '@esbuild/netbsd-x64@0.28.2': + resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==} + engines: {node: '>=18'} + cpu: [x64] + os: [netbsd] + + '@esbuild/openbsd-arm64@0.28.2': + resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openbsd] + + '@esbuild/openbsd-x64@0.28.2': + resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==} + engines: {node: '>=18'} + cpu: [x64] + os: [openbsd] + + '@esbuild/openharmony-arm64@0.28.2': + resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openharmony] + + '@esbuild/sunos-x64@0.28.2': + resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==} + engines: {node: '>=18'} + cpu: [x64] + os: [sunos] + + '@esbuild/win32-arm64@0.28.2': + resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [win32] + + '@esbuild/win32-ia32@0.28.2': + resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==} + engines: {node: '>=18'} + cpu: [ia32] + os: [win32] + + '@esbuild/win32-x64@0.28.2': + resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==} + engines: {node: '>=18'} + cpu: [x64] + os: [win32] + + '@types/node@22.20.4': + resolution: {integrity: sha512-zJRE40jpHtKqE/C4fgHrAKQLJuSpzEnP9ff9Y7YtoR3Wd2pwqzlekDeEuUQXjRd+QCYnVnNwuJYmhdk9XV8gvA==} + + esbuild@0.28.2: + resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==} + engines: {node: '>=18'} + hasBin: true + + fsevents@2.3.3: + resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} + engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} + os: [darwin] + + tsx@4.23.15: + resolution: {integrity: sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==} + engines: {node: '>=18.0.0'} + hasBin: true + + typescript@5.9.3: + resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} + engines: {node: '>=14.17'} + hasBin: true + + undici-types@6.21.0: + resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} + + yaml@2.9.1: + resolution: {integrity: sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==} + engines: {node: '>= 14.6'} + hasBin: true + +snapshots: + + '@esbuild/aix-ppc64@0.28.2': + optional: true + + '@esbuild/android-arm64@0.28.2': + optional: true + + '@esbuild/android-arm@0.28.2': + optional: true + + '@esbuild/android-x64@0.28.2': + optional: true + + '@esbuild/darwin-arm64@0.28.2': + optional: true + + '@esbuild/darwin-x64@0.28.2': + optional: true + + '@esbuild/freebsd-arm64@0.28.2': + optional: true + + '@esbuild/freebsd-x64@0.28.2': + optional: true + + '@esbuild/linux-arm64@0.28.2': + optional: true + + '@esbuild/linux-arm@0.28.2': + optional: true + + '@esbuild/linux-ia32@0.28.2': + optional: true + + '@esbuild/linux-loong64@0.28.2': + optional: true + + '@esbuild/linux-mips64el@0.28.2': + optional: true + + '@esbuild/linux-ppc64@0.28.2': + optional: true + + '@esbuild/linux-riscv64@0.28.2': + optional: true + + '@esbuild/linux-s390x@0.28.2': + optional: true + + '@esbuild/linux-x64@0.28.2': + optional: true + + '@esbuild/netbsd-arm64@0.28.2': + optional: true + + '@esbuild/netbsd-x64@0.28.2': + optional: true + + '@esbuild/openbsd-arm64@0.28.2': + optional: true + + '@esbuild/openbsd-x64@0.28.2': + optional: true + + '@esbuild/openharmony-arm64@0.28.2': + optional: true + + '@esbuild/sunos-x64@0.28.2': + optional: true + + '@esbuild/win32-arm64@0.28.2': + optional: true + + '@esbuild/win32-ia32@0.28.2': + optional: true + + '@esbuild/win32-x64@0.28.2': + optional: true + + '@types/node@22.20.4': + dependencies: + undici-types: 6.21.0 + + esbuild@0.28.2: + optionalDependencies: + '@esbuild/aix-ppc64': 0.28.2 + '@esbuild/android-arm': 0.28.2 + '@esbuild/android-arm64': 0.28.2 + '@esbuild/android-x64': 0.28.2 + '@esbuild/darwin-arm64': 0.28.2 + '@esbuild/darwin-x64': 0.28.2 + '@esbuild/freebsd-arm64': 0.28.2 + '@esbuild/freebsd-x64': 0.28.2 + '@esbuild/linux-arm': 0.28.2 + '@esbuild/linux-arm64': 0.28.2 + '@esbuild/linux-ia32': 0.28.2 + '@esbuild/linux-loong64': 0.28.2 + '@esbuild/linux-mips64el': 0.28.2 + '@esbuild/linux-ppc64': 0.28.2 + '@esbuild/linux-riscv64': 0.28.2 + '@esbuild/linux-s390x': 0.28.2 + '@esbuild/linux-x64': 0.28.2 + '@esbuild/netbsd-arm64': 0.28.2 + '@esbuild/netbsd-x64': 0.28.2 + '@esbuild/openbsd-arm64': 0.28.2 + '@esbuild/openbsd-x64': 0.28.2 + '@esbuild/openharmony-arm64': 0.28.2 + '@esbuild/sunos-x64': 0.28.2 + '@esbuild/win32-arm64': 0.28.2 + '@esbuild/win32-ia32': 0.28.2 + '@esbuild/win32-x64': 0.28.2 + + fsevents@2.3.3: + optional: true + + tsx@4.23.15: + dependencies: + esbuild: 0.28.2 + optionalDependencies: + fsevents: 2.3.3 + + typescript@5.9.3: {} + + undici-types@6.21.0: {} + + yaml@2.9.1: {} diff --git a/scripts/generate.ts b/scripts/generate.ts new file mode 100644 index 0000000..bc4a26b --- /dev/null +++ b/scripts/generate.ts @@ -0,0 +1,176 @@ +/** + * Generate `src/types.gen.ts` from `api/openapi.yaml`. + * + * A focused, dependency-light OpenAPI 3.1 → TypeScript emitter tailored to the + * Scribase management contract: it handles `$ref`, string/integer enums, + * objects with required/optional properties, arrays, scalars, and inline + * response bodies. It is intentionally not a general-purpose codegen — the + * contract is small and stable, and a readable emitter beats a giant dependency. + * + * Usage: `pnpm generate` (or `tsx scripts/generate.ts [openapi.yaml] [out.ts]`). + */ +import { readFileSync, writeFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parse } from 'yaml'; + +interface SchemaNode { + $ref?: string; + type?: string; + enum?: Array; + properties?: Record; + required?: string[]; + items?: SchemaNode; + format?: string; + description?: string; + oneOf?: SchemaNode[]; + anyOf?: SchemaNode[]; +} + +interface OpenApiDoc { + components?: { schemas?: Record }; + paths?: Record>; +} + +interface OperationNode { + operationId?: string; + responses?: Record }>; +} + +const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'patch'] as const; + +function refName(ref: string): string { + const parts = ref.split('/'); + const last = parts[parts.length - 1]; + if (last === undefined || last.length === 0) { + throw new Error(`unresolvable $ref: ${ref}`); + } + return last; +} + +function pascalCase(input: string): string { + return input.replace(/(^|[_-])([a-z])/g, (_, __, ch: string) => ch.toUpperCase()); +} + +/** Render a schema node as a TypeScript type expression. */ +function typeExpr(schema: SchemaNode, indent: string): string { + if (schema.$ref) { + return refName(schema.$ref); + } + // `oneOf`/`anyOf` become a TS union. The contract uses this for nullable + // references (e.g. `ImportVerification | null`), so it must not collapse to + // `unknown` — a caller needs to see that the value can be null. + const variants = schema.oneOf ?? schema.anyOf; + if (variants && variants.length > 0) { + const members = variants.map((variant) => typeExpr(variant, indent)); + return [...new Set(members)].join(' | '); + } + if (schema.enum && schema.enum.length > 0) { + return schema.enum + .map((value) => (typeof value === 'string' ? JSON.stringify(value) : String(value))) + .join(' | '); + } + switch (schema.type) { + case 'null': + return 'null'; + case 'string': + return 'string'; + case 'integer': + case 'number': + return 'number'; + case 'boolean': + return 'boolean'; + case 'array': + return `${typeExpr(schema.items ?? { type: 'string' }, indent)}[]`; + case 'object': + return objectExpr(schema, indent); + default: + return 'unknown'; + } +} + +/** Render an object schema as an inline `{ ... }` type or interface body. */ +function objectExpr(schema: SchemaNode, indent: string): string { + const props = schema.properties ?? {}; + const required = new Set(schema.required ?? []); + const inner = `${indent} `; + const lines = Object.entries(props).map(([name, prop]) => { + const optional = required.has(name) ? '' : '?'; + const doc = prop.description ? `${inner}/** ${prop.description} */\n` : ''; + return `${doc}${inner}${name}${optional}: ${typeExpr(prop, inner)};`; + }); + return `{\n${lines.join('\n')}\n${indent}}`; +} + +/** Emit a top-level named declaration for one component schema. */ +function emitSchema(name: string, schema: SchemaNode): string { + const doc = schema.description ? `/** ${schema.description} */\n` : ''; + if (schema.enum && schema.enum.length > 0 && schema.type !== 'object') { + return `${doc}export type ${name} = ${typeExpr(schema, '')};\n`; + } + if (schema.type === 'object') { + return `${doc}export interface ${name} ${objectExpr(schema, '')}\n`; + } + return `${doc}export type ${name} = ${typeExpr(schema, '')};\n`; +} + +/** Collect inline (non-$ref) object response bodies, named after their op. */ +function emitInlineResponses(paths: OpenApiDoc['paths']): string[] { + if (!paths) { + return []; + } + const out: string[] = []; + for (const item of Object.values(paths)) { + for (const method of HTTP_METHODS) { + const op = item[method]; + if (!op?.operationId || !op.responses) { + continue; + } + for (const [status, response] of Object.entries(op.responses)) { + const schema = response.content?.['application/json']?.schema; + if (!schema || schema.$ref || schema.type !== 'object' || !schema.properties) { + continue; + } + if (status[0] !== '2') { + continue; + } + const name = `${pascalCase(op.operationId)}Response`; + out.push( + `/** Inline ${status} body of \`${op.operationId}\`. */\n` + + `export interface ${name} ${objectExpr(schema, '')}\n`, + ); + } + } + } + return out; +} + +function main(): void { + const here = dirname(fileURLToPath(import.meta.url)); + const inputPath = process.argv[2] ?? resolve(here, '..', '..', '..', 'api', 'openapi.yaml'); + const outputPath = process.argv[3] ?? resolve(here, '..', 'src', 'types.gen.ts'); + + const doc = parse(readFileSync(inputPath, 'utf8')) as OpenApiDoc; + const schemas = doc.components?.schemas ?? {}; + + const header = + '/**\n' + + ' * DO NOT EDIT BY HAND.\n' + + ' *\n' + + ` * Generated from \`api/openapi.yaml\` by \`scripts/generate.ts\`.\n` + + ' * Run `pnpm generate` to refresh after the contract changes.\n' + + ' */\n'; + + const parts: string[] = [header]; + for (const [name, schema] of Object.entries(schemas)) { + parts.push(emitSchema(name, schema)); + } + parts.push(...emitInlineResponses(doc.paths)); + + writeFileSync(outputPath, `${parts.join('\n')}`, 'utf8'); + process.stdout.write( + `Wrote ${Object.keys(schemas).length} schemas to ${outputPath}\n`, + ); +} + +main(); diff --git a/src/cli/add.ts b/src/cli/add.ts new file mode 100644 index 0000000..e3158fc --- /dev/null +++ b/src/cli/add.ts @@ -0,0 +1,433 @@ +/** + * `npx scribase add `: turns a capability on for the project this folder + * is connected to and prints its proof (SP-D1). + * + * npx scribase add email send a proof email to your own address + * npx scribase add email --own use your own mail server (entered in the + * browser, never here) + * npx scribase add --list what can be added, Live or Arriving + * + * The control plane does the work (`POST .../capabilities/{slot}`) and answers + * with `{slot, live, proof:{kind,id,at}}`. When a slot needs a credential, the + * answer is a console link instead: the person enters it there, and this + * command waits for the proof. No secret is read from or written to the + * terminal, the chat, or the env file: only public values are written, and a + * value that looks like a secret is refused by name. + */ + +import { spawn } from 'node:child_process'; +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { dirname } from 'node:path'; + +import { readCredentials } from './credentials.js'; +import { mergeEnv, publicEnvOnly, readEnvValue } from './envfile.js'; +import { InitError, STATE_FILE } from './init.js'; +import { railyardAddHandler } from './capabilities/railyard/index.js'; + +const DEFAULT_API_URL = 'https://api.scribase.com'; +const ENV_FILES = ['.env.local', '.env'] as const; +const DEFAULT_WAIT_SECONDS = 600; +const POLL_MS = 3_000; + +export interface AddOptions { + slot: string | null; + list: boolean; + own: boolean; + resend: boolean; + json: boolean; + wait: boolean; + browser: boolean; + waitSeconds: number; +} + +export interface AddIo { + cwd: string; + env: Record; + fetch: typeof fetch; + readFile: (path: string) => string | null; + writeFile: (path: string, contents: string) => void; + credentials: () => { apiUrl?: string; token?: string }; + sleep: (ms: number) => Promise; + now: () => number; + log: (line: string) => void; + openBrowser: (url: string) => void; +} + +export interface Proof { + kind: string; + id: string; + at: number; + detail?: string | null; +} + +export interface CapabilityState { + slot: string; + title: string; + status: 'live' | 'arriving'; + state: string; + live: boolean; + provider: string | null; + proof: Proof | null; + proof_label?: string; + connect_url: string | null; + next: string | null; + env?: Record; + sent?: boolean; +} + +export interface RegistryEntry { + slot: string; + title: string; + summary: string; + status: 'live' | 'arriving'; +} + +export type AddResult = + | { + ok: true; + slot: string; + status: 'live' | 'needs_connect'; + live: boolean; + provider: string | null; + proof: Proof | null; + sent: boolean; + connect_url?: string; + env_written: string[]; + env_refused: string[]; + next: string | null; + } + | { ok: true; status: 'list'; capabilities: RegistryEntry[] }; + +interface ProjectState { + organization_id: string; + project_id: string; + environment_id: string; + api_url?: string; +} + +const SLOT = /^[a-z][a-z0-9-]{1,31}$/; + +/** Parses `add` arguments. */ +export function parseAddArgs(argv: string[]): AddOptions { + const options: AddOptions = { + slot: null, + list: false, + own: false, + resend: false, + json: false, + wait: true, + browser: true, + waitSeconds: DEFAULT_WAIT_SECONDS, + }; + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index] ?? ''; + if (arg === '--list') options.list = true; + else if (arg === '--own') options.own = true; + else if (arg === '--resend') options.resend = true; + else if (arg === '--json') options.json = true; + else if (arg === '--no-wait') options.wait = false; + else if (arg === '--no-browser') options.browser = false; + else if (arg === '--wait' || arg.startsWith('--wait=')) { + const raw = arg.startsWith('--wait=') ? arg.slice('--wait='.length) : argv[++index]; + const seconds = Number(raw); + if (!Number.isInteger(seconds) || seconds < 1 || seconds > 3_600) { + throw new InitError('invalid_argument', '--wait takes whole seconds from 1 to 3600'); + } + options.waitSeconds = seconds; + } else if (arg.startsWith('--')) { + throw new InitError('invalid_argument', `unknown option ${arg}`, 'run `npx scribase add --help`'); + } else if (options.slot === null) { + if (!SLOT.test(arg)) { + throw new InitError('invalid_argument', `"${arg}" is not a capability name`, 'run `npx scribase add --list`'); + } + options.slot = arg; + } else { + throw new InitError('invalid_argument', `unexpected argument ${arg}`); + } + } + if (!options.list && options.slot === null) { + throw new InitError('invalid_argument', 'no capability given', 'run `npx scribase add email`, or `--list` to see them all'); + } + return options; +} + +function join(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +function readProject(io: AddIo): ProjectState { + const text = io.readFile(join(io.cwd, STATE_FILE)); + let state: Partial | null = null; + try { + state = text ? (JSON.parse(text) as Partial) : null; + } catch { + state = null; + } + if (!state?.organization_id || !state.project_id || !state.environment_id) { + throw new InitError('not_initialized', 'this folder is not connected to a Scribase project', 'run `npx scribase init` here first'); + } + return state as ProjectState; +} + +function findToken(io: AddIo): string | undefined { + const fromEnv = io.env.SCRIBASE_ACCESS_TOKEN?.trim(); + if (fromEnv) return fromEnv; + for (const file of ENV_FILES) { + const contents = io.readFile(join(io.cwd, file)); + const value = contents ? readEnvValue(contents, 'SCRIBASE_ACCESS_TOKEN')?.trim() : undefined; + if (value) return value; + } + return io.credentials().token; +} + +function apiUrlFor(io: AddIo, project?: ProjectState): string { + return (io.env.SCRIBASE_API_URL ?? project?.api_url ?? io.credentials().apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''); +} + +async function call(io: AddIo, url: string, init: { method: 'GET' | 'POST'; token?: string; body?: unknown }): Promise { + const headers: Record = { accept: 'application/json', 'user-agent': 'scribase-add' }; + if (init.token) headers.authorization = `Bearer ${init.token}`; + if (init.body !== undefined) headers['content-type'] = 'application/json'; + let response: Response; + try { + response = await io.fetch(url, { + method: init.method, + headers, + ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}), + }); + } catch (error) { + throw new InitError('network_error', `could not reach the control plane: ${(error as Error).message}`, 'check your connection or SCRIBASE_API_URL'); + } + const text = await response.text(); + let body: unknown = null; + try { + body = text ? JSON.parse(text) : null; + } catch { + body = { detail: text.slice(0, 200) }; + } + if (response.status !== 200) { + const value = (body ?? {}) as { code?: unknown; detail?: unknown }; + const code = typeof value.code === 'string' ? value.code : 'request_failed'; + const detail = typeof value.detail === 'string' ? value.detail : 'the request failed'; + const next = + response.status === 401 || response.status === 403 + ? 'run `npx scribase login` (adding a capability needs an owner or admin)' + : code === 'unknown_capability' || code === 'capability_arriving' + ? 'run `npx scribase add --list`' + : undefined; + throw new InitError(code, `${detail} (HTTP ${response.status})`, next); + } + return body; +} + +function asState(body: unknown): CapabilityState { + const value = (body ?? {}) as Partial; + if (typeof value.slot !== 'string' || typeof value.state !== 'string') { + throw new InitError('invalid_response', 'the control plane answered with an unexpected shape'); + } + return value as CapabilityState; +} + +function capabilityPath(project: ProjectState, slot: string): string { + return ( + `/v1/organizations/${encodeURIComponent(project.organization_id)}` + + `/projects/${encodeURIComponent(project.project_id)}` + + `/environments/${encodeURIComponent(project.environment_id)}` + + `/capabilities/${encodeURIComponent(slot)}` + ); +} + +/** Which env file public values go to: the first one init wrote, else `.env`. */ +function envFileFor(io: AddIo): string { + for (const file of ENV_FILES) { + if (io.readFile(join(io.cwd, file)) !== null) return file; + } + return '.env'; +} + +function writePublicEnv(io: AddIo, values: Record | undefined): { written: string[]; refused: string[] } { + const { safe, refused } = publicEnvOnly(values ?? {}); + const written = Object.keys(safe); + if (written.length > 0) { + const file = join(io.cwd, envFileFor(io)); + io.writeFile(file, mergeEnv(io.readFile(file) ?? '', safe)); + } + return { written, refused }; +} + +/** Runs `add` and returns its result. Never returns or logs a secret. */ +export async function runAdd(options: AddOptions, io: AddIo): Promise { + if (options.list) { + let connected: ProjectState | undefined; + try { + connected = readProject(io); + } catch { + connected = undefined; + } + const body = (await call(io, `${apiUrlFor(io, connected)}/v1/capabilities`, { method: 'GET' })) as { capabilities?: RegistryEntry[] }; + const capabilities = (body.capabilities ?? []).map(({ slot, title, summary, status }) => ({ slot, title, summary, status })); + return { ok: true, status: 'list', capabilities }; + } + const slot = options.slot ?? ''; + // Wave P carve-out (PY lane): a Railyard slot with its own local handler. + const local = railyardAddHandler(slot); + if (local) return local(options, io); + const project = readProject(io); + const token = findToken(io); + if (!token) { + throw new InitError('not_signed_in', 'no Scribase token for this folder', 'run `npx scribase login`, or `npx scribase init` here'); + } + const url = `${apiUrlFor(io, project)}${capabilityPath(project, slot)}`; + const startedAt = Math.floor(io.now() / 1000); + const body: Record = {}; + if (options.own) body.provider = 'own'; + if (options.resend) body.resend = true; + let state = asState(await call(io, url, { method: 'POST', token, body })); + let sent = state.sent === true; + + if (state.state === 'needs_connect' && state.connect_url) { + io.log(`Open this link to finish in the browser (nothing to type here): ${state.connect_url}`); + if (options.browser) io.openBrowser(state.connect_url); + if (!options.wait) { + return { + ok: true, + slot, + status: 'needs_connect', + live: false, + provider: null, + proof: state.proof, + sent: false, + connect_url: state.connect_url, + env_written: [], + env_refused: [], + next: `finish on the connect page, then run \`npx scribase add ${slot}\` again`, + }; + } + const deadline = io.now() + options.waitSeconds * 1_000; + io.log('Waiting for the proof...'); + for (;;) { + await io.sleep(POLL_MS); + state = asState(await call(io, url, { method: 'GET', token })); + if (state.state === 'live' && state.proof && state.proof.at >= startedAt) { + sent = true; + break; + } + if (io.now() >= deadline) { + throw new InitError( + 'connect_timeout', + `no proof arrived within ${options.waitSeconds} s`, + `finish on ${state.connect_url ?? 'the connect page'}, then run \`npx scribase add ${slot}\` again`, + ); + } + } + } + const env = writePublicEnv(io, state.env); + return { + ok: true, + slot, + status: state.state === 'live' ? 'live' : 'needs_connect', + live: state.live, + provider: state.provider, + proof: state.proof, + sent, + ...(state.connect_url ? { connect_url: state.connect_url } : {}), + env_written: env.written, + env_refused: env.refused, + next: state.next, + }; +} + +/** The human-readable output of {@link runAdd}. */ +export function formatAdd(result: AddResult): string { + if (result.status === 'list') { + const lines = ['Capabilities:']; + for (const entry of result.capabilities) { + lines.push(` ${entry.slot.padEnd(12)} ${entry.status === 'live' ? 'Live ' : 'Arriving'} ${entry.summary}`); + } + lines.push('', 'Add one with `npx scribase add `.', ''); + return lines.join('\n'); + } + const lines: string[] = []; + if (result.status === 'live') { + lines.push(`${result.slot} is live${result.provider ? ` (${result.provider === 'own' ? 'your mail server' : 'Scribase'})` : ''}.`); + } else { + lines.push(`${result.slot} is not on yet.`); + } + if (result.proof) { + const when = new Date(result.proof.at * 1000).toISOString(); + const detail = result.proof.detail ? ` to ${result.proof.detail}` : ''; + lines.push(` proof ${result.proof.kind} #${result.proof.id}${detail} at ${when}${result.sent ? ' (just now)' : ''}`); + } + if (result.env_written.length > 0) lines.push(` env wrote ${result.env_written.join(', ')}`); + if (result.env_refused.length > 0) lines.push(` env refused (secret): ${result.env_refused.join(', ')}`); + if (result.connect_url && result.status !== 'live') lines.push(` connect ${result.connect_url}`); + if (result.next) lines.push(` next ${result.next}`); + lines.push(''); + return lines.join('\n'); +} + +export const ADD_HELP = `Usage: npx scribase add [--own] [--resend] [--json] [--no-wait] [--no-browser] [--wait ] + npx scribase add --list [--json] + +Turns a capability on for the project this folder is connected to, and prints +its proof (for email: a real email sent to your own address, with its log id). +A capability that needs a provider credential (--own for your own mail +server) prints a console link: enter the credential there, never here. This +command waits for the proof (up to 10 minutes; --wait to change). Only public +values are written to the env file; secrets are never printed or written. +`; + +/** Entry point for the `add` command; returns the exit code. */ +export async function addMain(argv: string[], io: AddIo, write: (text: string) => void): Promise { + if (argv.includes('--help') || argv.includes('-h')) { + write(ADD_HELP); + return 0; + } + const json = argv.includes('--json'); + try { + const result = await runAdd(parseAddArgs(argv), io); + write(json ? `${JSON.stringify(result)}\n` : formatAdd(result)); + return result.status === 'needs_connect' ? 3 : 0; + } catch (error) { + const failure = + error instanceof InitError + ? { code: error.code, message: error.message, next: error.next ?? null } + : { code: 'unexpected_error', message: (error as Error).message, next: null }; + write(json ? `${JSON.stringify({ ok: false, error: failure })}\n` : `scribase add: ${failure.message}\n${failure.next ? ` next: ${failure.next}\n` : ''}`); + return 1; + } +} + +function openBrowser(url: string): void { + const [command, args] = + process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]]; + try { + spawn(command as string, args as string[], { stdio: 'ignore', detached: true }).unref(); + } catch { + // The link is printed anyway. + } +} + +/** The real-process IO for `add`. In --json mode stdout carries one JSON document; notes go to stderr. */ +export function nodeAddIo(json: boolean): AddIo { + return { + cwd: process.cwd(), + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null), + writeFile: (path, contents) => { + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, contents, { mode: 0o600 }); + }, + credentials: () => readCredentials(process.env), + sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)), + now: () => Date.now(), + log: (line) => (json ? process.stderr.write(`${line}\n`) : process.stdout.write(`${line}\n`)), + openBrowser, + }; +} + +/** `npx scribase add ...` as the CLI runs it (the one line \`index.ts\` needs). */ +export function addCommand(argv: string[]): Promise { + return addMain(argv, nodeAddIo(argv.includes('--json')), (text) => process.stdout.write(text)); +} diff --git a/src/cli/aliases.ts b/src/cli/aliases.ts new file mode 100644 index 0000000..53039ad --- /dev/null +++ b/src/cli/aliases.ts @@ -0,0 +1,13 @@ +/** + * Command aliases of the `scribase` npm binary (Wave P PS2.0, hand-off P-Y4). + * + * `npx scribase deploy [...]` is `npx scribase add deploy [...]`: the Railyard + * deploy slot, which links on first use and then deploys this folder. + */ + +/** The argv the CLI runs for `argv`, with an alias expanded. */ +export function expandAlias(argv: readonly string[]): string[] { + const [command, ...rest] = argv; + if (command === 'deploy') return ['add', 'deploy', ...rest]; + return [...argv]; +} diff --git a/src/cli/capabilities/ota.ts b/src/cli/capabilities/ota.ts new file mode 100644 index 0000000..7b779c5 --- /dev/null +++ b/src/cli/capabilities/ota.ts @@ -0,0 +1,373 @@ +/** + * `npx scribase ota `: over-the-air updates for the + * app in this folder (PS3.1), on the project `npx scribase init` connected. + * + * npx scribase ota deploy -p ios [-c production] [-m "message"] [-r 25] + * npx scribase ota rollback -p android [-c production] + * npx scribase ota status + * + * `deploy` sets OTA up on the environment when it is not yet (the schema, the + * private bucket and the update-check function), writes `hot-updater.config.ts` + * when the folder has none, then runs the unmodified `hot-updater deploy` CLI + * (MIT) with the environment's URL and secret key in the child process only: + * the key is never printed, logged or written to a file. The update URL the + * app reads (`EXPO_PUBLIC_HOT_UPDATER_URL`) is written to the env file, a + * public value. After the upload it reads the release back as proof. + */ +import { spawn } from 'node:child_process'; +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { dirname } from 'node:path'; + +import { readCredentials } from '../credentials.js'; + +import { mergeEnv, publicEnvOnly, readEnvValue } from '../envfile.js'; +import { InitError, STATE_FILE } from '../init.js'; + +const DEFAULT_API_URL = 'https://api.scribase.com'; +const ENV_FILES = ['.env.local', '.env'] as const; +export const CONFIG_FILE = 'hot-updater.config.ts'; +export const BUCKET = 'ota-bundles'; +/** The hot-updater CLI, pinned to the protocol the update-check function speaks. */ +export const HOT_UPDATER_CLI = ['npx', '--yes', 'hot-updater@0.36.16'] as const; + +export type Platform = 'ios' | 'android'; + +export interface OtaOptions { + action: 'deploy' | 'rollback' | 'status'; + platform: Platform | null; + channel: string; + /** Extra `hot-updater deploy` flags, passed through as written. */ + passthrough: string[]; + json: boolean; +} + +export interface OtaIo { + cwd: string; + env: Record; + fetch: typeof fetch; + readFile: (path: string) => string | null; + writeFile: (path: string, contents: string) => void; + credentials: () => { apiUrl?: string; token?: string }; + log: (line: string) => void; + /** Runs a command; resolves with its exit code. `env` holds extra variables. */ + run: (command: string, args: string[], env: Record) => Promise; +} + +export interface Release { + id: string; + platform: Platform; + channel: string; + target_app_version: string | null; + fingerprint_hash: string | null; + enabled: boolean; + force_update: boolean; + rollout_percent: number; + message: string | null; + created_at_epoch_seconds: number; +} + +export interface OtaStatus { + enabled: boolean; + conflict: boolean; + update_url: string | null; + bucket: string; + releases: number; + latest: Release[]; +} + +export type OtaResult = + | { ok: true; action: 'status'; status: OtaStatus } + | { ok: true; action: 'rollback'; turned_off: string; now_serving: string | null; platform: Platform; channel: string } + | { ok: true; action: 'deploy'; release: Release | null; set_up: boolean; config_written: boolean; env_written: string[] }; + +const CHANNEL = /^[A-Za-z0-9._-]{1,64}$/; + +/** Parses `ota` arguments. */ +export function parseOtaArgs(argv: string[]): OtaOptions { + const [action, ...rest] = argv; + if (action !== 'deploy' && action !== 'rollback' && action !== 'status') { + throw new InitError('invalid_argument', 'say what to do: deploy, rollback or status', 'run `npx scribase ota deploy -p ios`'); + } + let platform: Platform | null = null; + let channel = 'production'; + let json = false; + const passthrough: string[] = []; + for (let index = 0; index < rest.length; index += 1) { + const arg = rest[index] ?? ''; + const value = () => { + const next = rest[index + 1]; + if (next === undefined || next.startsWith('-')) throw new InitError('invalid_argument', `${arg} needs a value`); + index += 1; + return next; + }; + if (arg === '-p' || arg === '--platform') { + const chosen = value(); + if (chosen !== 'ios' && chosen !== 'android') throw new InitError('invalid_argument', 'platform must be ios or android'); + platform = chosen; + } else if (arg === '-c' || arg === '--channel') { + channel = value(); + if (!CHANNEL.test(channel)) throw new InitError('invalid_argument', 'channel must be letters, digits, ".", "_" or "-"'); + } else if (arg === '--json') { + json = true; + } else if (action === 'deploy' && ['-m', '--message', '-r', '--rollout', '-t', '--target-app-version'].includes(arg)) { + passthrough.push(arg, value()); + } else if (action === 'deploy' && ['-f', '--force-update', '-d', '--disabled'].includes(arg)) { + passthrough.push(arg); + } else { + throw new InitError('invalid_argument', `unknown option ${arg}`, 'run `npx scribase ota --help`'); + } + } + if (action !== 'status' && !platform) { + throw new InitError('invalid_argument', `ota ${action} needs a platform`, `run \`npx scribase ota ${action} -p ios\` (or android)`); + } + return { action, platform, channel, passthrough, json }; +} + +/** The config the hot-updater CLI reads, for an Expo app on Scribase. */ +export const CONFIG_TEMPLATE = `import { expo } from '@hot-updater/expo'; +import { supabaseDatabase, supabaseStorage } from '@hot-updater/supabase'; +import { defineConfig } from 'hot-updater'; + +// Over-the-air updates stored in your Scribase project. \`npx scribase ota deploy\` +// sets HOT_UPDATER_SUPABASE_URL and the secret key for the upload only; never +// put the secret key in this file or in your app. +const supabaseUrl = process.env.HOT_UPDATER_SUPABASE_URL!; +const supabaseServiceRoleKey = process.env.HOT_UPDATER_SUPABASE_SERVICE_ROLE_KEY!; + +export default defineConfig({ + build: expo(), + storage: supabaseStorage({ supabaseUrl, supabaseServiceRoleKey, bucketName: '${BUCKET}' }), + database: supabaseDatabase({ supabaseUrl, supabaseServiceRoleKey }), + updateStrategy: 'appVersion', +}); +`; + +interface ProjectState { + organization_id: string; + project_id: string; + environment_id: string; + api_url?: string; +} + +const joinPath = (root: string, relative: string) => `${root.replace(/\/+$/, '')}/${relative}`; + +function readProject(io: OtaIo): ProjectState { + const text = io.readFile(joinPath(io.cwd, STATE_FILE)); + let state: Partial | null = null; + try { + state = text ? (JSON.parse(text) as Partial) : null; + } catch { + state = null; + } + if (!state?.organization_id || !state.project_id || !state.environment_id) { + throw new InitError('not_initialized', 'this folder is not connected to a Scribase project', 'run `npx scribase init` here first'); + } + return state as ProjectState; +} + +function findToken(io: OtaIo): string | undefined { + const fromEnv = io.env.SCRIBASE_ACCESS_TOKEN?.trim(); + if (fromEnv) return fromEnv; + for (const file of ENV_FILES) { + const contents = io.readFile(joinPath(io.cwd, file)); + const value = contents ? readEnvValue(contents, 'SCRIBASE_ACCESS_TOKEN')?.trim() : undefined; + if (value) return value; + } + return io.credentials().token; +} + +type Call = (method: 'GET' | 'POST', suffix: string, body?: unknown) => Promise; + +function client(io: OtaIo, project: ProjectState): { call: Call; environmentPath: string } { + const token = findToken(io); + if (!token) throw new InitError('not_signed_in', 'no Scribase token for this folder', 'run `npx scribase login`'); + const apiUrl = (io.env.SCRIBASE_API_URL ?? project.api_url ?? io.credentials().apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''); + const environmentPath = + `/v1/organizations/${encodeURIComponent(project.organization_id)}` + + `/projects/${encodeURIComponent(project.project_id)}` + + `/environments/${encodeURIComponent(project.environment_id)}`; + const call: Call = async (method, suffix, body) => { + let response: Response; + try { + response = await io.fetch(`${apiUrl}${environmentPath}${suffix}`, { + method, + headers: { + accept: 'application/json', + authorization: `Bearer ${token}`, + 'user-agent': 'scribase-ota', + ...(body === undefined ? {} : { 'content-type': 'application/json' }), + }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }), + }); + } catch (error) { + throw new InitError('network_error', `could not reach ${apiUrl}: ${(error as Error).message}`); + } + const text = await response.text(); + let parsed: unknown = null; + try { + parsed = text ? JSON.parse(text) : null; + } catch { + parsed = null; + } + if (!response.ok) { + const value = (parsed ?? {}) as { code?: unknown; detail?: unknown }; + throw new InitError( + typeof value.code === 'string' ? value.code : 'request_failed', + `${typeof value.detail === 'string' ? value.detail : 'the request failed'} (HTTP ${response.status})`, + response.status === 401 || response.status === 403 ? 'run `npx scribase login`' : undefined, + ); + } + return parsed; + }; + return { call, environmentPath }; +} + +function envFile(io: OtaIo): string { + for (const file of ENV_FILES) { + if (io.readFile(joinPath(io.cwd, file)) !== null) return joinPath(io.cwd, file); + } + return joinPath(io.cwd, '.env'); +} + +async function deploy(options: OtaOptions, io: OtaIo, call: Call): Promise { + let status = (await call('GET', '/ota')) as OtaStatus; + let setUp = false; + if (status.conflict) { + throw new InitError('ota_table_conflict', 'this database has its own public.bundles table; OTA updates need that name', 'rename your table, then run this again'); + } + if (!status.enabled) { + io.log('Setting up over-the-air updates in this environment...'); + status = (await call('POST', '/ota')) as OtaStatus; + setUp = true; + } + const keys = (await call('GET', '/api-keys')) as { api_url?: string; secret_key?: string | null; service_role_key?: string | null }; + const secret = keys.secret_key ?? keys.service_role_key; + if (!keys.api_url || !secret) { + throw new InitError('forbidden', 'your role cannot read this environment\'s secret key, which the upload needs', 'ask an owner, admin or developer to run the deploy'); + } + const configPath = joinPath(io.cwd, CONFIG_FILE); + const configWritten = io.readFile(configPath) === null; + if (configWritten) io.writeFile(configPath, CONFIG_TEMPLATE); + const envWritten: string[] = []; + if (status.update_url) { + const { safe } = publicEnvOnly({ EXPO_PUBLIC_HOT_UPDATER_URL: status.update_url }); + const file = envFile(io); + const current = io.readFile(file) ?? ''; + if (readEnvValue(current, 'EXPO_PUBLIC_HOT_UPDATER_URL') !== status.update_url) { + io.writeFile(file, mergeEnv(current, safe)); + envWritten.push(...Object.keys(safe)); + } + } + const [command, ...prefix] = HOT_UPDATER_CLI; + const args = [...prefix, 'deploy', '-p', options.platform as Platform, '-c', options.channel, ...options.passthrough]; + const code = await io.run(command, args, { + HOT_UPDATER_SUPABASE_URL: keys.api_url.replace(/\/+$/, ''), + HOT_UPDATER_SUPABASE_SERVICE_ROLE_KEY: secret, + HOT_UPDATER_SUPABASE_BUCKET_NAME: BUCKET, + }); + if (code !== 0) { + throw new InitError('deploy_failed', `hot-updater deploy exited with code ${code}`, 'read its output above; nothing was published if it failed before the upload'); + } + const after = (await call('GET', '/ota')) as OtaStatus; + const release = after.latest.find((entry) => entry.platform === options.platform && entry.channel === options.channel) ?? null; + return { ok: true, action: 'deploy', release, set_up: setUp, config_written: configWritten, env_written: envWritten }; +} + +/** Runs one `ota` action against this folder's project. */ +export async function runOta(options: OtaOptions, io: OtaIo): Promise { + const { call } = client(io, readProject(io)); + if (options.action === 'status') return { ok: true, action: 'status', status: (await call('GET', '/ota')) as OtaStatus }; + if (options.action === 'rollback') { + const answer = (await call('POST', '/ota/rollback', { platform: options.platform, channel: options.channel })) as { + turned_off: string; + now_serving: string | null; + }; + return { ok: true, action: 'rollback', turned_off: answer.turned_off, now_serving: answer.now_serving, platform: options.platform as Platform, channel: options.channel }; + } + return deploy(options, io, call); +} + +const describe = (release: Release) => + `${release.platform} ${release.channel}: ${release.id} (${release.enabled ? `on for ${release.rollout_percent}% of devices` : 'off'}${ + release.target_app_version ? `, app ${release.target_app_version}` : '' + })`; + +/** Human output. */ +export function formatOta(result: OtaResult): string { + if (result.action === 'status') { + const status = result.status; + if (!status.enabled) { + return status.conflict + ? 'OTA updates are not set up: this database has its own public.bundles table.\n' + : 'OTA updates are not set up yet. Run `npx scribase ota deploy -p ios` to set them up and publish.\n'; + } + const lines = [`OTA updates are on. Update URL: ${status.update_url ?? 'unknown'}`, `${status.releases} release(s).`]; + for (const release of status.latest) lines.push(` ${describe(release)}`); + return `${lines.join('\n')}\n`; + } + if (result.action === 'rollback') { + const target = result.now_serving ? `release ${result.now_serving}` : "the bundle built into the app"; + return `Turned off ${result.turned_off}. ${result.platform} devices on ${result.channel} go back to ${target} on their next launch.\n`; + } + const lines: string[] = []; + if (result.set_up) lines.push('Set up over-the-air updates in this environment.'); + if (result.config_written) lines.push(`Wrote ${CONFIG_FILE}.`); + if (result.env_written.length) lines.push(`Wrote ${result.env_written.join(', ')} to your env file.`); + lines.push(result.release ? `Published. ${describe(result.release)}` : 'Published; the release will show in `npx scribase ota status`.'); + lines.push('Installed builds take it on their next launch.'); + return `${lines.join('\n')}\n`; +} + +export const OTA_HELP = `Usage: npx scribase ota [options] + + deploy -p set OTA up if needed, then publish this app's JavaScript + -c channel (default production) + -m release message + -r share of devices that get it (default 100) + -t app versions it targets, e.g. 1.x.x + -f force the update + rollback -p turn off the newest release; devices go back to the one before + status what is published +`; + +/** The default IO: real fetch, files and child processes. */ +export function nodeOtaIo(json: boolean): OtaIo { + const cwd = process.cwd(); + return { + cwd, + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null), + writeFile: (path, contents) => { + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, contents, { mode: 0o600 }); + }, + credentials: () => readCredentials(process.env), + log: (line) => (json ? process.stderr.write(`${line}\n`) : process.stdout.write(`${line}\n`)), + run: (command, args, env) => + new Promise((resolve) => { + const child = spawn(command, args, { cwd, env: { ...process.env, ...env }, stdio: ['inherit', json ? 'ignore' : 'inherit', 'inherit'] }); + child.on('error', () => resolve(127)); + child.on('close', (code) => resolve(code ?? 1)); + }), + }; +} + +/** `ota` entry: parses, runs, prints. Returns the exit code. */ +export async function otaMain(argv: string[], io: OtaIo, write: (text: string) => void): Promise { + if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) { + write(OTA_HELP); + return argv.length === 0 ? 1 : 0; + } + let options: OtaOptions; + try { + options = parseOtaArgs(argv); + const result = await runOta(options, io); + write(options.json ? `${JSON.stringify(result)}\n` : formatOta(result)); + return 0; + } catch (error) { + const failure = error instanceof InitError ? error : new InitError('unexpected', (error as Error).message); + write(`scribase ota: ${failure.message}${failure.next ? `\n next: ${failure.next}` : ''}\n`); + return 1; + } +} diff --git a/src/cli/capabilities/railyard/ai.ts b/src/cli/capabilities/railyard/ai.ts new file mode 100644 index 0000000..900bbf5 --- /dev/null +++ b/src/cli/capabilities/railyard/ai.ts @@ -0,0 +1,43 @@ +/** + * `npx scribase add ai` (Wave P PY1.4): the project's gateway key goes + * straight to the environment's secrets (`AI_GATEWAY_KEY`, read by functions + * at run time); only the public `AI_GATEWAY_URL` reaches the env file. The + * customer connects their own AI provider on a one-time page opened in the + * browser (nothing typed here), and this command waits for it. Their provider + * bills them directly. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { InitError } from '../../init.js'; +import type { SlotAnswer, SlotContext } from './index.js'; + +const POLL_MS = 3_000; + +type ReadSlot = (io: AddIo, ctx: SlotContext) => Promise; + +function toSeconds(at: string | number): number { + return typeof at === 'number' ? at : Math.floor(Date.parse(at) / 1000); +} + +export async function aiConnect(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext, readSlot: ReadSlot): Promise { + if (result.status === 'list') return result; + if (ctx.answer.state === 'live' && ctx.answer.proof) return result; + const link = ctx.answer.connect_url; + if (!link || !/^https?:\/\//.test(link)) throw new InitError('invalid_response', 'the control plane did not return a connect link'); + io.log(`Connect your AI provider in the browser (nothing to type here): ${link}`); + if (options.browser) io.openBrowser(link); + if (!options.wait) { + return { ...result, status: 'needs_connect', live: false, connect_url: link, next: 'connect a provider on the page, then run `npx scribase add ai` again' }; + } + io.log('Waiting for the connection...'); + const deadline = io.now() + options.waitSeconds * 1_000; + for (;;) { + await io.sleep(POLL_MS); + const state = await readSlot(io, ctx); + if (state.state === 'live' && state.proof) { + return { ...result, live: true, proof: { kind: state.proof.kind, id: state.proof.id, at: toSeconds(state.proof.at) }, sent: true, next: null }; + } + if (io.now() >= deadline) { + throw new InitError('connect_timeout', `no provider was connected within ${options.waitSeconds} s`, 'open the link again from `npx scribase add ai`'); + } + } +} diff --git a/src/cli/capabilities/railyard/analytics.ts b/src/cli/capabilities/railyard/analytics.ts new file mode 100644 index 0000000..afdd03f --- /dev/null +++ b/src/cli/capabilities/railyard/analytics.ts @@ -0,0 +1,99 @@ +/** + * `npx scribase add analytics` (Wave P PY1.3): the control plane creates this + * project environment's analytics site and answers with its public values, + * which go to the env file (the site key ships in the page, like an anon + * key). Then, results first: this machine sends one proof event to the + * collector, and the command waits (up to 60 s) until the Analytics tab + * shows it. The proof is that first event. + * + * Wave Q QY1.2: the answer also carries the product analytics host and the + * project's public key (`*_ANALYTICS_HOST`, `*_ANALYTICS_KEY`). The command + * then sends the check event to product analytics too, in its capture + * protocol, so an app that only uses the SDK sees its first product event in + * the Analytics tab; whichever arrives first is the proof. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { InitError } from '../../init.js'; +import type { SlotAnswer, SlotContext } from './index.js'; + +export const PROOF_EVENT = 'scribase_proof'; +export const WAIT_MS = 60_000; +const POLL_MS = 3_000; + +type ReadSlot = (io: AddIo, ctx: SlotContext) => Promise; + +function toSeconds(at: string | number): number { + return typeof at === 'number' ? at : Math.floor(Date.parse(at) / 1000); +} + +/** The page tag to put in the app's HTML head. */ +export function pageTag(scriptUrl: string, siteKey: string): string { + return ``; +} + +/** The check event in the product analytics capture protocol (QY1.2). */ +export function productCheckEvent(key: string, at: number): Record { + return { + api_key: key, + event: PROOF_EVENT, + distinct_id: 'scribase-cli', + timestamp: new Date(at).toISOString(), + properties: { $lib: 'scribase-cli', $current_url: 'https://scribase.local/scribase/add-analytics', $pathname: '/scribase/add-analytics', $process_person_profile: false }, + }; +} + +async function post(io: AddIo, url: string, init: RequestInit, what: string): Promise { + let sent: Response; + try { + sent = await io.fetch(url, init); + } catch (error) { + throw new InitError('network_error', `could not reach ${what}: ${(error as Error).message}`); + } + if (sent.status >= 400) throw new InitError('proof_refused', `${what} refused the check event (HTTP ${sent.status})`); +} + +/** Sends one proof event the way the page tag does (and the way the SDK does), then waits for it to show. */ +export async function analyticsProof(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext, readSlot: ReadSlot): Promise { + if (result.status !== 'live') return result; + if (ctx.answer.state === 'live' && ctx.answer.proof) return result; + const env = ctx.answer.env ?? {}; + const site = env.NEXT_PUBLIC_ANALYTICS_SITE ?? env.VITE_ANALYTICS_SITE ?? env.EXPO_PUBLIC_ANALYTICS_SITE; + const collector = env.ANALYTICS_COLLECTOR_URL; + const host = env.NEXT_PUBLIC_ANALYTICS_HOST ?? env.VITE_ANALYTICS_HOST ?? env.EXPO_PUBLIC_ANALYTICS_HOST; + const key = env.NEXT_PUBLIC_ANALYTICS_KEY ?? env.VITE_ANALYTICS_KEY ?? env.EXPO_PUBLIC_ANALYTICS_KEY ?? site; + if (!site || (!collector && !host)) { + throw new InitError('invalid_response', 'the control plane did not return the analytics site'); + } + if (env.ANALYTICS_SCRIPT_URL) io.log(`Page tag for your app's : ${pageTag(env.ANALYTICS_SCRIPT_URL, site)}`); + if (host) io.log(`Product analytics: send events to ${host} with the key in ${env.NEXT_PUBLIC_ANALYTICS_KEY ? 'NEXT_PUBLIC_ANALYTICS_KEY' : env.VITE_ANALYTICS_KEY ? 'VITE_ANALYTICS_KEY' : 'EXPO_PUBLIC_ANALYTICS_KEY'}.`); + const started = Math.floor(io.now() / 1000); + if (collector) { + const payload = { type: 'event', payload: { website: site, url: '/scribase/add-analytics', hostname: 'scribase.local', name: PROOF_EVENT, title: 'Analytics check', language: 'en', screen: '0x0' } }; + await post( + io, + `${collector.replace(/\/+$/, '')}/api/send`, + { method: 'POST', headers: { 'content-type': 'text/plain', 'user-agent': 'Scribase CLI (analytics check)' }, body: JSON.stringify(payload) }, + 'the collector', + ); + } + if (host && key) { + await post( + io, + `${host.replace(/\/+$/, '')}/capture/`, + { method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'Scribase CLI (analytics check)' }, body: JSON.stringify(productCheckEvent(key, io.now())) }, + 'product analytics', + ); + } + io.log('Sent one check event; waiting for it to arrive...'); + const deadline = io.now() + (options.wait ? WAIT_MS : 0); + for (;;) { + const state = await readSlot(io, ctx); + if (state.state === 'live' && state.proof && toSeconds(state.proof.at) >= started - 5) { + return { ...result, live: true, proof: { kind: state.proof.kind, id: state.proof.id, at: toSeconds(state.proof.at) }, sent: true, next: null }; + } + if (io.now() >= deadline) { + return { ...result, next: 'The check event is on its way; it shows in the Analytics tab shortly.' }; + } + await io.sleep(POLL_MS); + } +} diff --git a/src/cli/capabilities/railyard/billing.ts b/src/cli/capabilities/railyard/billing.ts new file mode 100644 index 0000000..7c046c0 --- /dev/null +++ b/src/cli/capabilities/railyard/billing.ts @@ -0,0 +1,49 @@ +/** + * `npx scribase add billing` (Wave P PY2.3): opens the one-time connect page + * in the browser, where the customer connects their own payment account (no + * key is typed here), and waits for the connection. Buyers then pay the + * customer's account directly; each purchase becomes a row in + * billing.entitlements of this environment. The proof is the first test + * purchase, made from the Billing tab. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { InitError } from '../../init.js'; +import type { SlotAnswer, SlotContext } from './index.js'; + +const POLL_MS = 3_000; + +type ReadSlot = (io: AddIo, ctx: SlotContext) => Promise; + +function toSeconds(at: string | number): number { + return typeof at === 'number' ? at : Math.floor(Date.parse(at) / 1000); +} + +export async function billingConnect(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext, readSlot: ReadSlot): Promise { + if (result.status !== 'live') return result; + if (ctx.answer.state === 'live' && ctx.answer.proof) return result; + if (ctx.answer.state === 'no_proof_yet') { + return { ...result, next: 'Connected. Add a product and make one test purchase in Environment > Add-ons > Billing.' }; + } + const link = ctx.answer.connect_url; + if (!link || !/^https?:\/\//.test(link)) throw new InitError('invalid_response', 'the control plane did not return a connect link'); + io.log(`Connect your payment account in the browser (nothing to type here): ${link}`); + if (options.browser) io.openBrowser(link); + if (!options.wait) { + return { ...result, status: 'needs_connect', live: false, connect_url: link, next: 'connect your account on the page, then run `npx scribase add billing` again' }; + } + io.log('Waiting for the connection...'); + const deadline = io.now() + options.waitSeconds * 1_000; + for (;;) { + await io.sleep(POLL_MS); + const state = await readSlot(io, ctx); + if (state.state === 'live' && state.proof) { + return { ...result, live: true, proof: { kind: state.proof.kind, id: state.proof.id, at: toSeconds(state.proof.at) }, sent: true, next: null }; + } + if (state.state === 'no_proof_yet') { + return { ...result, next: 'Connected. Add a product and make one test purchase in Environment > Add-ons > Billing.' }; + } + if (io.now() >= deadline) { + throw new InitError('connect_timeout', `no account was connected within ${options.waitSeconds} s`, 'open the link again from `npx scribase add billing`'); + } + } +} diff --git a/src/cli/capabilities/railyard/consent-files.ts b/src/cli/capabilities/railyard/consent-files.ts new file mode 100644 index 0000000..19ada9c --- /dev/null +++ b/src/cli/capabilities/railyard/consent-files.ts @@ -0,0 +1,34 @@ +/** + * The consent templates `npx scribase add consent` copies into an app (Wave + * P PY2.5). Generated from `templates/consent/**`; railyard.test.mjs checks + * they stay byte-identical. Do not edit here: edit the template and copy. + */ + +export interface TemplateFile { + /** Where it goes in the app folder. */ + path: string; + /** The repository template it comes from. */ + template: string; + /** Only for Next.js apps. */ + next?: boolean; + contents: string; +} + +export const CONSENT_FILES: readonly TemplateFile[] = Object.freeze([ + { + path: "consent/consent-core.js", + template: "templates/consent/web/consent-core.js", + contents: "// Consent for your app (Scribase, the consent slot; Wave P PY2.5). No\n// dependencies. Categories follow the common consent-manager names\n// (necessary, measurement, marketing, functionality, experience), so another\n// banner can replace this one later without changing your checks.\n//\n// const consent = createConsent({ supabaseUrl, anonKey, policyVersion: '1' });\n// consent.allowed('measurement') // false until the person agrees\n// await consent.decide({ measurement: true, marketing: false });\n//\n// Every decision is stored on this device and added, with its time and the\n// policy version, to the insert-only consent_records table of your project.\n\nexport const CATEGORIES = ['necessary', 'measurement', 'marketing', 'functionality', 'experience'];\nconst STORE_KEY = 'scribase-consent';\n\nfunction randomId() {\n const bytes = new Uint8Array(16);\n globalThis.crypto.getRandomValues(bytes);\n return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n}\n\nexport function createConsent({ supabaseUrl, anonKey, policyVersion = '1', storage = globalThis.localStorage, fetchImpl = globalThis.fetch?.bind(globalThis), source = 'web' } = {}) {\n if (!supabaseUrl || !anonKey) throw new Error('createConsent needs supabaseUrl and anonKey');\n const read = () => {\n try {\n const saved = JSON.parse(storage?.getItem(STORE_KEY) ?? 'null');\n return saved && saved.version === policyVersion ? saved : null;\n } catch {\n return null;\n }\n };\n let state = read();\n const listeners = new Set();\n const subject = () => {\n let id = null;\n try {\n id = storage?.getItem(`${STORE_KEY}:subject`) ?? null;\n if (!id) {\n id = randomId();\n storage?.setItem(`${STORE_KEY}:subject`, id);\n }\n } catch {\n id = id ?? randomId();\n }\n return id;\n };\n return {\n /** Whether the person decided under the current policy version. */\n decided: () => state !== null,\n /** `necessary` is always allowed; everything else only after a yes. */\n allowed: (category) => category === 'necessary' || state?.choices?.[category] === true,\n current: () => (state ? { ...state.choices } : null),\n subscribe(listener) {\n listeners.add(listener);\n return () => listeners.delete(listener);\n },\n /** Saves the choice here and records it in your project. Resolves true when recorded. */\n async decide(choices) {\n const clean = Object.fromEntries(CATEGORIES.map((c) => [c, c === 'necessary' ? true : choices?.[c] === true]));\n state = { version: policyVersion, choices: clean, at: new Date().toISOString() };\n try {\n storage?.setItem(STORE_KEY, JSON.stringify(state));\n } catch {\n // Private mode: the choice holds for this page.\n }\n for (const l of listeners) l({ ...clean });\n if (!fetchImpl) return false;\n try {\n const res = await fetchImpl(`${supabaseUrl.replace(/\\/+$/, '')}/rest/v1/consent_records`, {\n method: 'POST',\n headers: { apikey: anonKey, authorization: `Bearer ${anonKey}`, 'content-type': 'application/json', prefer: 'return=minimal' },\n body: JSON.stringify({ subject_id: subject(), choices: clean, policy_version: policyVersion, source }),\n });\n return res.ok;\n } catch {\n return false;\n }\n },\n };\n}\n\n/**\n * Loads the analytics page tag only once measurement is allowed. Before that\n * (and after a no) no analytics request leaves the browser: the script is\n * never added to the page.\n */\nexport function loadAnalyticsWhenAllowed(consent, { scriptUrl, site, doc = globalThis.document }) {\n let loaded = false;\n const load = () => {\n if (loaded || !consent.allowed('measurement') || !doc) return;\n loaded = true;\n const s = doc.createElement('script');\n s.defer = true;\n s.src = scriptUrl;\n s.setAttribute('data-site', site);\n doc.head.appendChild(s);\n };\n load();\n const stop = consent.subscribe(load);\n return () => stop();\n}\n", + }, + { + path: "consent/banner.js", + template: "templates/consent/web/banner.js", + contents: "// A plain consent banner for any web page (Scribase, the consent slot).\n// Include after consent-core.js; it shows once, until the person decides.\n//\n// \n\nexport function showBanner(consent, { privacyUrl = '/privacy', doc = globalThis.document, text = {} } = {}) {\n if (!doc || consent.decided()) return null;\n const t = {\n body: 'We use cookies and similar tools to measure how the app is used. Choose what you allow.',\n accept: 'Allow all',\n reject: 'Only necessary',\n privacy: 'Privacy',\n ...text,\n };\n const box = doc.createElement('div');\n box.setAttribute('role', 'dialog');\n box.setAttribute('aria-label', 'Consent');\n box.style.cssText = 'position:fixed;left:16px;right:16px;bottom:16px;max-width:560px;margin:0 auto;padding:16px;border-radius:12px;background:#fff;color:#1b1f24;box-shadow:0 8px 30px rgba(0,0,0,.15);font:14px/1.5 system-ui,sans-serif;z-index:2147483000';\n const p = doc.createElement('p');\n p.textContent = `${t.body} `;\n const link = doc.createElement('a');\n link.href = privacyUrl;\n link.textContent = t.privacy;\n p.appendChild(link);\n const row = doc.createElement('div');\n row.style.cssText = 'display:flex;gap:8px;justify-content:flex-end;margin-top:8px';\n const button = (label, primary, choices) => {\n const b = doc.createElement('button');\n b.type = 'button';\n b.textContent = label;\n b.style.cssText = `padding:8px 14px;border-radius:8px;border:1px solid #1b1f24;cursor:pointer;${primary ? 'background:#1b1f24;color:#fff' : 'background:#fff;color:#1b1f24'}`;\n b.addEventListener('click', () => {\n box.remove();\n void consent.decide(choices);\n });\n return b;\n };\n row.appendChild(button(t.reject, false, {}));\n row.appendChild(button(t.accept, true, { measurement: true, marketing: true, functionality: true, experience: true }));\n box.appendChild(p);\n box.appendChild(row);\n doc.body.appendChild(box);\n return box;\n}\n", + }, + { + path: "components/ConsentBanner.tsx", + template: "templates/consent/next/ConsentBanner.tsx", + next: true, + contents: "'use client';\n\n// A consent banner for Next.js apps (Scribase, the consent slot). The page\n// tag for analytics loads only after measurement is allowed.\n//\n// \n\nimport { useEffect, useMemo, useState } from 'react';\n// @ts-expect-error: plain ESM module shipped next to this file\nimport { createConsent, loadAnalyticsWhenAllowed } from '../consent/consent-core.js';\n\nexport function ConsentBanner({ analyticsScript, analyticsSite, privacyUrl = '/privacy' }: { analyticsScript?: string; analyticsSite?: string; privacyUrl?: string }) {\n const consent = useMemo(\n () =>\n createConsent({\n supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL,\n anonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,\n policyVersion: process.env.NEXT_PUBLIC_CONSENT_POLICY_VERSION ?? '1',\n }),\n [],\n );\n const [open, setOpen] = useState(false);\n useEffect(() => {\n setOpen(!consent.decided());\n if (analyticsScript && analyticsSite) return loadAnalyticsWhenAllowed(consent, { scriptUrl: analyticsScript, site: analyticsSite });\n return undefined;\n }, [consent, analyticsScript, analyticsSite]);\n if (!open) return null;\n const decide = (choices: Record) => {\n setOpen(false);\n void consent.decide(choices);\n };\n return (\n
\n

\n We use cookies and similar tools to measure how the app is used. Choose what you allow. Privacy\n

\n
\n \n \n
\n
\n );\n}\n", + }, +]); diff --git a/src/cli/capabilities/railyard/consent.ts b/src/cli/capabilities/railyard/consent.ts new file mode 100644 index 0000000..4efc6e7 --- /dev/null +++ b/src/cli/capabilities/railyard/consent.ts @@ -0,0 +1,44 @@ +/** + * `npx scribase add consent` (Wave P PY2.5, SP-F3): the control plane creates + * the insert-only consent_records table in this environment's database; this + * machine copies the consent files into the app (the core, a plain banner, + * and the Next.js banner when the app uses Next.js). Existing files are never + * overwritten. The analytics tag then loads only after a yes. The proof is + * the first consent record from a visitor. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { CONSENT_FILES } from './consent-files.js'; +import type { SlotContext } from './index.js'; + +function isNext(io: AddIo): boolean { + const pkg = io.readFile(`${io.cwd.replace(/\/+$/, '')}/package.json`); + if (!pkg) return false; + try { + const parsed = JSON.parse(pkg) as { dependencies?: Record; devDependencies?: Record }; + return Boolean(parsed.dependencies?.next ?? parsed.devDependencies?.next); + } catch { + return false; + } +} + +export async function consentFiles(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext): Promise { + void options; + void ctx; + if (result.status !== 'live') return result; + const next = isNext(io); + const root = io.cwd.replace(/\/+$/, ''); + const written: string[] = []; + for (const file of CONSENT_FILES) { + if (file.next && !next) continue; + const target = `${root}/${file.path}`; + if (io.readFile(target) !== null) { + io.log(`Kept your ${file.path} (already there).`); + continue; + } + io.writeFile(target, file.contents); + written.push(file.path); + } + if (written.length) io.log(`Added ${written.join(', ')}.`); + io.log(next ? 'Render in your root layout; analytics loads only after a yes.' : "Call showBanner() from consent/banner.js on your pages; analytics loads only after a yes."); + return { ...result, next: result.next ?? 'The first consent record from a visitor shows in the Consent tab.' }; +} diff --git a/src/cli/capabilities/railyard/deploy.ts b/src/cli/capabilities/railyard/deploy.ts new file mode 100644 index 0000000..ab7775a --- /dev/null +++ b/src/cli/capabilities/railyard/deploy.ts @@ -0,0 +1,75 @@ +/** + * `npx scribase add deploy` (Wave P PY1.2): links this machine to the + * organization's deploy account with a one-time claim (never printed), then + * deploys the folder to the person's own Cloudflare account and answers with + * the live URL as the proof. The project's URL and anon key come from the env + * file `scribase init` wrote; nothing is pasted. + * + * The deploy runs the pinned deploy CLI (see `DEPLOY_CLI`); its lines are + * passed through, and the URL line becomes the proof. + */ +import { spawn } from 'node:child_process'; + +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { InitError } from '../../init.js'; + +export const DEPLOY_CLI = ['npx', '--yes', 'railyard@0.1.0', 'deploy'] as const; + +/** Runs the deploy in `cwd`; resolves with its exit code and every line it printed. */ +export type RunDeploy = (io: AddIo) => Promise<{ code: number; lines: string[] }>; + +const defaultRun: RunDeploy = (io) => + new Promise((resolve) => { + const [command, ...args] = io.env.SCRIBASE_RAILYARD_CLI ? [io.env.SCRIBASE_RAILYARD_CLI, 'deploy'] : DEPLOY_CLI; + const child = spawn(command as string, args, { cwd: io.cwd, env: io.env as NodeJS.ProcessEnv, stdio: ['inherit', 'pipe', 'pipe'] }); + const lines: string[] = []; + const take = (chunk: Buffer): void => { + for (const line of String(chunk).split(/\r?\n/)) if (line.trim()) lines.push(line); + }; + child.stdout.on('data', take); + child.stderr.on('data', take); + child.on('error', () => resolve({ code: 127, lines })); + child.on('close', (code) => resolve({ code: code ?? 1, lines })); + }); + +let run: RunDeploy = defaultRun; + +/** Test seam: replaces the deploy runner; returns the previous one. */ +export function setRunDeploy(next: RunDeploy): RunDeploy { + const previous = run; + run = next; + return previous; +} + +/** The live URL a deploy printed (`Live: https://..workers.dev`). */ +export function liveUrl(lines: readonly string[]): string | null { + for (const line of lines) { + const match = /^Live: (https:\/\/[a-z0-9.-]+\.workers\.dev)\b/i.exec(line.trim()); + if (match?.[1]) return match[1]; + } + return null; +} + +/** Lines worth showing: the deploy's own progress, minus anything naming the vendor tool. */ +export function shownLines(lines: readonly string[]): string[] { + return lines.filter((line) => !/railyard/i.test(line)); +} + +/** Link (done by the slot answer's claim), then deploy and prove with the live URL. */ +export async function deployAfterLink(linked: AddResult, io: AddIo, options: AddOptions): Promise { + void options; + if (linked.status !== 'live') return linked; + const { code, lines } = await run(io); + for (const line of shownLines(lines)) io.log(line); + const url = liveUrl(lines); + if (code !== 0 || !url) { + throw new InitError('deploy_failed', 'the deploy did not finish; the lines above say why', 'fix it, then run the same command again'); + } + return { + ...linked, + live: true, + proof: { kind: 'deploy', id: url, at: Math.floor(io.now() / 1000) }, + sent: true, + next: null, + }; +} diff --git a/src/cli/capabilities/railyard/flags.ts b/src/cli/capabilities/railyard/flags.ts new file mode 100644 index 0000000..0aa113b --- /dev/null +++ b/src/cli/capabilities/railyard/flags.ts @@ -0,0 +1,57 @@ +/** + * `npx scribase add flags` (Wave P PY2.1): the control plane creates this + * project environment's flags on first use and answers with its public + * values for the env file (the flags key ships in the app, like an anon key). + * Then, results first: this machine reads the flags once the way the app's + * SDK does, and the command waits until that first read shows as the slot's + * proof. Flip flags in Environment > Add-ons > Flags; the app sees a flip on + * its next read, with no new build. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { InitError } from '../../init.js'; +import type { SlotAnswer, SlotContext } from './index.js'; + +export const WAIT_MS = 60_000; +const POLL_MS = 3_000; + +type ReadSlot = (io: AddIo, ctx: SlotContext) => Promise; + +function toSeconds(at: string | number): number { + return typeof at === 'number' ? at : Math.floor(Date.parse(at) / 1000); +} + +/** How the app reads its flags (plain fetch; the SDK polls the same URL). */ +export function readSnippet(envName: string): string { + return `const { flags } = await (await fetch(\`\${process.env.FLAGS_URL}?key=\${process.env.${envName}}\`)).json();`; +} + +export async function flagsFirstRead(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext, readSlot: ReadSlot): Promise { + if (result.status !== 'live') return result; + if (ctx.answer.state === 'live' && ctx.answer.proof) return result; + const env = ctx.answer.env ?? {}; + const key = env.NEXT_PUBLIC_FLAGS_KEY ?? env.EXPO_PUBLIC_FLAGS_KEY ?? env.VITE_FLAGS_KEY; + const url = env.FLAGS_URL; + if (!key || !/^ry_flags_/.test(key) || !url || !/^https?:\/\//.test(url)) { + throw new InitError('invalid_response', 'the control plane did not return the flags key'); + } + io.log(`Read flags in your app: ${readSnippet('NEXT_PUBLIC_FLAGS_KEY')}`); + let read: Response; + try { + read = await io.fetch(`${url.replace(/\/+$/, '')}?key=${encodeURIComponent(key)}`, { method: 'GET', headers: { accept: 'application/json', 'user-agent': 'Scribase CLI (flags check)' } }); + } catch (error) { + throw new InitError('network_error', `could not read the flags: ${(error as Error).message}`); + } + if (read.status !== 200) throw new InitError('proof_refused', `the flags read answered HTTP ${read.status}`); + io.log('Read the flags once, the way the app does; waiting for it to show...'); + const deadline = io.now() + (options.wait ? WAIT_MS : 0); + for (;;) { + const state = await readSlot(io, ctx); + if (state.state === 'live' && state.proof) { + return { ...result, live: true, proof: { kind: state.proof.kind, id: state.proof.id, at: toSeconds(state.proof.at) }, sent: true, next: null }; + } + if (io.now() >= deadline) { + return { ...result, next: 'The first read is recorded; it shows in the Flags tab shortly.' }; + } + await io.sleep(POLL_MS); + } +} diff --git a/src/cli/capabilities/railyard/index.ts b/src/cli/capabilities/railyard/index.ts new file mode 100644 index 0000000..4f682b3 --- /dev/null +++ b/src/cli/capabilities/railyard/index.ts @@ -0,0 +1,275 @@ +/** + * `npx scribase add ` handlers for the Railyard slots: deploy, + * analytics, flags, uptime, ai, billing, consent (Wave P carve-out, dispatch + * section 3.1; PY1.0 slot dispatcher). + * + * Owned by the PY lane. PS1.0 created this skeleton and its dispatch line in + * `src/cli/add.ts`; nobody in the PS lane edits this folder. + * + * Each slot calls the control plane's Railyard route + * (`POST .../environments/{env}/railyard/{slot}`), which answers in the + * capability-state shape `{slot, state, live, proof:{kind,id,at}, next, env}`. + * A slot whose package has not landed answers `arriving`, and this command says + * so and changes nothing. When a slot needs this machine linked to Railyard + * (deploy), the answer carries a one-time claim: it is piped on stdin to + * `railyard link-scribase`, which saves the token to Railyard's own credentials + * file (mode 600). The claim and the token are never printed, logged, or + * written to the project's env file. + */ +import { spawn } from 'node:child_process'; + +import type { AddIo, AddOptions, AddResult, Proof } from '../../add.js'; +import { publicEnvOnly, mergeEnv, readEnvValue } from '../../envfile.js'; +import { InitError, STATE_FILE } from '../../init.js'; +import { deployAfterLink } from './deploy.js'; +import { analyticsProof } from './analytics.js'; +import { aiConnect } from './ai.js'; +import { flagsFirstRead } from './flags.js'; +import { uptimeBody, uptimeFirstResult } from './uptime.js'; +import { billingConnect } from './billing.js'; +import { consentFiles } from './consent.js'; + +export type RailyardAddHandler = (options: AddOptions, io: AddIo) => Promise; + +/** The Railyard slots this CLI dispatches (errors stays Scribase's own slot). */ +export const RAILYARD_SLOTS = Object.freeze(['deploy', 'analytics', 'ai', 'flags', 'uptime', 'billing', 'consent'] as const); + +const DEFAULT_API_URL = 'https://api.scribase.com'; +const ENV_FILES = ['.env.local', '.env'] as const; +/** The Railyard CLI that saves the linked token (pinned; the claim goes on stdin). */ +export const RAILYARD_CLI = ['npx', '--yes', 'railyard@0.1.0', 'link-scribase'] as const; + +interface ProjectState { + organization_id: string; + project_id: string; + environment_id: string; + api_url?: string; +} + +/** The answer of the Railyard route (capability-state shape plus an optional claim). */ +export interface SlotAnswer { + slot: string; + state: string; + live: boolean; + proof: Proof | { kind: string; id: string; at: string } | null; + next: string | null; + env?: Record; + /** A one-time link to a page where a credential is entered (never in the terminal). */ + connect_url?: string | null; + claim?: { claim: string; console: string } | null; +} + +/** Pipes a one-time claim to the Railyard CLI. Resolves with its exit code. */ +export type LinkRailyard = (input: string, io: AddIo) => Promise; + +const defaultLink: LinkRailyard = (input, io) => + new Promise((resolve) => { + const [command, ...args] = RAILYARD_CLI; + const child = spawn(command, args, { cwd: io.cwd, env: io.env as NodeJS.ProcessEnv, stdio: ['pipe', 'ignore', 'inherit'] }); + child.on('error', () => resolve(127)); + child.on('close', (code) => resolve(code ?? 1)); + child.stdin.end(input); + }); + +let link: LinkRailyard = defaultLink; + +/** Test seam: replaces the Railyard CLI runner; returns the previous one. */ +export function setLinkRailyard(next: LinkRailyard): LinkRailyard { + const previous = link; + link = next; + return previous; +} + +function joinPath(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +function readProject(io: AddIo): ProjectState { + const text = io.readFile(joinPath(io.cwd, STATE_FILE)); + let state: Partial | null = null; + try { + state = text ? (JSON.parse(text) as Partial) : null; + } catch { + state = null; + } + if (!state?.organization_id || !state.project_id || !state.environment_id) { + throw new InitError('not_initialized', 'this folder is not connected to a Scribase project', 'run `npx scribase init` here first'); + } + return state as ProjectState; +} + +function findToken(io: AddIo): string | undefined { + const fromEnv = io.env.SCRIBASE_ACCESS_TOKEN?.trim(); + if (fromEnv) return fromEnv; + for (const file of ENV_FILES) { + const contents = io.readFile(joinPath(io.cwd, file)); + const value = contents ? readEnvValue(contents, 'SCRIBASE_ACCESS_TOKEN')?.trim() : undefined; + if (value) return value; + } + return io.credentials().token; +} + +/** The control-plane path of one Railyard slot for this folder's environment. */ +export function slotPath(project: ProjectState, slot: string): string { + return ( + `/v1/organizations/${encodeURIComponent(project.organization_id)}` + + `/projects/${encodeURIComponent(project.project_id)}` + + `/environments/${encodeURIComponent(project.environment_id)}` + + `/railyard/${encodeURIComponent(slot)}` + ); +} + +function asAnswer(body: unknown): SlotAnswer { + const value = (body ?? {}) as Partial; + if (typeof value.slot !== 'string' || typeof value.state !== 'string' || typeof value.live !== 'boolean') { + throw new InitError('invalid_response', 'the control plane answered with an unexpected shape'); + } + return value as SlotAnswer; +} + +async function post(io: AddIo, url: string, token: string, payload: Record = {}): Promise { + let response: Response; + try { + response = await io.fetch(url, { + method: 'POST', + headers: { accept: 'application/json', 'content-type': 'application/json', authorization: `Bearer ${token}`, 'user-agent': 'scribase-add' }, + body: JSON.stringify(payload), + }); + } catch (error) { + throw new InitError('network_error', `could not reach the control plane: ${(error as Error).message}`, 'check your connection or SCRIBASE_API_URL'); + } + const text = await response.text(); + let body: unknown = null; + try { + body = text ? JSON.parse(text) : null; + } catch { + body = { detail: text.slice(0, 200) }; + } + if (response.status !== 200) { + const value = (body ?? {}) as { code?: unknown; detail?: unknown }; + const code = typeof value.code === 'string' ? value.code : 'request_failed'; + const detail = typeof value.detail === 'string' ? value.detail : 'the request failed'; + const next = + response.status === 402 + ? 'turn on the Portfolio add-on under Billing, Add-ons in the console' + : response.status === 401 || response.status === 403 + ? 'run `npx scribase login` (adding a slot needs an owner or admin)' + : undefined; + throw new InitError(code, `${detail} (HTTP ${response.status})`, next); + } + return asAnswer(body); +} + +function envFileFor(io: AddIo): string { + for (const file of ENV_FILES) { + if (io.readFile(joinPath(io.cwd, file)) !== null) return file; + } + return '.env'; +} + +function toProof(proof: SlotAnswer['proof']): Proof | null { + if (!proof) return null; + const at = typeof proof.at === 'number' ? proof.at : Math.floor(Date.parse(String(proof.at)) / 1000); + return { kind: proof.kind, id: proof.id, at: Number.isFinite(at) ? at : 0 }; +} + +/** What a slot's follow-up step on this machine may use (never printed). */ +export interface SlotContext { + /** The slot's control-plane URL. */ + url: string; + token: string; + answer: SlotAnswer; +} + +/** Follow-up steps: deploy runs the deploy, analytics sends a proof event and waits for it. */ +export type AfterStep = (result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext) => Promise; + +/** One Railyard slot, end to end. Never returns or logs a secret. */ +export async function addRailyardSlot(slot: string, options: AddOptions, io: AddIo): Promise { + return (await addWithContext(slot, options, io)).result; +} + +async function addWithContext(slot: string, options: AddOptions, io: AddIo): Promise<{ result: AddResult; ctx: SlotContext }> { + void options; + const project = readProject(io); + const token = findToken(io); + if (!token) { + throw new InitError('not_signed_in', 'no Scribase token for this folder', 'run `npx scribase login`, or `npx scribase init` here'); + } + const base = (io.env.SCRIBASE_API_URL ?? project.api_url ?? io.credentials().apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''); + const url = `${base}${slotPath(project, slot)}`; + const answer = await post(io, url, token, BODY[slot]?.(io) ?? {}); + if (answer.state === 'arriving') { + throw new InitError('capability_arriving', answer.next ?? `${slot} is arriving and cannot be turned on yet. Nothing was changed.`, 'run `npx scribase add --list`'); + } + if (answer.claim) { + // The secure channel: stdin of the Railyard CLI only. + const code = await link(JSON.stringify({ claim: answer.claim.claim, console: answer.claim.console }), io); + if (code !== 0) { + throw new InitError('link_failed', 'this machine could not be linked to Railyard; nothing was printed', `run \`npx scribase add ${slot}\` again`); + } + io.log('This machine is linked to your organization for deploys (saved for your user only).'); + } + const { safe, refused } = publicEnvOnly(answer.env ?? {}); + const written = Object.keys(safe); + if (written.length > 0) { + const file = joinPath(io.cwd, envFileFor(io)); + io.writeFile(file, mergeEnv(io.readFile(file) ?? '', safe)); + } + const result: AddResult = { + ok: true, + slot, + status: 'live', + live: answer.live, + provider: 'railyard', + proof: toProof(answer.proof), + sent: answer.proof !== null, + env_written: written, + env_refused: refused, + next: answer.next, + }; + return { result, ctx: { url, token, answer } }; +} + +/** Reads a slot's state again (the follow-up steps poll it). */ +export async function readSlot(io: AddIo, ctx: SlotContext): Promise { + const response = await io.fetch(ctx.url, { method: 'GET', headers: { accept: 'application/json', authorization: `Bearer ${ctx.token}`, 'user-agent': 'scribase-add' } }); + if (response.status !== 200) throw new InitError('request_failed', `the control plane answered HTTP ${response.status}`); + return asAnswer(JSON.parse(await response.text())); +} + +export { toProof }; + +/** Slots whose add request carries a body (uptime: the app's address when known). */ +const BODY: Readonly Record>> = Object.freeze({ + uptime: uptimeBody, +}); + +/** Slots that do more on this machine once the control plane answers (deploy runs the deploy). */ +const AFTER: Readonly> = Object.freeze({ + deploy: (result, io, options) => deployAfterLink(result, io, options), + analytics: (result, io, options, ctx) => analyticsProof(result, io, options, ctx, readSlot), + ai: (result, io, options, ctx) => aiConnect(result, io, options, ctx, readSlot), + flags: (result, io, options, ctx) => flagsFirstRead(result, io, options, ctx, readSlot), + uptime: (result, io, options, ctx) => uptimeFirstResult(result, io, options, ctx, readSlot), + billing: (result, io, options, ctx) => billingConnect(result, io, options, ctx, readSlot), + consent: (result, io, options, ctx) => consentFiles(result, io, options, ctx), +}); + +const HANDLERS: Readonly> = Object.freeze( + Object.fromEntries( + RAILYARD_SLOTS.map((slot) => [ + slot, + async (options: AddOptions, io: AddIo) => { + const { result, ctx } = await addWithContext(slot, options, io); + const after = AFTER[slot]; + return after ? after(result, io, options, ctx) : result; + }, + ]), + ), +); + +/** The local handler for `slot`, or `null` when the generic path serves it. */ +export function railyardAddHandler(slot: string): RailyardAddHandler | null { + return Object.hasOwn(HANDLERS, slot) ? (HANDLERS[slot] ?? null) : null; +} diff --git a/src/cli/capabilities/railyard/railyard.test.mjs b/src/cli/capabilities/railyard/railyard.test.mjs new file mode 100644 index 0000000..6e169ef --- /dev/null +++ b/src/cli/capabilities/railyard/railyard.test.mjs @@ -0,0 +1,354 @@ +// PY1.0: `npx scribase add ` dispatch. Run: +// node --import tsx/esm --test src/cli/capabilities/railyard/railyard.test.mjs +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readdirSync, readFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import { RAILYARD_SLOTS, railyardAddHandler, setLinkRailyard, slotPath } from './index.ts'; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const project = { organization_id: 'org_a', project_id: 'shop', environment_id: 'prod' }; +const CLAIM = 'claim_0123456789abcdefghijklmnop'; + +function io(answer, status = 200) { + const files = new Map([['/app/.scribase/project.json', JSON.stringify(project)], ['/app/.env.local', 'NEXT_PUBLIC_SUPABASE_URL=https://x\n']]); + const logs = []; + const calls = []; + return { + logs, + calls, + files, + io: { + cwd: '/app', + env: { SCRIBASE_API_URL: 'https://api.test', SCRIBASE_ACCESS_TOKEN: 'scb_pat_test' }, + fetch: async (url, init) => { + calls.push({ url, init }); + return new Response(JSON.stringify(answer), { status }); + }, + readFile: (p) => files.get(p) ?? null, + writeFile: (p, c) => files.set(p, c), + credentials: () => ({}), + sleep: async () => {}, + now: () => 0, + log: (l) => logs.push(l), + openBrowser: () => {}, + }, + }; +} +const opts = { slot: 'deploy', list: false, own: false, resend: false, json: false, wait: true, browser: false, waitSeconds: 1 }; + +test('every Railyard slot has a handler; errors and unknown slots stay on the generic path', () => { + for (const slot of RAILYARD_SLOTS) assert.equal(typeof railyardAddHandler(slot), 'function', slot); + assert.equal(railyardAddHandler('errors'), null); + assert.equal(railyardAddHandler('email'), null); + assert.equal(slotPath(project, 'deploy'), '/v1/organizations/org_a/projects/shop/environments/prod/railyard/deploy'); +}); + +test('an arriving slot says so and changes nothing', async () => { + const t = io({ slot: 'analytics', state: 'arriving', live: false, proof: null, next: 'Analytics is arriving (PY1.3).', env: {} }); + await assert.rejects(railyardAddHandler('analytics')(opts, t.io), (e) => e.code === 'capability_arriving' && /PY1\.3/.test(e.message)); + assert.equal(t.calls[0].url, 'https://api.test/v1/organizations/org_a/projects/shop/environments/prod/railyard/analytics'); + assert.equal(t.calls[0].init.headers.authorization, 'Bearer scb_pat_test'); + assert.equal(t.files.get('/app/.env.local'), 'NEXT_PUBLIC_SUPABASE_URL=https://x\n'); +}); + +test('a live slot returns its proof; a claim goes only to the Railyard CLI stdin and is never logged or written', async () => { + const piped = []; + const previous = setLinkRailyard(async (input) => { + piped.push(input); + return 0; + }); + try { + const t = io({ + slot: 'flags', + state: 'live', + live: true, + proof: { kind: 'flag_flip', id: 'd1', at: '2026-09-29T12:00:00.000Z' }, + next: null, + env: { PUBLIC_X: '1', RAILYARD_TOKEN_SECRET: 'nope' }, + claim: { claim: CLAIM, console: 'https://railyard.example' }, + }); + const r = await railyardAddHandler('flags')(opts, t.io); + assert.equal(r.live, true); + assert.deepEqual(r.proof, { kind: 'flag_flip', id: 'd1', at: 1790683200 }); + assert.deepEqual(r.env_written, ['PUBLIC_X']); + assert.deepEqual(r.env_refused, ['RAILYARD_TOKEN_SECRET']); + assert.deepEqual(JSON.parse(piped[0]), { claim: CLAIM, console: 'https://railyard.example' }); + const everything = [...t.logs, ...t.files.values(), JSON.stringify(r)].join('\n'); + assert.ok(!everything.includes(CLAIM), 'the claim is never printed, logged or written'); + } finally { + setLinkRailyard(previous); + } +}); + +test('a missing add-on is a plain 402 with the next step', async () => { + const t = io({ code: 'addon_required', detail: 'Deploy comes with the Portfolio add-on, which is off for this organization.' }, 402); + await assert.rejects(railyardAddHandler('deploy')(opts, t.io), (e) => e.code === 'addon_required' && /Billing, Add-ons/.test(e.next)); +}); + +test('no file in this folder prints to the console directly (grep test)', () => { + for (const f of readdirSync(HERE).filter((f) => f.endsWith('.ts'))) { + assert.doesNotMatch(readFileSync(join(HERE, f), 'utf8'), /console\.(log|info|warn|error|debug)|process\.(stdout|stderr)/, f); + } +}); + +test('deploy (PY1.2): link with the claim, then deploy, and the live URL is the proof; vendor lines are not shown', async () => { + const { setRunDeploy, liveUrl, shownLines } = await import('./deploy.ts'); + const piped = []; + const prevLink = setLinkRailyard(async (input) => { + piped.push(input); + return 0; + }); + const prevRun = setRunDeploy(async () => ({ + code: 0, + lines: ['Deploying vite app shop (branch main) as shop', 'Using the Scribase project settings: VITE_SUPABASE_ANON_KEY, VITE_SUPABASE_URL', 'Run railyard login first.', 'Live: https://shop.founder.workers.dev'], + })); + try { + const t = io({ slot: 'deploy', state: 'no_proof_yet', live: true, proof: null, next: 'Deploy from the project folder.', env: {}, claim: { claim: CLAIM, console: 'https://r.example' } }); + t.io.now = () => 1790683200000; + const r = await railyardAddHandler('deploy')(opts, t.io); + assert.equal(piped.length, 1); + assert.deepEqual(r.proof, { kind: 'deploy', id: 'https://shop.founder.workers.dev', at: 1790683200 }); + assert.ok(!t.logs.some((l) => /railyard/i.test(l)), 'vendor lines are not shown'); + assert.ok(t.logs.includes('Live: https://shop.founder.workers.dev')); + assert.ok(![...t.logs, JSON.stringify(r)].join('\n').includes(CLAIM)); + } finally { + setLinkRailyard(prevLink); + setRunDeploy(prevRun); + } + assert.equal(liveUrl(['nope']), null); + assert.deepEqual(shownLines(['Railyard x', 'ok']), ['ok']); +}); + +test('a failed deploy is an error with the next step, not a proof', async () => { + const { setRunDeploy } = await import('./deploy.ts'); + const prevLink = setLinkRailyard(async () => 0); + const prevRun = setRunDeploy(async () => ({ code: 1, lines: ['X [ERROR] build failed'] })); + try { + const t = io({ slot: 'deploy', state: 'no_proof_yet', live: true, proof: null, next: null, env: {}, claim: { claim: CLAIM, console: 'https://r.example' } }); + await assert.rejects(railyardAddHandler('deploy')(opts, t.io), (e) => e.code === 'deploy_failed'); + } finally { + setLinkRailyard(prevLink); + setRunDeploy(prevRun); + } +}); + +test('analytics (PY1.3): public site values go to the env file, one check event is sent, and the first event is the proof', async () => { + const answers = [ + { slot: 'analytics', state: 'no_proof_yet', live: true, proof: null, next: 'Waiting.', env: { NEXT_PUBLIC_ANALYTICS_SITE: 'ry_site_abcdefgh12', ANALYTICS_SCRIPT_URL: 'https://i.example/s.js', ANALYTICS_COLLECTOR_URL: 'https://i.example' } }, + ]; + const t = io(answers[0]); + const sends = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.fetch = async (url, init) => { + if (url === 'https://i.example/api/send') { + sends.push({ body: JSON.parse(init.body), ua: init.headers['user-agent'] }); + return new Response('', { status: 202 }); + } + if (init.method === 'GET') { + polls += 1; + const live = polls >= 2; + return new Response(JSON.stringify({ slot: 'analytics', state: live ? 'live' : 'no_proof_yet', live: true, proof: live ? { kind: 'first_event', id: 'app1', at: '2026-09-29T12:00:06.000Z' } : null, next: null }), { status: 200 }); + } + return new Response(JSON.stringify(answers[0]), { status: 200 }); + }; + const r = await railyardAddHandler('analytics')(opts, t.io); + assert.deepEqual(r.env_written.sort(), ['ANALYTICS_COLLECTOR_URL', 'ANALYTICS_SCRIPT_URL', 'NEXT_PUBLIC_ANALYTICS_SITE']); + assert.equal(sends.length, 1); + assert.equal(sends[0].body.payload.website, 'ry_site_abcdefgh12'); + assert.doesNotMatch(sends[0].ua, /bot|curl|node/i); + assert.deepEqual(r.proof, { kind: 'first_event', id: 'app1', at: 1790683206 }); + assert.ok(t.logs.some((l) => l.includes('data-site="ry_site_abcdefgh12"'))); + assert.ok(clock - 1790683200000 <= 60_000, 'within 60 s'); +}); + +test('analytics (QY1.2): host and project key reach the env file; the check event also goes to product analytics; the first product event is the proof', async () => { + const env = { + NEXT_PUBLIC_ANALYTICS_SITE: 'ry_site_abcdefgh12', + ANALYTICS_SCRIPT_URL: 'https://i.example/s.js', + ANALYTICS_COLLECTOR_URL: 'https://i.example', + NEXT_PUBLIC_ANALYTICS_HOST: 'https://pa.example', + NEXT_PUBLIC_ANALYTICS_KEY: 'ry_site_abcdefgh12', + }; + const answer = { slot: 'analytics', state: 'no_proof_yet', live: true, proof: null, next: 'Waiting.', env }; + const t = io(answer); + const sends = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.fetch = async (url, init) => { + if (url === 'https://i.example/api/send' || url === 'https://pa.example/capture/') { + sends.push({ url, body: JSON.parse(init.body), headers: init.headers }); + return new Response('{"status":1}', { status: url.includes('pa.example') ? 200 : 202 }); + } + if (init.method === 'GET') { + polls += 1; + const live = polls >= 2; + return new Response(JSON.stringify({ slot: 'analytics', state: live ? 'live' : 'no_proof_yet', live: true, proof: live ? { kind: 'first_product_event', id: 'app1', at: '2026-09-29T12:00:04.000Z' } : null, next: null }), { status: 200 }); + } + return new Response(JSON.stringify(answer), { status: 200 }); + }; + const r = await railyardAddHandler('analytics')(opts, t.io); + assert.deepEqual(r.env_written.sort(), Object.keys(env).sort()); + assert.deepEqual(sends.map((s) => s.url), ['https://i.example/api/send', 'https://pa.example/capture/'], 'the page-tag path is kept; product analytics gets the same check'); + const product = sends[1].body; + assert.equal(product.api_key, 'ry_site_abcdefgh12'); + assert.equal(product.event, 'scribase_proof'); + assert.equal(product.properties.$process_person_profile, false); + assert.doesNotMatch(sends[1].headers['user-agent'], /bot|curl|node/i); + assert.deepEqual(r.proof, { kind: 'first_product_event', id: 'app1', at: 1790683204 }); + assert.ok(t.logs.some((l) => l.includes('https://pa.example') && l.includes('NEXT_PUBLIC_ANALYTICS_KEY'))); + assert.ok(!t.logs.join('\n').includes('ry_pak_'), 'no server key is ever printed'); + // An SDK-only stack (no collector) still sends its check to product analytics. + const onlyPa = { ...answer, env: { NEXT_PUBLIC_ANALYTICS_SITE: 'ry_site_abcdefgh12', NEXT_PUBLIC_ANALYTICS_HOST: 'https://pa.example', NEXT_PUBLIC_ANALYTICS_KEY: 'ry_site_abcdefgh12' } }; + const t2 = io(onlyPa); + const urls = []; + t2.io.fetch = async (url, init) => { + if (init.method === 'GET') return new Response(JSON.stringify({ slot: 'analytics', state: 'live', live: true, proof: { kind: 'first_product_event', id: 'app1', at: '2026-09-29T12:00:04.000Z' }, next: null }), { status: 200 }); + urls.push(url); + return new Response(JSON.stringify(url.includes('/capture/') ? { status: 1 } : onlyPa), { status: 200 }); + }; + t2.io.now = () => 1790683200000; + await railyardAddHandler('analytics')(opts, t2.io); + assert.ok(urls.includes('https://pa.example/capture/')); + assert.ok(!urls.some((u) => u.endsWith('/api/send'))); +}); + +test('ai (PY1.4): only the public gateway URL reaches the env file; the connect page opens in the browser; connected provider is the proof', async () => { + const answer = { slot: 'ai', state: 'needs_connect', live: false, proof: null, next: 'Open the connect link.', env: { AI_GATEWAY_URL: 'https://r.example/api/v1/ai' }, connect_url: 'https://r.example/connect/ai?t=ry_ct_0123456789abcdefghijkl' }; + const t = io(answer); + const opened = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.openBrowser = (u) => opened.push(u); + t.io.fetch = async (url, init) => { + if (init.method === 'GET') { + polls += 1; + const live = polls >= 2; + return new Response(JSON.stringify({ slot: 'ai', state: live ? 'live' : 'needs_connect', live, proof: live ? { kind: 'gateway_key', id: 'anthropic', at: '2026-09-29T12:00:09.000Z' } : null, next: null }), { status: 200 }); + } + return new Response(JSON.stringify(answer), { status: 200 }); + }; + const r = await railyardAddHandler('ai')({ ...opts, browser: true, waitSeconds: 60 }, t.io); + assert.deepEqual(r.env_written, ['AI_GATEWAY_URL']); + assert.deepEqual(opened, [answer.connect_url]); + assert.deepEqual(r.proof, { kind: 'gateway_key', id: 'anthropic', at: 1790683209 }); + const envFile = t.files.get('/app/.env.local'); + assert.ok(!/ry_ai_|AI_GATEWAY_KEY/.test(envFile), 'the key never reaches the env file'); +}); + +test('flags (PY2.1): public flags values go to the env file, one read the way the app reads, and the first read is the proof', async () => { + const KEY = 'ry_flags_abcdefghijklmnopqrstuvwxyz012345'; + const answer = { slot: 'flags', state: 'no_proof_yet', live: true, proof: null, next: 'Read a flag.', env: { NEXT_PUBLIC_FLAGS_KEY: KEY, EXPO_PUBLIC_FLAGS_KEY: KEY, VITE_FLAGS_KEY: KEY, FLAGS_URL: 'https://r.example/api/v1/flags/client' } }; + const t = io(answer); + const reads = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.fetch = async (url, init) => { + if (url.startsWith('https://r.example/api/v1/flags/client')) { + reads.push(url); + return new Response(JSON.stringify({ env: 'prod', flags: {} }), { status: 200 }); + } + if (init.method === 'GET') { + polls += 1; + const live = polls >= 2; + return new Response(JSON.stringify({ slot: 'flags', state: live ? 'live' : 'no_proof_yet', live: true, proof: live ? { kind: 'first_flag_read', id: 'shop/prod', at: '2026-09-29T12:00:04.000Z' } : null, next: null }), { status: 200 }); + } + return new Response(JSON.stringify(answer), { status: 200 }); + }; + const r = await railyardAddHandler('flags')(opts, t.io); + assert.deepEqual(r.env_written.sort(), ['EXPO_PUBLIC_FLAGS_KEY', 'FLAGS_URL', 'NEXT_PUBLIC_FLAGS_KEY', 'VITE_FLAGS_KEY']); + assert.deepEqual(reads, [`https://r.example/api/v1/flags/client?key=${KEY}`]); + assert.deepEqual(r.proof, { kind: 'first_flag_read', id: 'shop/prod', at: 1790683204 }); + assert.ok(clock - 1790683200000 <= 60_000, 'within 60 s'); + const bad = io({ ...answer, env: { FLAGS_URL: 'https://r.example/x' } }); + await assert.rejects(railyardAddHandler('flags')(opts, bad.io), (e) => e.code === 'invalid_response'); +}); + +test('uptime (PY2.2): the site address from the env file is sent, the status page is printed, the first result is the proof', async () => { + const answer = { slot: 'uptime', state: 'no_proof_yet', live: true, proof: null, next: 'The first result arrives within two minutes. Status page: https://r.example/status/shop-abc123', env: {} }; + const t = io(answer); + t.files.set('/app/.env.local', 'NEXT_PUBLIC_SITE_URL=https://shop.example.com\n'); + const posted = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.fetch = async (url, init) => { + if (init.method === 'GET') { + polls += 1; + const live = polls >= 3; + return new Response(JSON.stringify({ slot: 'uptime', state: live ? 'live' : 'no_proof_yet', live: true, proof: live ? { kind: 'check_result', id: 'c1', at: '2026-09-29T12:01:30.000Z' } : null, next: 'Status page: https://r.example/status/shop-abc123' }), { status: 200 }); + } + posted.push(JSON.parse(init.body)); + return new Response(JSON.stringify(answer), { status: 200 }); + }; + const r = await railyardAddHandler('uptime')(opts, t.io); + assert.deepEqual(posted, [{ url: 'https://shop.example.com' }]); + assert.ok(t.logs.some((l) => l.includes('https://r.example/status/shop-abc123'))); + assert.deepEqual(r.proof, { kind: 'check_result', id: 'c1', at: 1790683290 }); + assert.ok(clock - 1790683200000 <= 180_000); + const none = io(answer); + none.files.delete('/app/.env.local'); + const bodies = []; + none.io.fetch = async (url, init) => (bodies.push(init.body), new Response(JSON.stringify({ ...answer, state: 'live', proof: { kind: 'check_result', id: 'c1', at: 1 } }), { status: 200 })); + await railyardAddHandler('uptime')(opts, none.io); + assert.deepEqual(bodies, ['{}'], 'no address known: the project\'s latest live deploy is checked'); +}); + +test('billing (PY2.3): the connect page opens in the browser, no key is asked or written, and the connection is awaited', async () => { + const answer = { slot: 'billing', state: 'needs_connect', live: false, proof: null, next: 'Open the connect link.', env: {}, connect_url: 'https://mint.example/mint/connect/' + 'a'.repeat(64) }; + const t = io(answer); + const opened = []; + let polls = 0; + let clock = 1790683200000; + t.io.now = () => clock; + t.io.sleep = async (ms) => void (clock += ms); + t.io.openBrowser = (u) => opened.push(u); + t.io.fetch = async (url, init) => { + if (init.method === 'GET') { + polls += 1; + return new Response(JSON.stringify({ slot: 'billing', state: polls >= 2 ? 'no_proof_yet' : 'needs_connect', live: polls >= 2, proof: null, next: null }), { status: 200 }); + } + return new Response(JSON.stringify(answer), { status: 200 }); + }; + const r = await railyardAddHandler('billing')({ ...opts, browser: true, waitSeconds: 60 }, t.io); + assert.deepEqual(opened, [answer.connect_url]); + assert.match(r.next, /test purchase/); + assert.deepEqual(r.env_written, []); + assert.equal(t.files.get('/app/.env.local'), 'NEXT_PUBLIC_SUPABASE_URL=https://x\n', 'nothing is written'); + assert.ok(!t.logs.some((l) => /api_key|secret/i.test(l))); +}); + +test('consent (PY2.5): the template files are copied, Next.js gets its banner, nothing is overwritten', async () => { + const answer = { slot: 'consent', state: 'no_proof_yet', live: true, proof: null, next: null, env: { NEXT_PUBLIC_CONSENT_POLICY_VERSION: '1' } }; + const t = io(answer); + t.files.set('/app/package.json', JSON.stringify({ dependencies: { next: '15.0.0' } })); + t.files.set('/app/consent/banner.js', '// mine'); + const r = await railyardAddHandler('consent')(opts, t.io); + assert.equal(r.ok, true); + assert.ok(t.files.get('/app/consent/consent-core.js').includes('loadAnalyticsWhenAllowed')); + assert.equal(t.files.get('/app/consent/banner.js'), '// mine', 'never overwritten'); + assert.ok(t.files.get('/app/components/ConsentBanner.tsx').includes('ConsentBanner')); + assert.deepEqual(r.env_written, ['NEXT_PUBLIC_CONSENT_POLICY_VERSION']); + const plain = io(answer); + await railyardAddHandler('consent')(opts, plain.io); + assert.equal(plain.files.get('/app/components/ConsentBanner.tsx'), undefined, 'no Next.js banner without Next.js'); +}); + +// The upstream monorepo (not shipped here) keeps canonical copies of these +// templates under `templates/consent/**` and asserts `consent-files.ts` +// stays byte-identical to them. This standalone repo ships only the +// already-embedded `contents` strings in `consent-files.ts`, which is what +// the CLI actually writes, so that cross-check has nothing to compare +// against here and is intentionally not reproduced. diff --git a/src/cli/capabilities/railyard/uptime.ts b/src/cli/capabilities/railyard/uptime.ts new file mode 100644 index 0000000..9e8333e --- /dev/null +++ b/src/cli/capabilities/railyard/uptime.ts @@ -0,0 +1,55 @@ +/** + * `npx scribase add uptime` (Wave P PY2.2): adds a check for the app's + * address (SCRIBASE_UPTIME_URL, else the site URL in the env file, else the + * project's latest live deploy), then waits for the first result, which is + * the slot's proof, and prints the public status page. Two failures in a row + * email the person who added it. + */ +import type { AddIo, AddOptions, AddResult } from '../../add.js'; +import { readEnvValue } from '../../envfile.js'; +import type { SlotAnswer, SlotContext } from './index.js'; + +export const WAIT_MS = 180_000; +const POLL_MS = 10_000; +/** Where the app's address is looked up, in order. */ +export const URL_NAMES = ['SCRIBASE_UPTIME_URL', 'NEXT_PUBLIC_SITE_URL', 'SITE_URL', 'APP_URL', 'PUBLIC_URL'] as const; +const ENV_FILES = ['.env.local', '.env'] as const; + +type ReadSlot = (io: AddIo, ctx: SlotContext) => Promise; + +function toSeconds(at: string | number): number { + return typeof at === 'number' ? at : Math.floor(Date.parse(at) / 1000); +} + +/** The body of the add request: the app's https address when one is known. */ +export function uptimeBody(io: AddIo): Record { + for (const name of URL_NAMES) { + const fromEnv = io.env[name]?.trim(); + if (fromEnv?.startsWith('https://')) return { url: fromEnv }; + for (const file of ENV_FILES) { + const contents = io.readFile(`${io.cwd.replace(/\/+$/, '')}/${file}`); + const value = contents ? readEnvValue(contents, name)?.trim() : undefined; + if (value?.startsWith('https://')) return { url: value }; + } + } + return {}; +} + +export async function uptimeFirstResult(result: AddResult, io: AddIo, options: AddOptions, ctx: SlotContext, readSlot: ReadSlot): Promise { + if (result.status !== 'live') return result; + if (ctx.answer.next) io.log(ctx.answer.next); + if (ctx.answer.state === 'live' && ctx.answer.proof) return result; + if (!options.wait) return result; + io.log('Waiting for the first result...'); + const deadline = io.now() + WAIT_MS; + for (;;) { + await io.sleep(POLL_MS); + const state = await readSlot(io, ctx); + if (state.state === 'live' && state.proof) { + return { ...result, live: true, proof: { kind: state.proof.kind, id: state.proof.id, at: toSeconds(state.proof.at) }, sent: true, next: state.next }; + } + if (io.now() >= deadline) { + return { ...result, next: 'The check is added; its first result shows in the Uptime tab shortly.' }; + } + } +} diff --git a/src/cli/connect.ts b/src/cli/connect.ts new file mode 100644 index 0000000..3a96901 --- /dev/null +++ b/src/cli/connect.ts @@ -0,0 +1,392 @@ +/** + * `npx scribase connect [tool...]`: writes the Scribase remote MCP server + * (`https://api.scribase.com/mcp`) into every AI coding tool this machine has + * installed, in one command — the Neon `neon init` / Vercel `npx add-mcp` + * pattern (see `research/scribase-ai-default-2026-11-11.md` P4). + * + * Supported tools and exactly what each one gets, matching its own documented + * config shape (sources: `research/scribase-ai-default-2026-11-11.md` §4): + * + * claude-code `claude mcp add --transport http --scope user scribase ` + * cursor ~/.cursor/mcp.json {"mcpServers":{"scribase":{"url":...}}} + * vscode ./.vscode/mcp.json {"servers":{"scribase":{"type":"http","url":...}}} + * codex ~/.codex/config.toml [mcp_servers.scribase]\n url = "..."\n auth = "oauth" + * windsurf ~/.codeium/windsurf/mcp_config.json {"mcpServers":{"scribase":{"serverUrl":...}}} + * zed ~/.config/zed/settings.json {"context_servers":{"scribase":{"url":...}}} + * + * No `Authorization` header is written for the JSON/TOML tools: the server + * answers `tools/list` without a token and asks for OAuth only on the first + * tool call that needs one, so the client's own OAuth flow (Claude Code, + * Cursor, VS Code, Codex all support MCP OAuth) is what runs — never a pasted + * token. Every write is idempotent: an identical entry already present is + * left untouched and reported as `already_configured`, never duplicated. + * + * `--dry-run` runs every detection and diff but writes nothing. `--tool ` + * (repeatable, or positional ids) configures exactly those tools, skipping + * auto-detection for them. Auto mode (no `--tool`) only touches tools this + * machine actually has (a config directory or a binary on PATH) so a clean + * machine's filesystem is left alone. + */ + +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { homedir } from 'node:os'; +import { dirname } from 'node:path'; +import { spawnSync } from 'node:child_process'; + +import { DEFAULT_API_URL } from './init.js'; +import { InitError } from './init.js'; + +export const TOOL_IDS = ['claude-code', 'cursor', 'vscode', 'codex', 'windsurf', 'zed'] as const; +export type ToolId = (typeof TOOL_IDS)[number]; + +const TOOL_ALIASES: Record = { + claude: 'claude-code', + 'claude-code': 'claude-code', + 'claude code': 'claude-code', + cursor: 'cursor', + vscode: 'vscode', + 'vs-code': 'vscode', + 'vs code': 'vscode', + code: 'vscode', + codex: 'codex', + windsurf: 'windsurf', + zed: 'zed', +}; + +const TOOL_LABELS: Record = { + 'claude-code': 'Claude Code', + cursor: 'Cursor', + vscode: 'VS Code', + codex: 'Codex', + windsurf: 'Windsurf', + zed: 'Zed', +}; + +export interface ConnectOptions { + json: boolean; + dryRun: boolean; + /** `null` = auto-detect every tool; otherwise configure exactly these, unconditionally. */ + tools: ToolId[] | null; + apiUrl?: string; +} + +export interface RunOutcome { + ok: boolean; + output: string; +} + +export interface ConnectIo { + cwd: string; + home: string; + env: Record; + readFile: (path: string) => string | null; + writeFile: (path: string, contents: string) => void; + exists: (path: string) => boolean; + /** Is `command` runnable on PATH? (e.g. a plain `which`/`where` check.) */ + which: (command: string) => boolean; + /** Runs `command` with `args`, no shell. Used only for the Claude Code CLI. */ + run: (command: string, args: string[]) => RunOutcome; +} + +export type ToolStatus = 'configured' | 'already_configured' | 'would_configure' | 'skipped_not_detected' | 'failed'; + +export interface ToolResult { + tool: ToolId; + label: string; + detected: boolean; + status: ToolStatus; + path?: string; + detail?: string; +} + +export interface ConnectResult { + ok: true; + mcp_url: string; + dry_run: boolean; + tools: ToolResult[]; +} + +function join(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +/** Parses one `--tool` value (or positional argument) into a {@link ToolId}. */ +function parseToolId(raw: string): ToolId { + const id = TOOL_ALIASES[raw.toLowerCase()]; + if (!id) { + throw new InitError('invalid_argument', `"${raw}" is not a known tool`, `run \`npx scribase connect --help\` for the list (${TOOL_IDS.join(', ')})`); + } + return id; +} + +/** Parses `connect` arguments. */ +export function parseConnectArgs(argv: string[]): ConnectOptions { + const options: ConnectOptions = { json: false, dryRun: false, tools: null }; + const selected: ToolId[] = []; + let anySelected = false; + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index] ?? ''; + if (arg === '--json') options.json = true; + else if (arg === '--dry-run') options.dryRun = true; + else if (arg === '--tool' || arg.startsWith('--tool=')) { + const raw = arg.startsWith('--tool=') ? arg.slice('--tool='.length) : argv[++index]; + if (!raw) throw new InitError('invalid_argument', '--tool needs a value', `one of ${TOOL_IDS.join(', ')}`); + anySelected = true; + const id = parseToolId(raw); + if (!selected.includes(id)) selected.push(id); + } else if (arg === '--api-url' || arg.startsWith('--api-url=')) { + const raw = arg.startsWith('--api-url=') ? arg.slice('--api-url='.length) : argv[++index]; + if (!raw) throw new InitError('invalid_argument', '--api-url needs a value'); + options.apiUrl = raw; + } else if (arg.startsWith('--')) { + throw new InitError('invalid_argument', `unknown option ${arg}`, 'run `npx scribase connect --help`'); + } else { + anySelected = true; + const id = parseToolId(arg); + if (!selected.includes(id)) selected.push(id); + } + } + if (anySelected) options.tools = selected; + return options; +} + +function mcpUrl(options: ConnectOptions, io: Pick): string { + const apiUrl = (options.apiUrl ?? io.env.SCRIBASE_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, ''); + return `${apiUrl}/mcp`; +} + +/** Deep-equal for the small plain-object entries this file writes; order-independent. */ +function sameEntry(a: unknown, b: unknown): boolean { + if (a === b) return true; + if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false; + const aKeys = Object.keys(a as Record).sort(); + const bKeys = Object.keys(b as Record).sort(); + if (aKeys.length !== bKeys.length || aKeys.some((key, index) => key !== bKeys[index])) return false; + return aKeys.every((key) => sameEntry((a as Record)[key], (b as Record)[key])); +} + +interface MergeOutcome { + content: string; + changed: boolean; +} + +/** + * Merges `{ [topKey]: { [entryKey]: entry } }` into an existing JSON file's + * text (or a fresh object when there is none yet), preserving every other + * key. Throws {@link InitError} `invalid_config` when the existing file is + * not valid JSON — this command never overwrites a file it cannot parse. + */ +export function mergeJsonServer(existing: string | null, path: string, topKey: string, entryKey: string, entry: Record): MergeOutcome { + let parsed: Record = {}; + if (existing !== null && existing.trim().length > 0) { + try { + parsed = JSON.parse(existing) as Record; + } catch { + throw new InitError('invalid_config', `${path} is not valid JSON`, 'fix or remove it, then run `npx scribase connect` again'); + } + } + const container = { ...((parsed[topKey] as Record | undefined) ?? {}) }; + if (sameEntry(container[entryKey], entry)) { + return { content: existing ?? `${JSON.stringify(parsed, null, 2)}\n`, changed: false }; + } + container[entryKey] = entry; + const next = { ...parsed, [topKey]: container }; + return { content: `${JSON.stringify(next, null, 2)}\n`, changed: true }; +} + +/** + * Appends a `[header]` TOML table when it is not already present (checked by + * a literal `[header]` line, not a full parse — safe because this command + * only ever adds a brand-new table, never edits one). Idempotent: a file + * that already declares the table is returned unchanged. + */ +export function mergeTomlSection(existing: string | null, header: string, lines: readonly string[]): MergeOutcome { + const text = existing ?? ''; + const headerLine = `[${header}]`; + if (text.split('\n').some((line) => line.trim() === headerLine)) { + return { content: text, changed: false }; + } + const prefix = text.length === 0 ? '' : text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n'; + return { content: `${text}${prefix}${headerLine}\n${lines.map((line) => `${line}\n`).join('')}`, changed: true }; +} + +function detect(id: ToolId, io: ConnectIo): boolean { + switch (id) { + case 'claude-code': + return io.which('claude'); + case 'cursor': + return io.exists(join(io.home, '.cursor')) || io.exists(join(io.home, '.cursor/mcp.json')); + case 'vscode': + return io.which('code') || io.exists(join(io.cwd, '.vscode')); + case 'codex': + return io.exists(join(io.home, '.codex')) || io.which('codex'); + case 'windsurf': + return io.exists(join(io.home, '.codeium/windsurf')) || io.exists(join(io.home, '.windsurf')); + case 'zed': + return io.exists(join(io.home, '.config/zed')); + } +} + +function applyClaudeCode(io: ConnectIo, url: string, dryRun: boolean): ToolResult { + const label = TOOL_LABELS['claude-code']; + if (dryRun) { + return { tool: 'claude-code', label, detected: true, status: 'would_configure', detail: `claude mcp add --transport http --scope user scribase ${url}` }; + } + const outcome = io.run('claude', ['mcp', 'add', '--transport', 'http', '--scope', 'user', 'scribase', url]); + if (outcome.ok) { + const firstLine = outcome.output.trim().split('\n')[0]; + return firstLine ? { tool: 'claude-code', label, detected: true, status: 'configured', detail: firstLine } : { tool: 'claude-code', label, detected: true, status: 'configured' }; + } + if (/already exists/i.test(outcome.output)) { + return { tool: 'claude-code', label, detected: true, status: 'already_configured' }; + } + return { tool: 'claude-code', label, detected: true, status: 'failed', detail: outcome.output.trim().slice(0, 300) || 'claude mcp add failed' }; +} + +function applyJsonTool(io: ConnectIo, id: ToolId, path: string, topKey: string, entry: Record, dryRun: boolean): ToolResult { + const label = TOOL_LABELS[id]; + let merge: MergeOutcome; + try { + merge = mergeJsonServer(io.readFile(path), path, topKey, 'scribase', entry); + } catch (error) { + return { tool: id, label, detected: true, status: 'failed', path, detail: (error as Error).message }; + } + if (!merge.changed) return { tool: id, label, detected: true, status: 'already_configured', path }; + if (dryRun) return { tool: id, label, detected: true, status: 'would_configure', path }; + io.writeFile(path, merge.content); + return { tool: id, label, detected: true, status: 'configured', path }; +} + +function applyCodex(io: ConnectIo, url: string, dryRun: boolean): ToolResult { + const path = join(io.home, '.codex/config.toml'); + const merge = mergeTomlSection(io.readFile(path), 'mcp_servers.scribase', [`url = "${url}"`, 'auth = "oauth"']); + if (!merge.changed) return { tool: 'codex', label: TOOL_LABELS.codex, detected: true, status: 'already_configured', path }; + if (dryRun) return { tool: 'codex', label: TOOL_LABELS.codex, detected: true, status: 'would_configure', path }; + io.writeFile(path, merge.content); + return { tool: 'codex', label: TOOL_LABELS.codex, detected: true, status: 'configured', path }; +} + +function applyTool(io: ConnectIo, id: ToolId, url: string, dryRun: boolean): ToolResult { + switch (id) { + case 'claude-code': + return applyClaudeCode(io, url, dryRun); + case 'cursor': + return applyJsonTool(io, 'cursor', join(io.home, '.cursor/mcp.json'), 'mcpServers', { url }, dryRun); + case 'vscode': + return applyJsonTool(io, 'vscode', join(io.cwd, '.vscode/mcp.json'), 'servers', { type: 'http', url }, dryRun); + case 'windsurf': + return applyJsonTool(io, 'windsurf', join(io.home, '.codeium/windsurf/mcp_config.json'), 'mcpServers', { serverUrl: url }, dryRun); + case 'zed': + return applyJsonTool(io, 'zed', join(io.home, '.config/zed/settings.json'), 'context_servers', { url }, dryRun); + case 'codex': + return applyCodex(io, url, dryRun); + } +} + +/** Runs `connect` and returns its result. Never throws for a single tool's own failure. */ +export function runConnect(options: ConnectOptions, io: ConnectIo): ConnectResult { + const url = mcpUrl(options, io); + const targets = options.tools ?? [...TOOL_IDS]; + const tools: ToolResult[] = []; + for (const id of targets) { + const detected = detect(id, io); + if (options.tools === null && !detected) { + tools.push({ tool: id, label: TOOL_LABELS[id], detected: false, status: 'skipped_not_detected' }); + continue; + } + tools.push(applyTool(io, id, url, options.dryRun)); + } + return { ok: true, mcp_url: url, dry_run: options.dryRun, tools }; +} + +/** The human-readable output of {@link runConnect}. */ +export function formatConnect(result: ConnectResult): string { + const lines: string[] = [`MCP server: ${result.mcp_url}${result.dry_run ? ' (dry run, nothing written)' : ''}`, '']; + for (const tool of result.tools) { + const mark = + tool.status === 'configured' + ? 'done' + : tool.status === 'already_configured' + ? 'already set up' + : tool.status === 'would_configure' + ? 'would configure' + : tool.status === 'skipped_not_detected' + ? 'not detected, skipped' + : 'FAILED'; + lines.push(` ${tool.label.padEnd(12)} ${mark}${tool.path ? ` (${tool.path})` : ''}${tool.detail ? ` ${tool.detail}` : ''}`); + } + lines.push(''); + if (!result.dry_run && result.tools.some((tool) => tool.status === 'configured')) { + lines.push('Restart or reload the configured tool(s) to pick up the new server.', ''); + } + return lines.join('\n'); +} + +export const CONNECT_HELP = `Usage: npx scribase connect [tool...] [--tool ]... [--dry-run] [--json] [--api-url ] + +Writes the Scribase MCP server (https://api.scribase.com/mcp) into every AI +coding tool this machine has installed: ${TOOL_IDS.join(', ')}. + +With no tool named, only tools actually detected on this machine (a config +directory or a binary on PATH) are configured; everything else is reported +as "not detected, skipped". Naming one or more tools (as arguments or +repeated --tool) configures exactly those, regardless of detection. + +Every write is idempotent: an identical entry already there is left alone. +No access token or secret is ever written; tools that support MCP OAuth +(Claude Code, Cursor, VS Code, Codex) authenticate in the browser on first +use instead. + + --dry-run show what would change; write nothing + --json print one JSON object + --tool configure only this tool (repeatable) + --api-url control plane (default: SCRIBASE_API_URL or https://api.scribase.com) +`; + +/** The real-process IO for `connect`. */ +export function nodeConnectIo(json: boolean): ConnectIo { + const which = (command: string): boolean => { + const probe = + process.platform === 'win32' ? spawnSync('where', [command], { encoding: 'utf8' }) : spawnSync('command', ['-v', command], { encoding: 'utf8', shell: true }); + return probe.status === 0; + }; + void json; // reserved: nothing is logged outside the one JSON/text result line today. + return { + cwd: process.cwd(), + home: homedir(), + env: process.env, + readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null), + writeFile: (path, contents) => { + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, contents); + }, + exists: (path) => existsSync(path), + which, + run: (command, args) => { + const result = spawnSync(command, args, { encoding: 'utf8' }); + return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}` }; + }, + }; +} + +/** Entry point for the `connect` command; returns the exit code. */ +export function connectMain(argv: string[], io: ConnectIo, write: (text: string) => void): number { + if (argv.includes('--help') || argv.includes('-h')) { + write(CONNECT_HELP); + return 0; + } + try { + const options = parseConnectArgs(argv); + const result = runConnect(options, io); + write(options.json ? `${JSON.stringify(result)}\n` : formatConnect(result)); + return result.tools.some((tool) => tool.status === 'failed') ? 1 : 0; + } catch (error) { + const failure = + error instanceof InitError + ? { code: error.code, message: error.message, next: error.next ?? null } + : { code: 'unexpected_error', message: (error as Error).message, next: null }; + const json = argv.includes('--json'); + write(json ? `${JSON.stringify({ ok: false, error: failure })}\n` : `scribase connect: ${failure.message}\n${failure.next ? ` next: ${failure.next}\n` : ''}`); + return 1; + } +} diff --git a/src/cli/credentials.ts b/src/cli/credentials.ts new file mode 100644 index 0000000..e47dd03 --- /dev/null +++ b/src/cli/credentials.ts @@ -0,0 +1,160 @@ +/** + * Stored CLI credentials, shared with the Rust `scribase` CLI: + * `$XDG_CONFIG_HOME/scribase/credentials` (default `~/.config/scribase`), + * mode 0600, holding `api_url` and either `access_token` or + * `token_store=keychain`, in which case the token lives in the OS credential + * store (macOS keychain via `security`, Linux Secret Service via + * `secret-tool`) under service `scribase`, account = the API URL. The token + * is handed to those tools on standard input, never as an argument. + * `SCRIBASE_NO_KEYCHAIN=1` forces the file. + */ + +import { spawnSync } from 'node:child_process'; +import { randomUUID } from 'node:crypto'; +import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs'; +import { homedir } from 'node:os'; +import { dirname, join } from 'node:path'; + +const SERVICE = 'scribase'; + +export interface StoredCredentials { + apiUrl?: string; + token?: string; +} + +export function configDir(env: NodeJS.ProcessEnv): string { + return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'scribase'); +} + +export function credentialsPath(env: NodeJS.ProcessEnv): string { + return join(configDir(env), 'credentials'); +} + +/** Parses the credentials file (`key=value` lines). */ +export function parseCredentialsFile(text: string): { apiUrl?: string; token?: string; tokenStore?: string } { + const out: { apiUrl?: string; token?: string; tokenStore?: string } = {}; + for (const line of text.split('\n')) { + const at = line.indexOf('='); + if (at < 0) continue; + const key = line.slice(0, at).trim(); + const value = line.slice(at + 1).trim(); + if (!value) continue; + if (key === 'api_url') out.apiUrl = value; + if (key === 'access_token') out.token = value; + if (key === 'token_store') out.tokenStore = value; + } + return out; +} + +type Store = 'mac' | 'secret-service'; + +function keychain(env: NodeJS.ProcessEnv): Store | null { + if (env.SCRIBASE_NO_KEYCHAIN && env.SCRIBASE_NO_KEYCHAIN !== '0') return null; + const store: Store | null = process.platform === 'darwin' ? 'mac' : process.platform === 'linux' ? 'secret-service' : null; + if (!store) return null; + const probe = spawnSync(store === 'mac' ? 'security' : 'secret-tool', ['--help'], { stdio: 'ignore' }); + return probe.error ? null : store; +} + +function safeAccount(account: string): boolean { + return account.length > 0 && account.length <= 512 && !/["\\\u0000-\u001f]/.test(account); +} + +const TOKEN_SHAPE = /^[A-Za-z0-9._~+/=-]{1,16384}$/; + +/** The `security -i` command that saves a token; the token rides on stdin. */ +export function macStoreCommand(account: string, token: string): string { + return `add-generic-password -U -s ${SERVICE} -l "Scribase CLI" -a "${account}" -w "${token}"\n`; +} + +function keychainLoad(store: Store, account: string): string | undefined { + if (!safeAccount(account)) return undefined; + const result = + store === 'mac' + ? spawnSync('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w'], { encoding: 'utf8' }) + : spawnSync('secret-tool', ['lookup', 'service', SERVICE, 'account', account], { encoding: 'utf8' }); + const token = (result.stdout ?? '').trim(); + return result.status === 0 && TOKEN_SHAPE.test(token) ? token : undefined; +} + +function keychainSave(store: Store, account: string, token: string): boolean { + if (!safeAccount(account) || !TOKEN_SHAPE.test(token)) return false; + const result = + store === 'mac' + ? spawnSync('security', ['-i'], { input: macStoreCommand(account, token), stdio: ['pipe', 'ignore', 'ignore'] }) + : spawnSync('secret-tool', ['store', '--label=Scribase CLI', 'service', SERVICE, 'account', account], { + input: token, + stdio: ['pipe', 'ignore', 'ignore'], + }); + // `security -i` exits 0 even when its command fails: read it back. + return result.status === 0 && keychainLoad(store, account) === token; +} + +function writePrivate(path: string, contents: string): void { + mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); + writeFileSync(path, contents, { mode: 0o600 }); + // Tighten a file that existed with a wider mode. + chmodSync(path, 0o600); +} + +/** Reads the stored API URL and token (from the keychain when recorded there). */ +export function readCredentials(env: NodeJS.ProcessEnv): StoredCredentials { + const path = credentialsPath(env); + if (!existsSync(path)) return {}; + const parsed = parseCredentialsFile(readFileSync(path, 'utf8')); + const out: StoredCredentials = {}; + if (parsed.apiUrl) out.apiUrl = parsed.apiUrl; + if (parsed.token) out.token = parsed.token; + if (!out.token && parsed.tokenStore === 'keychain' && parsed.apiUrl) { + const store = keychain(env); + const token = store ? keychainLoad(store, parsed.apiUrl) : undefined; + if (token) out.token = token; + } + return out; +} + +/** Stores a token for `apiUrl`; returns where it went (for display). Never prints it. */ +export function storeCredentials(env: NodeJS.ProcessEnv, apiUrl: string, token: string): string { + const path = credentialsPath(env); + const store = keychain(env); + if (store && keychainSave(store, apiUrl, token)) { + writePrivate(path, `api_url=${apiUrl}\ntoken_store=keychain\n`); + return store === 'mac' ? 'the macOS keychain' : 'the Secret Service keyring'; + } + writePrivate(path, `api_url=${apiUrl}\naccess_token=${token}\n`); + return path; +} + +/** The pending device login, kept between `--no-wait` runs (0600). */ +export function pendingStore(env: NodeJS.ProcessEnv): { read: () => string | null; write: (text: string) => void; clear: () => void } { + const path = join(configDir(env), 'pending-login'); + return { + read: () => (existsSync(path) ? readFileSync(path, 'utf8') : null), + write: (text) => writePrivate(path, text), + clear: () => rmSync(path, { force: true }), + }; +} + +/** + * This machine's anonymous CLI install id: a random id created once in + * `/install-id` (mode 0600). It rides on claim links as `?ref=` + * so a claim can be credited to where the project came from. It carries no + * personal data. `SCRIBASE_NO_REF=1` sends none. Returns null when the file + * cannot be read or written. + */ +export function installId(env: NodeJS.ProcessEnv, random: () => string = () => randomUUID().replace(/-/g, '')): string | null { + if (env.SCRIBASE_NO_REF === '1') return null; + const path = join(configDir(env), 'install-id'); + try { + if (existsSync(path)) { + const value = readFileSync(path, 'utf8').trim(); + if (/^[A-Za-z0-9_-]{8,64}$/.test(value)) return value; + } + const value = random(); + mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); + writeFileSync(path, `${value}\n`, { mode: 0o600 }); + return value; + } catch { + return null; + } +} diff --git a/src/cli/doctor.ts b/src/cli/doctor.ts new file mode 100644 index 0000000..6d3a3ef --- /dev/null +++ b/src/cli/doctor.ts @@ -0,0 +1,304 @@ +/** + * `npx scribase doctor` — checks that this app can reach its Scribase backend + * and prints one fix per problem: + * + * - the project link (`.scribase/project.json`) and the env file exist; + * - the URL and publishable (anon) key variables are set and well formed; + * - the secret (service-role) key is not in a variable the framework ships to + * the browser or app bundle; + * - the env file is ignored by git; + * - the backend answers: Auth health and the REST API, with the app's key; + * - a temporary project is not expired or about to expire. + * + * Values are never printed, only variable names. All I/O goes through + * {@link DoctorIo} so the checks run offline in tests. + */ + +import { conventionsFor, detectFramework } from './framework.js'; +import type { Framework, ProjectFacts } from './framework.js'; +import { ensureIgnored, readEnvValue } from './envfile.js'; + +export type CheckStatus = 'ok' | 'problem' | 'warning'; + +export interface DoctorCheck { + id: string; + status: CheckStatus; + detail: string; + /** One concrete fix, set for problems and warnings. */ + fix?: string; +} + +export interface DoctorResult { + ok: boolean; + framework: Framework; + env_file: string; + checks: DoctorCheck[]; +} + +export interface DoctorIo { + cwd: string; + fetch: typeof fetch; + readFile: (path: string) => string | null; + exists: (path: string) => boolean; + /** Wall clock in milliseconds. */ + now: () => number; +} + +/** Prefixes a framework exposes to client bundles. */ +const PUBLIC_PREFIXES = ['NEXT_PUBLIC_', 'EXPO_PUBLIC_', 'VITE_', 'PUBLIC_', 'REACT_APP_']; +const EXPIRY_WARNING_SECONDS = 24 * 3600; +const PROBE_TIMEOUT_MS = 8000; + +interface State { + temporary?: boolean; + claim_url?: string; + expires_at?: number; + organization_id?: string; + project_id?: string; +} + +function join(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +/** The JWT payload's `role`, or null when `value` is not a readable JWT. */ +export function jwtRole(value: string): string | null { + const parts = value.split('.'); + if (parts.length !== 3 || !parts[1]) return null; + try { + const json = Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'); + const payload = JSON.parse(json) as { role?: unknown }; + return typeof payload.role === 'string' ? payload.role : null; + } catch { + return null; + } +} + +/** Whether `value` is shaped like a publishable key (a JWT, or an `sb_publishable_` key). */ +export function looksLikePublicKey(value: string): boolean { + return value.startsWith('sb_publishable_') || value.split('.').length === 3; +} + +/** Every `NAME=value` pair in an env file (last one wins). */ +export function envEntries(contents: string): Map { + const out = new Map(); + for (const line of contents.split(/\r?\n/)) { + const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line); + const name = match?.[1]; + if (!name) continue; + const value = readEnvValue(line, name); + if (value !== undefined) out.set(name, value); + } + return out; +} + +/** Public variables that hold a secret (service-role) key. */ +export function leakedSecretVars(entries: Map, serviceKey: string | undefined): string[] { + const leaked: string[] = []; + for (const [name, value] of entries) { + if (!PUBLIC_PREFIXES.some((prefix) => name.startsWith(prefix)) || value.length === 0) continue; + if ((serviceKey && value === serviceKey) || jwtRole(value) === 'service_role' || value.startsWith('sb_secret_')) { + leaked.push(name); + } + } + return leaked.sort(); +} + +async function probe(io: DoctorIo, url: string, key: string): Promise<{ status: number } | { error: string }> { + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS); + try { + const response = await io.fetch(url, { + method: 'GET', + headers: { apikey: key, authorization: `Bearer ${key}`, accept: 'application/json', 'user-agent': 'scribase-doctor' }, + signal: controller.signal, + }); + await response.text().catch(() => ''); + return { status: response.status }; + } catch (error) { + return { error: (error as Error).name === 'AbortError' ? `no answer within ${PROBE_TIMEOUT_MS / 1000} s` : (error as Error).message }; + } finally { + clearTimeout(timer); + } +} + +function readState(io: DoctorIo): State | null { + const text = io.readFile(join(io.cwd, '.scribase/project.json')); + if (!text) return null; + try { + return JSON.parse(text) as State; + } catch { + return null; + } +} + +function temporaryCheck(state: State, now: number): DoctorCheck | null { + if (!state.temporary || !state.expires_at) return null; + const left = state.expires_at - Math.floor(now / 1000); + const keep = state.claim_url ? `open the claim link in .scribase/project.json (claim_url), sign up and add a card` : 'open the claim link init printed'; + if (left <= 0) { + return { + id: 'temporary_expiry', + status: 'problem', + detail: 'this temporary project expired and was deleted', + fix: 'run `npx scribase init` again for a new one (or `npx scribase init --account` to use an account)', + }; + } + const hours = Math.floor(left / 3600); + const minutes = Math.floor((left % 3600) / 60); + const remaining = hours > 0 ? `${hours} h ${minutes} min` : `${minutes} min`; + if (left < EXPIRY_WARNING_SECONDS) { + return { id: 'temporary_expiry', status: 'warning', detail: `this temporary project is deleted in ${remaining}`, fix: `to keep it, ${keep}` }; + } + return { id: 'temporary_expiry', status: 'ok', detail: `temporary project, deleted in ${remaining} unless claimed` }; +} + +/** Runs every check. Never throws for a failed check; each becomes a result line. */ +export async function runDoctor(io: DoctorIo): Promise { + const exists = (relative: string) => io.exists(join(io.cwd, relative)); + let packageJson: ProjectFacts['packageJson'] = null; + const checks: DoctorCheck[] = []; + const packageText = io.readFile(join(io.cwd, 'package.json')); + if (packageText) { + try { + packageJson = JSON.parse(packageText) as ProjectFacts['packageJson']; + } catch { + checks.push({ id: 'package_json', status: 'problem', detail: 'package.json is not valid JSON', fix: 'fix the JSON syntax in package.json' }); + } + } + const facts = { packageJson, exists }; + const framework = detectFramework(facts); + const conventions = conventionsFor(framework, facts); + const done = (): DoctorResult => ({ + ok: checks.every((check) => check.status !== 'problem'), + framework, + env_file: conventions.envFile, + checks, + }); + + const state = readState(io); + checks.push( + state + ? { id: 'project_link', status: 'ok', detail: `linked to ${state.organization_id ?? '?'}/${state.project_id ?? '?'}` } + : { id: 'project_link', status: 'warning', detail: 'no .scribase/project.json in this folder', fix: 'run `npx scribase init` here to link a backend' }, + ); + + const envText = io.readFile(join(io.cwd, conventions.envFile)); + if (envText === null) { + checks.push({ id: 'env_file', status: 'problem', detail: `${conventions.envFile} is missing`, fix: 'run `npx scribase init` to write it' }); + return done(); + } + checks.push({ id: 'env_file', status: 'ok', detail: `${conventions.envFile} found` }); + const entries = envEntries(envText); + + const url = entries.get(conventions.urlVar) ?? ''; + let parsedUrl: URL | null = null; + try { + parsedUrl = url ? new URL(url) : null; + } catch { + parsedUrl = null; + } + if (!url) { + checks.push({ id: 'url', status: 'problem', detail: `${conventions.urlVar} is not set`, fix: 'run `npx scribase init` to write it' }); + } else if (!parsedUrl || !/^https?:$/.test(parsedUrl.protocol)) { + checks.push({ id: 'url', status: 'problem', detail: `${conventions.urlVar} is not a URL`, fix: 'run `npx scribase init` to rewrite it' }); + } else { + checks.push({ id: 'url', status: 'ok', detail: `${conventions.urlVar} is set (${parsedUrl.host})` }); + } + + const anon = entries.get(conventions.anonKeyVar) ?? ''; + const anonRole = anon ? jwtRole(anon) : null; + if (!anon) { + checks.push({ id: 'anon_key', status: 'problem', detail: `${conventions.anonKeyVar} is not set`, fix: 'run `npx scribase init` to write it' }); + } else if (anonRole === 'service_role' || anon.startsWith('sb_secret_')) { + checks.push({ + id: 'anon_key', + status: 'problem', + detail: `${conventions.anonKeyVar} holds the secret key, not the publishable one`, + fix: 'rotate the secret key in the console (API keys), then run `npx scribase init` to write the publishable key', + }); + } else if (!looksLikePublicKey(anon)) { + checks.push({ id: 'anon_key', status: 'problem', detail: `${conventions.anonKeyVar} does not look like a key`, fix: 'run `npx scribase init` to rewrite it' }); + } else { + checks.push({ id: 'anon_key', status: 'ok', detail: `${conventions.anonKeyVar} is set` }); + } + + const leaked = leakedSecretVars(entries, conventions.serviceRoleVar ? entries.get(conventions.serviceRoleVar) : undefined).filter( + (name) => name !== conventions.anonKeyVar, + ); + checks.push( + leaked.length > 0 + ? { + id: 'secret_exposure', + status: 'problem', + detail: `the secret key is in ${leaked.join(', ')}, which ships to the browser or app bundle`, + fix: `remove ${leaked.join(', ')} and rotate the secret key in the console (API keys)`, + } + : { id: 'secret_exposure', status: 'ok', detail: 'no secret key in a public variable' }, + ); + + const gitignore = io.readFile(join(io.cwd, '.gitignore')) ?? ''; + checks.push( + ensureIgnored(gitignore, conventions.envFile) === null + ? { id: 'gitignore', status: 'ok', detail: `${conventions.envFile} is ignored by git` } + : { id: 'gitignore', status: 'problem', detail: `${conventions.envFile} is not in .gitignore`, fix: `add ${conventions.envFile} to .gitignore before you commit` }, + ); + + if (state) { + const expiry = temporaryCheck(state, io.now()); + if (expiry) checks.push(expiry); + if (state.temporary && !entries.get('SCRIBASE_ACCESS_TOKEN')) { + checks.push({ + id: 'agent_token', + status: 'warning', + detail: `SCRIBASE_ACCESS_TOKEN is not in ${conventions.envFile}, so migrations and SQL from this folder cannot reach the temporary project`, + fix: 'run `npx scribase init` again to restore it', + }); + } + } + + if (parsedUrl && anon && looksLikePublicKey(anon)) { + const base = url.replace(/\/+$/, ''); + const auth = await probe(io, `${base}/auth/v1/health`, anon); + if ('error' in auth) { + checks.push({ id: 'reach_auth', status: 'problem', detail: `could not reach ${parsedUrl.host}: ${auth.error}`, fix: 'check your network, then the URL; a paused project wakes on this request, so try again in a minute' }); + } else if (auth.status >= 200 && auth.status < 300) { + checks.push({ id: 'reach_auth', status: 'ok', detail: 'Auth answers' }); + } else { + checks.push({ + id: 'reach_auth', + status: 'problem', + detail: `Auth answered HTTP ${auth.status}`, + fix: auth.status === 404 ? 'the project no longer exists: run `npx scribase init`' : 'wait a minute (the project may be starting) and run doctor again', + }); + } + const rest = await probe(io, `${base}/rest/v1/`, anon); + if ('error' in rest) { + checks.push({ id: 'reach_rest', status: 'problem', detail: `the REST API did not answer: ${rest.error}`, fix: 'try again in a minute; if it persists, open the project in the console' }); + } else if (rest.status === 401 || rest.status === 403) { + checks.push({ id: 'reach_rest', status: 'problem', detail: `the REST API refused ${conventions.anonKeyVar} (HTTP ${rest.status})`, fix: 'the key belongs to another project or was rotated: run `npx scribase init` to rewrite it' }); + } else if (rest.status >= 500) { + checks.push({ id: 'reach_rest', status: 'problem', detail: `the REST API answered HTTP ${rest.status}`, fix: 'wait a minute (the project may be starting) and run doctor again' }); + } else { + checks.push({ id: 'reach_rest', status: 'ok', detail: 'the REST API accepts the key' }); + } + } + return done(); +} + +/** Plain-text report: one line per check, a fix under each problem. */ +export function formatDoctor(result: DoctorResult): string { + const mark: Record = { ok: 'ok ', problem: 'PROBLEM', warning: 'warning' }; + const lines = result.checks.flatMap((check) => [ + ` ${mark[check.status]} ${check.detail}`, + ...(check.fix && check.status !== 'ok' ? [` fix: ${check.fix}`] : []), + ]); + const problems = result.checks.filter((check) => check.status === 'problem').length; + return [ + `scribase doctor (${result.framework}, ${result.env_file})`, + ...lines, + '', + problems === 0 ? 'No problems found.' : `${problems} problem${problems === 1 ? '' : 's'} found.`, + '', + ].join('\n'); +} diff --git a/src/cli/envfile.ts b/src/cli/envfile.ts new file mode 100644 index 0000000..42b198b --- /dev/null +++ b/src/cli/envfile.ts @@ -0,0 +1,159 @@ +/** + * Minimal `.env` editing: set keys without disturbing anything else in the + * file (comments, order, other variables), and make sure the file is ignored + * by git. Pure string functions; the caller does the I/O. + */ + +const KEY = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/; + +function quoteValue(value: string): string { + return /^[A-Za-z0-9_./:@+-]*$/.test(value) ? value : JSON.stringify(value); +} + +const HEADER = '# Scribase (written by `npx scribase init`)'; + +/** The comment a temporary project's note starts with; re-runs replace it. */ +export const TEMPORARY_NOTE_PREFIX = '# Temporary project, deleted '; + +/** + * Returns `existing` with every key in `values` set: replaced in place when + * present, appended (under a short header) when not. `notes` are comment + * lines kept right under the header (a temporary project's expiry and claim + * link); an earlier temporary note is replaced, never duplicated, so a re-run + * of `init` leaves exactly one. + */ +export function mergeEnv(existing: string, values: Record, notes: readonly string[] = []): string { + const remaining = new Map(Object.entries(values)); + const lines = existing.length > 0 ? existing.replace(/\r\n/g, '\n').split('\n') : []; + const updated = lines + .filter((line) => !(notes.length > 0 && line.startsWith(TEMPORARY_NOTE_PREFIX))) + .map((line) => { + const match = KEY.exec(line); + const key = match?.[1]; + if (key !== undefined && remaining.has(key)) { + const value = remaining.get(key) ?? ''; + remaining.delete(key); + return `${key}=${quoteValue(value)}`; + } + return line; + }); + while (updated.length > 0 && updated[updated.length - 1] === '') { + updated.pop(); + } + const comments = notes.map((note) => (note.startsWith('#') ? note : `# ${note}`)); + const header = updated.indexOf(HEADER); + if (remaining.size > 0) { + if (header < 0) { + if (updated.length > 0) updated.push(''); + updated.push(HEADER, ...comments); + } else { + updated.splice(header + 1, 0, ...comments); + } + for (const [key, value] of remaining) { + updated.push(`${key}=${quoteValue(value)}`); + } + } else if (comments.length > 0) { + if (header < 0) { + if (updated.length > 0) updated.push(''); + updated.push(HEADER, ...comments); + } else { + updated.splice(header + 1, 0, ...comments); + } + } + return `${updated.join('\n')}\n`; +} + +/** Reads one key from env file contents. */ +export function readEnvValue(contents: string, key: string): string | undefined { + for (const line of contents.split(/\r?\n/)) { + const match = KEY.exec(line); + if (match?.[1] === key) { + const raw = line.slice(line.indexOf('=') + 1).trim(); + if (raw.startsWith('"')) { + try { + return JSON.parse(raw) as string; + } catch { + return raw.slice(1, -1); + } + } + return raw; + } + } + return undefined; +} + +/** `.gitignore` contents that ignore `envFile`, or null when already ignored. */ +export function ensureIgnored(gitignore: string, envFile: string): string | null { + const patterns = gitignore.split(/\r?\n/).map((line) => line.trim()); + const covered = patterns.some( + (pattern) => + pattern === envFile || + pattern === `/${envFile}` || + pattern === '.env*' || + (envFile.endsWith('.local') && (pattern === '*.local' || pattern === '.env*.local')), + ); + if (covered) return null; + const base = gitignore.length === 0 || gitignore.endsWith('\n') ? gitignore : `${gitignore}\n`; + return `${base}${envFile}\n`; +} + +/** + * `.gitignore` contents that also ignore the directory `dir` (e.g. `.scribase`, + * which holds a temporary project's claim link), or null when already ignored. + */ +export function ensureDirIgnored(gitignore: string, dir: string): string | null { + const name = dir.replace(/^\/+|\/+$/g, ''); + const covered = gitignore + .split(/\r?\n/) + .map((line) => line.trim()) + .some((pattern) => [name, `${name}/`, `/${name}`, `/${name}/`, `${name}/*`, `/${name}/*`].includes(pattern)); + if (covered) return null; + const base = gitignore.length === 0 || gitignore.endsWith('\n') ? gitignore : `${gitignore}\n`; + return `${base}${name}/\n`; +} + +/** + * Value shapes that are secrets whatever the variable is called: service-role + * and secret keys, agent and access tokens, private keys, and URLs with a + * password. `scribase add` never writes one of these (SP-D1). + */ +const SECRET_VALUE = [ + /^sb_secret_/, + /^scb_(agt|pat|mt)_/, + /-----BEGIN [A-Z ]*PRIVATE KEY-----/, + /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i, +]; +/** Variable names that hold secrets. Public keys (anon, publishable) are allowed. */ +const SECRET_NAME = /(SECRET|PASSWORD|PASSWD|PRIVATE|SERVICE_ROLE|ACCESS_TOKEN|_PASS$|SMTP_PASS)/; + +/** True when `name=value` would put a secret in an env file or terminal. */ +export function isSecretEnv(name: string, value: string): boolean { + if (SECRET_NAME.test(name)) return true; + if (SECRET_VALUE.some((pattern) => pattern.test(value))) return true; + // A JWT whose payload says service_role. + const parts = value.split('.'); + if (parts.length === 3 && /^eyJ/.test(value)) { + try { + const payload = JSON.parse(Buffer.from(parts[1] ?? '', 'base64url').toString('utf8')) as { role?: unknown }; + if (payload.role === 'service_role') return true; + } catch { + return false; + } + } + return false; +} + +/** + * The entries of `values` that are safe to write, and the names refused as + * secrets. The caller writes only `safe`; refused names are reported by name, + * never by value. + */ +export function publicEnvOnly(values: Record): { safe: Record; refused: string[] } { + const safe: Record = {}; + const refused: string[] = []; + for (const [name, value] of Object.entries(values)) { + if (isSecretEnv(name, value)) refused.push(name); + else safe[name] = value; + } + return { safe, refused }; +} diff --git a/src/cli/framework.ts b/src/cli/framework.ts new file mode 100644 index 0000000..0b186c4 --- /dev/null +++ b/src/cli/framework.ts @@ -0,0 +1,253 @@ +/** + * Framework detection and the per-framework conventions `scribase init` + * follows: which env file to write, which variable names the framework exposes + * to client code, and where the client module goes. Pure: callers pass the + * facts about the directory in. + */ + +export type Framework = 'next' | 'expo' | 'vite' | 'sveltekit' | 'node'; + +export interface ProjectFacts { + /** Parsed package.json, or null when there is none. */ + packageJson: { dependencies?: Record; devDependencies?: Record } | null; + /** Whether a path relative to the project root exists. */ + exists: (relativePath: string) => boolean; +} + +export interface FrameworkConventions { + framework: Framework; + /** The env file the framework loads in development. */ + envFile: string; + /** Variable holding the project URL. */ + urlVar: string; + /** Variable holding the public (anon) key. */ + anonKeyVar: string; + /** + * Variable for the service-role key, or null where any env value can end up + * in a client bundle by mistake (Expo, Vite) — those projects never get it. + */ + serviceRoleVar: string | null; + /** Where the client module is written, relative to the root. */ + clientFile: string; + /** How client code reads a variable (`process.env.X` or `import.meta.env.X`). */ + readEnv: (name: string) => string; +} + +function hasDependency(facts: ProjectFacts, name: string): boolean { + const pkg = facts.packageJson; + return Boolean(pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name]); +} + +/** Detects the framework from package.json dependencies and config files. */ +export function detectFramework(facts: ProjectFacts): Framework { + if ( + hasDependency(facts, 'next') || + ['next.config.js', 'next.config.mjs', 'next.config.ts'].some((file) => facts.exists(file)) + ) { + return 'next'; + } + if (hasDependency(facts, 'expo') || facts.exists('app.json') && hasDependency(facts, 'react-native')) { + return 'expo'; + } + // SvelteKit is itself a Vite project (it ships vite.config.ts and depends + // on vite), so this check must come before the plain-Vite one below, or a + // SvelteKit app would get Vite's conventions (VITE_ vars read via + // `import.meta.env`, no server-side client) instead of its own ($env + // modules, and a real service-role key since SvelteKit has a server). + if ( + hasDependency(facts, '@sveltejs/kit') || + ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'].some((file) => facts.exists(file)) + ) { + return 'sveltekit'; + } + if ( + hasDependency(facts, 'vite') || + ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'].some((file) => facts.exists(file)) + ) { + return 'vite'; + } + return 'node'; +} + +/** The conventions for a framework in a given directory layout. */ +export function conventionsFor(framework: Framework, facts: ProjectFacts): FrameworkConventions { + const typescript = facts.exists('tsconfig.json'); + const extension = typescript ? 'ts' : 'js'; + const processEnv = (name: string) => `process.env.${name}`; + switch (framework) { + case 'next': + return { + framework, + envFile: '.env.local', + urlVar: 'NEXT_PUBLIC_SUPABASE_URL', + anonKeyVar: 'NEXT_PUBLIC_SUPABASE_ANON_KEY', + serviceRoleVar: 'SUPABASE_SERVICE_ROLE_KEY', + clientFile: `${facts.exists('src') ? 'src/' : ''}lib/supabase.${extension}`, + readEnv: processEnv, + }; + case 'expo': + return { + framework, + envFile: '.env', + urlVar: 'EXPO_PUBLIC_SUPABASE_URL', + anonKeyVar: 'EXPO_PUBLIC_SUPABASE_ANON_KEY', + serviceRoleVar: null, + clientFile: `${facts.exists('src') ? 'src/' : ''}lib/supabase.${extension}`, + readEnv: processEnv, + }; + case 'vite': + return { + framework, + envFile: '.env.local', + urlVar: 'VITE_SUPABASE_URL', + anonKeyVar: 'VITE_SUPABASE_ANON_KEY', + serviceRoleVar: null, + clientFile: `src/lib/supabase.${extension}`, + readEnv: (name) => `import.meta.env.${name}`, + }; + case 'sveltekit': + return { + framework, + // SvelteKit (via Vite) loads .env itself; unlike plain Vite, its own + // $env/static/public convention (not VITE_-prefixed import.meta.env) + // is what every SvelteKit + Supabase guide uses, so follow it exactly. + envFile: '.env', + urlVar: 'PUBLIC_SUPABASE_URL', + anonKeyVar: 'PUBLIC_SUPABASE_ANON_KEY', + // Unlike Vite/Expo (pure client bundles), SvelteKit has a real server + // (hooks.server.ts, +page.server.ts) that can hold the secret key + // behind $env/static/private, never shipped to the browser. + serviceRoleVar: 'SUPABASE_SERVICE_ROLE_KEY', + clientFile: `src/lib/supabase.${extension}`, + // Unused for sveltekit: clientSource imports the $env/static/public + // bindings by name instead of inlining a `readEnv` expression. + readEnv: (name) => name, + }; + case 'node': + return { + framework, + envFile: '.env', + urlVar: 'SUPABASE_URL', + anonKeyVar: 'SUPABASE_ANON_KEY', + serviceRoleVar: 'SUPABASE_SERVICE_ROLE_KEY', + clientFile: `${facts.exists('src') ? 'src/' : ''}supabase.${typescript ? 'ts' : 'mjs'}`, + readEnv: processEnv, + }; + } +} + +/** The client module `scribase init` writes (Scribase speaks the supabase-js API). */ +export function clientSource(conventions: FrameworkConventions): string { + const url = conventions.readEnv(conventions.urlVar); + const key = conventions.readEnv(conventions.anonKeyVar); + const typescript = conventions.clientFile.endsWith('.ts'); + // $env/static/public's exports are already typed `string` (SvelteKit fails + // the build itself if one is missing), so a non-null assertion would just + // be noise; every other framework's env read is typed as possibly + // undefined, where the assertion earns its place. + const bang = typescript && conventions.framework !== 'sveltekit' ? '!' : ''; + const lines = [ + "import { createClient } from '@supabase/supabase-js';", + ...(conventions.framework === 'sveltekit' ? [`import { ${conventions.urlVar}, ${conventions.anonKeyVar} } from '$env/static/public';`] : []), + '', + `// Written by \`npx scribase init\`. The values come from ${conventions.envFile}.`, + `export const supabase = createClient(${url}${bang}, ${key}${bang});`, + '', + ]; + if (conventions.framework === 'expo') { + lines.splice( + 2, + 0, + '// For sessions that survive app restarts, pass `auth: { storage: AsyncStorage }`', + '// from @react-native-async-storage/async-storage as the third argument.', + ); + } + if (conventions.framework === 'node') { + // Next.js/Vite/Expo each load their own env file before user code runs; + // plain Node does not. Without this, `process.env.SUPABASE_URL` is + // undefined the moment this file is imported and createClient throws + // "supabaseUrl is required." — the exact next step `scribase init` + // itself prints. `process.loadEnvFile` is a zero-dependency Node builtin + // (stable since Node 20.12; this package already requires >=22.13). + lines.splice( + 2, + 0, + "// Plain Node has no built-in env-file loading (unlike Next.js/Vite/Expo), so load it here.", + `try { process.loadEnvFile(); } catch { /* ${JSON.stringify(conventions.envFile)} is optional if the shell already sets these */ }`, + ); + } + return lines.join('\n'); +} + +/** The package manager a project uses, from its lockfile. */ +export function packageManager(exists: (relativePath: string) => boolean): 'pnpm' | 'yarn' | 'bun' | 'npm' { + if (exists('pnpm-lock.yaml')) return 'pnpm'; + if (exists('yarn.lock')) return 'yarn'; + if (exists('bun.lockb') || exists('bun.lock')) return 'bun'; + return 'npm'; +} + +/** The install command for supabase-js with a package manager. */ +export function installCommand(manager: 'pnpm' | 'yarn' | 'bun' | 'npm'): [string, string[]] { + const pkg = '@supabase/supabase-js'; + // npm's audit and funding lookups are extra registry round trips that add + // seconds to init and change nothing about the install. + return manager === 'npm' ? ['npm', ['install', pkg, '--no-audit', '--no-fund']] : [manager, ['add', pkg]]; +} + +/* ------------------------- native projects (PS2.4) ------------------------- */ + +/** A native app platform `scribase init` recognises without a package.json. */ +export type NativePlatform = 'flutter' | 'swift' | 'android' | 'python'; + +/** + * The native platform of a folder with no package.json: Flutter + * (pubspec.yaml), Swift (Package.swift), Android or Kotlin (Gradle settings or + * build files), Python (pyproject.toml or requirements.txt). A JavaScript + * project is never native. + */ +export function detectNative(facts: ProjectFacts): NativePlatform | null { + if (facts.packageJson) return null; + if (facts.exists('pubspec.yaml')) return 'flutter'; + if (facts.exists('Package.swift')) return 'swift'; + if (['settings.gradle.kts', 'settings.gradle', 'build.gradle.kts', 'build.gradle'].some((file) => facts.exists(file))) { + return 'android'; + } + if (['pyproject.toml', 'requirements.txt', 'setup.py'].some((file) => facts.exists(file))) return 'python'; + return null; +} + +/** What to do next in a native project: add the client library and type the tables. */ +export function nativeNextSteps( + platform: NativePlatform, + ref: { organization_id: string; project_id: string; environment_id: string }, +): string[] { + const types = (lang: string, out: string) => + `type your tables: scribase gen types ${ref.organization_id} ${ref.project_id} ${ref.environment_id} --lang ${lang} --out ${out} (full CLI)`; + switch (platform) { + case 'flutter': + return [ + 'add the client: flutter pub add supabase_flutter', + 'pass SUPABASE_URL and SUPABASE_ANON_KEY from .env with --dart-define-from-file (never the service role key)', + types('dart', 'lib/database_types.dart'), + ]; + case 'swift': + return [ + 'add the client: .package(url: "https://github.com/supabase/supabase-swift.git", from: "2.55.0")', + 'create SupabaseClient(supabaseURL:supabaseKey:) with SUPABASE_URL and SUPABASE_ANON_KEY from .env', + types('swift', 'Sources/DatabaseTypes.swift'), + ]; + case 'android': + return [ + 'add the client: implementation(platform("io.github.jan-tennert.supabase:bom:3.8.0")) with postgrest-kt and auth-kt', + 'put SUPABASE_URL and SUPABASE_ANON_KEY from .env into BuildConfig fields (never the service role key)', + types('kotlin', 'app/src/main/java/DatabaseTypes.kt'), + ]; + case 'python': + return [ + 'add the client: pip install supabase', + 'create_client(os.environ["SUPABASE_URL"], os.environ["SUPABASE_ANON_KEY"]) (the values are in .env)', + types('python', 'database_types.py'), + ]; + } +} diff --git a/src/cli/index.ts b/src/cli/index.ts new file mode 100644 index 0000000..792167e --- /dev/null +++ b/src/cli/index.ts @@ -0,0 +1,411 @@ +#!/usr/bin/env node +/** + * The `scribase` npm binary: `init`, `add`, `sql`, `migrate`, `login` and + * `doctor`. Everything else lives in the full Rust CLI (`scribase` from the + * releases page), which this binary points to. Both share the stored + * credentials (keychain or 0600 file). + */ + +import { spawn, spawnSync } from 'node:child_process'; +import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { dirname } from 'node:path'; + +import { addMain, nodeAddIo } from './add.js'; +import { nodeOtaIo, otaMain } from './capabilities/ota.js'; +import { connectMain, nodeConnectIo } from './connect.js'; +import { expandAlias } from './aliases.js'; +import { installId, pendingStore, readCredentials, storeCredentials } from './credentials.js'; +import { formatDoctor, runDoctor } from './doctor.js'; +import { InitError, parseInitArgs, runInit } from './init.js'; +import { formatMigrate, MIGRATIONS_DIR, parseMigrateArgs, runMigrate } from './migrate.js'; +import { formatSql, parseSqlArgs, runSql } from './sql.js'; +import type { InitIo } from './init.js'; +import type { SpawnOutcome } from './vercel.js'; +import { vercelLine } from './vercel.js'; +import { DEFAULT_SCOPE, LoginError, parseLoginArgs, publicResult, runLogin } from './login.js'; +import type { LoginIo, LoginOptions } from './login.js'; + +const HELP = `Usage: npx scribase init [options] + npx scribase add [--own] [--json] (see npx scribase add --help) + npx scribase deploy [--json] (the same as npx scribase add deploy) + npx scribase sql "" [--file ] [--confirm] [--json] + npx scribase migrate new (scaffold a migration file) + npx scribase migrate [--dry-run] [--json] (plan, lint and apply pending ones) + npx scribase ota [-p ios|android] (see npx scribase ota --help) + npx scribase connect [tool...] [--dry-run] [--json] (see npx scribase connect --help) + npx scribase doctor [--json] + npx scribase login [--json] [--no-wait] [--scope ]... [--name ] [--api-url ] [--no-browser] + +sql: runs SQL on the project this folder is connected to (after init), in one +transaction; new tables are visible to the REST API at once. Statements that +remove data (DROP, TRUNCATE, DELETE without WHERE) only run with --confirm. +Uses SCRIBASE_ACCESS_TOKEN, the env file init wrote, or \`scribase login\`. + +migrate: tracked, repeatable SQL migrations in ${MIGRATIONS_DIR}/*.sql. +\`migrate new \` scaffolds a timestamped file; \`migrate\` sends every +local file, oldest first, to this folder's project, which plans, lints (a +public table with no RLS policy blocks the whole run) and applies whatever +is not already in that environment's migration ledger. Re-running is always +safe: already-applied files are skipped. \`--dry-run\` plans and lints only. + +connect: writes the Scribase MCP server into every AI coding tool this +machine has (Claude Code, Cursor, VS Code, Codex, Windsurf, Zed) — one +command, idempotent, no token ever written (OAuth runs in the client). +Name one or more tools to configure exactly those; otherwise only tools +actually detected on this machine are touched. See \`npx scribase connect --help\`. + +doctor: checks this folder's env file, keys and the connection to the backend, +and prints one fix per problem. Never prints key values. Exits 1 on a problem. + +login: sign in without pasting a key. Prints a link and a code (and opens the +browser); a person approves in the console; a scoped, expiring agent token is +stored in the OS keychain (else ~/.config/scribase/credentials, mode 0600) and +never printed. --json prints {"event":"device_authorization",...} at once and +a final JSON line; --no-wait prints the link and exits (run again to finish). + +init: + +Connect this app to a Scribase backend in one step: detects Next.js, Expo, +SvelteKit, Vite or Node, creates (or reuses) a project, writes the env file, installs +@supabase/supabase-js and writes a client module. Not signed in? You get a +temporary project for 72 hours, no account needed, and a claim link to keep it +(sign up, free for 14 days, no card; the URL and keys stay the same). + +Options: + --temp always a temporary project, even when signed in + --account not signed in: approve this app in the browser and use your + account instead of a temporary project + --watch after init, wait for your app's first request and say when + it arrives (up to 10 minutes; --watch-seconds to change) + --yes, -y never prompt; use defaults + --json print one JSON object (for coding agents and scripts) + --name project name (default: this directory's name) + --org organization (default: your first one) + --region region (default: eu-frankfurt) + --api-url control plane (default: SCRIBASE_API_URL or https://api.scribase.com) + --token access token (default: SCRIBASE_ACCESS_TOKEN or \`scribase login\`) + --no-wait with --account: print the approval link and exit; run again after + --no-install do not install @supabase/supabase-js + --no-vercel do not touch the linked Vercel project (by default, when this + folder is linked with \`vercel link\`, the URL and keys are set for + development, preview and production with VERCEL_TOKEN or the + signed-in vercel CLI) + --wait how long to wait for the database (default: 300) +`; + +function openBrowser(url: string): void { + const [command, args] = + process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]]; + try { + spawn(command as string, args as string[], { stdio: 'ignore', detached: true }).unref(); + } catch { + // The link is printed anyway. + } +} + +function loginIo(json: boolean): LoginIo { + return { + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)), + now: () => Date.now(), + log: (line) => (json ? process.stderr.write(`${line}\n`) : process.stdout.write(`${line}\n`)), + emit: (value) => process.stdout.write(`${JSON.stringify(value)}\n`), + openBrowser, + interactive: Boolean(process.stdout.isTTY) && !json, + store: (apiUrl, token) => storeCredentials(process.env, apiUrl, token), + pending: pendingStore(process.env), + storedApiUrl: () => readCredentials(process.env).apiUrl, + }; +} + +const SPAWN_TIMEOUT_MS = 60_000; +const SPAWN_OUTPUT_LIMIT = 1024 * 1024; + +/** Runs a program without a shell; `input` goes to stdin, never argv. */ +function spawnWithInput(command: string, args: string[], options: { cwd: string; input?: string }): Promise { + return new Promise((resolve) => { + let stdout = ''; + let stderr = ''; + let child: ReturnType; + try { + child = spawn(command, args, { cwd: options.cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], timeout: SPAWN_TIMEOUT_MS }); + } catch (error) { + resolve({ code: null, stdout: '', stderr: (error as Error).message }); + return; + } + child.stdout?.on('data', (chunk: Buffer) => { + if (stdout.length < SPAWN_OUTPUT_LIMIT) stdout += chunk.toString('utf8'); + }); + child.stderr?.on('data', (chunk: Buffer) => { + if (stderr.length < SPAWN_OUTPUT_LIMIT) stderr += chunk.toString('utf8'); + }); + child.on('error', (error) => resolve({ code: null, stdout, stderr: error.message })); + child.on('close', (code) => resolve({ code, stdout, stderr })); + child.stdin?.on('error', () => {}); + child.stdin?.end(options.input ?? ''); + }); +} + +function nodeIo(json: boolean): InitIo { + return { + cwd: process.cwd(), + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null), + writeFile: (path, contents) => { + mkdirSync(dirname(path), { recursive: true }); + // Env files hold keys: owner-only. Source files keep the default mode. + writeFileSync(path, contents, /\.env(\.local)?$/.test(path) ? { mode: 0o600 } : {}); + }, + exists: (path) => existsSync(path), + run: (command, args, cwd) => { + const result = spawnSync(command, args, { cwd, encoding: 'utf8', shell: process.platform === 'win32' }); + return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}` }; + }, + spawn: spawnWithInput, + sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)), + // In --json mode stdout carries exactly one JSON document; notes go to stderr. + log: (line) => (json ? process.stderr.write(`${line}\n`) : process.stdout.write(`${line}\n`)), + credentials: () => readCredentials(process.env), + now: () => Date.now(), + installId: () => installId(process.env), + login: async (apiUrl, request) => { + // Inside init, --json keeps stdout for init's own result: the approval + // prompt goes to stderr as a JSON line. + const io = loginIo(request.json); + const options: LoginOptions = { + apiUrl, + json: request.json, + noWait: request.noWait, + browser: true, + scopes: [`project:${request.project}:write`, ...DEFAULT_SCOPE.split(' ').filter((scope) => !scope.startsWith('project:'))], + }; + const result = await runLogin(options, { + ...io, + emit: (value) => process.stderr.write(`${JSON.stringify(value)}\n`), + }); + return { + status: result.status, + ...(result.token ? { token: result.token } : {}), + ...(result.organization_id ? { organizationId: result.organization_id } : {}), + ...(result.user_code ? { userCode: result.user_code } : {}), + ...(result.verification_uri_complete ? { verificationUriComplete: result.verification_uri_complete } : {}), + }; + }, + }; +} + +async function login(argv: string[]): Promise { + const json = argv.includes('--json'); + try { + const result = await runLogin(parseLoginArgs(argv), loginIo(json)); + if (json) { + process.stdout.write(`${JSON.stringify(publicResult(result))}\n`); + } else if (result.status === 'approved') { + const project = result.project_id === '*' ? 'every project' : `project ${result.project_id}`; + process.stdout.write( + [ + `Logged in to ${result.organization_id} (${project}) with scopes: ${(result.scopes ?? []).join(', ')}.`, + `Token stored in ${result.stored_in} (never printed).`, + '', + ].join('\n'), + ); + } else { + process.stdout.write(`Not waiting (--no-wait): ${result.next}.\n`); + } + return 0; + } catch (error) { + const failure = + error instanceof LoginError + ? { code: error.code, message: error.message, ...error.details } + : { code: 'unexpected_error', message: (error as Error).message }; + if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: failure })}\n`); + else process.stderr.write(`scribase login: ${failure.message}\n`); + return 1; + } +} + +async function doctor(argv: string[]): Promise { + const json = argv.includes('--json'); + const unknown = argv.filter((arg) => arg !== '--json'); + if (unknown.length > 0) { + process.stderr.write(`scribase doctor: unknown option ${unknown[0]}\n`); + return 2; + } + const result = await runDoctor({ + cwd: process.cwd(), + fetch: globalThis.fetch.bind(globalThis), + readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null), + exists: (path) => existsSync(path), + now: () => Date.now(), + }); + process.stdout.write(json ? `${JSON.stringify(result)}\n` : formatDoctor(result)); + return result.ok ? 0 : 1; +} + +async function sql(argv: string[]): Promise { + const json = argv.includes('--json'); + const readFile = (path: string) => (existsSync(path) ? readFileSync(path, 'utf8') : null); + try { + const result = await runSql(parseSqlArgs(argv, readFile), { + cwd: process.cwd(), + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + readFile, + credentials: () => readCredentials(process.env), + }); + process.stdout.write(json ? `${JSON.stringify(result)}\n` : formatSql(result)); + return result.status === 'committed' ? 0 : 3; + } catch (error) { + const failure = + error instanceof InitError + ? { code: error.code, message: error.message, next: error.next ?? null } + : { code: 'unexpected_error', message: (error as Error).message, next: null }; + if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: failure })}\n`); + else process.stderr.write(`scribase sql: ${failure.message}\n${failure.next ? ` next: ${failure.next}\n` : ''}`); + return 1; + } +} + +async function migrate(argv: string[]): Promise { + const json = argv.includes('--json'); + const readFile = (path: string) => (existsSync(path) ? readFileSync(path, 'utf8') : null); + try { + const result = await runMigrate(parseMigrateArgs(argv), { + cwd: process.cwd(), + env: process.env, + fetch: globalThis.fetch.bind(globalThis), + readFile, + writeFile: (path, contents) => { + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, contents); + }, + listMigrationFiles: () => { + const dir = `${process.cwd()}/${MIGRATIONS_DIR}`; + if (!existsSync(dir)) return []; + return readdirSync(dir, { withFileTypes: true }) + .filter((entry) => entry.isFile()) + .map((entry) => entry.name); + }, + credentials: () => readCredentials(process.env), + now: () => new Date(), + }); + process.stdout.write(json ? `${JSON.stringify(result)}\n` : formatMigrate(result)); + return result.action === 'run' && result.blocked ? 3 : 0; + } catch (error) { + const failure = + error instanceof InitError + ? { code: error.code, message: error.message, next: error.next ?? null } + : { code: 'unexpected_error', message: (error as Error).message, next: null }; + if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: failure })}\n`); + else process.stderr.write(`scribase migrate: ${failure.message}\n${failure.next ? ` next: ${failure.next}\n` : ''}`); + return 1; + } +} + +async function main(argv: string[]): Promise { + const [command, ...rest] = expandAlias(argv); + if (!command || command === 'help' || command === '--help' || command === '-h') { + process.stdout.write(HELP); + return 0; + } + if (command === 'login') { + if (rest.includes('--help') || rest.includes('-h')) { + process.stdout.write(HELP); + return 0; + } + return login(rest); + } + if (command === 'doctor') { + if (rest.includes('--help') || rest.includes('-h')) { + process.stdout.write(HELP); + return 0; + } + return doctor(rest); + } + if (command === 'add') { + return addMain(rest, nodeAddIo(rest.includes('--json')), (text) => process.stdout.write(text)); + } + if (command === 'ota') { + return otaMain(rest, nodeOtaIo(rest.includes('--json')), (text) => process.stdout.write(text)); + } + if (command === 'connect') { + const json = rest.includes('--json'); + return connectMain(rest, nodeConnectIo(json), (text) => process.stdout.write(text)); + } + if (command === 'sql') { + if (rest.includes('--help') || rest.includes('-h')) { + process.stdout.write(HELP); + return 0; + } + return sql(rest); + } + if (command === 'migrate') { + if (rest.includes('--help') || rest.includes('-h')) { + process.stdout.write(HELP); + return 0; + } + return migrate(rest); + } + if (command !== 'init') { + process.stderr.write( + `scribase: the npm package has \`init\`, \`add\`, \`deploy\`, \`ota\`, \`connect\`, \`sql\`, \`migrate\`, \`doctor\` and \`login\`. For \`${command}\`, install the full CLI: https://scribase.com/docs/cli\n`, + ); + return 2; + } + if (rest.includes('--help') || rest.includes('-h')) { + process.stdout.write(HELP); + return 0; + } + const json = rest.includes('--json'); + try { + const options = parseInitArgs(rest); + const result = await runInit(options, nodeIo(json)); + if (json) { + process.stdout.write(`${JSON.stringify(result)}\n`); + } else { + process.stdout.write( + [ + `Live in ${result.live_in_seconds} s: ${result.api_url}`, + ` framework ${result.framework}`, + ` project ${result.organization_id}/${result.project_id} (${result.environment_id})${result.reused ? ', reused' : ''}`, + ` env file ${result.env_file} (${result.env_vars.join(', ')})`, + result.client_file ? ` client ${result.client_file}` : ' client (kept your existing file)', + ...(result.vercel.status === 'disabled' ? [] : [` vercel ${vercelLine(result.vercel)}`]), + ...(result.claim_url + ? [ + ` temporary deleted ${result.deleted_at_utc ?? new Date((result.expires_at ?? 0) * 1000).toISOString()} unless you keep it`, + ` keep it ${result.claim_url} (sign up + card, same URL and keys)`, + ] + : []), + ...(result.first_request_at === undefined + ? [] + : result.first_request_at === null + ? [' watch no request arrived yet'] + : [` watch your app just talked to your backend (${new Date(result.first_request_at * 1000).toISOString()})`]), + '', + 'Next:', + ...result.next_steps.map((step) => ` - ${step}`), + '', + ].join('\n'), + ); + } + return 0; + } catch (error) { + const failure = + error instanceof InitError + ? { code: error.code, message: error.message, next: error.next ?? null, ...(error.details ?? {}) } + : { code: 'unexpected_error', message: (error as Error).message, next: null }; + if (json) { + process.stdout.write(`${JSON.stringify({ ok: false, error: failure })}\n`); + } else { + process.stderr.write(`scribase init: ${failure.message}\n${failure.next ? ` next: ${failure.next}\n` : ''}`); + } + return 1; + } +} + +main(process.argv.slice(2)).then((code) => { + process.exitCode = code; +}); diff --git a/src/cli/init.ts b/src/cli/init.ts new file mode 100644 index 0000000..72f763d --- /dev/null +++ b/src/cli/init.ts @@ -0,0 +1,816 @@ +/** + * `npx scribase init` — one command from an empty app to a live backend, + * built for coding agents (Claude Code, Codex, Cursor, Windsurf) as much as + * for people: + * + * npx scribase init signed in (SCRIBASE_ACCESS_TOKEN or + * `scribase login`): create or reuse a project in + * your account. Not signed in: a temporary + * project for 72 hours, with a claim link to keep it + * npx scribase init --account not signed in, but use an account: approve this + * app in the browser (no key is ever pasted) + * npx scribase init --watch also wait for the app's first request + * + * It detects the framework (Next.js, Expo, SvelteKit, Vite, plain Node), provisions or + * reuses a project, writes the framework's env file with the right variable + * names, installs `@supabase/supabase-js` (Scribase speaks its API), writes a + * small client module, and prints what to do next — as JSON with `--json`. + * + * All I/O goes through {@link InitIo} so the flow is testable offline. + */ + +import { clientSource, conventionsFor, detectFramework, detectNative, installCommand, nativeNextSteps, packageManager } from './framework.js'; +import type { Framework, FrameworkConventions, ProjectFacts } from './framework.js'; +import { ensureDirIgnored, ensureIgnored, mergeEnv, readEnvValue } from './envfile.js'; +import { solveChallenge } from './pow.js'; +import { syncVercel } from './vercel.js'; +import type { SpawnOutcome, VercelStatus, VercelTarget } from './vercel.js'; + +export const DEFAULT_API_URL = 'https://api.scribase.com'; +const STATE_DIR = '.scribase'; +export const STATE_FILE = `${STATE_DIR}/project.json`; +/** Where hosted Scribase runs (the control plane's temporary-project default too). */ +export const DEFAULT_REGION = 'eu-frankfurt'; +const ENVIRONMENT_ID = 'production'; +/** + * The first table the next steps suggest. A new project's database is empty, + * so the first query must create something before it can read it back. Row + * level security is on with a read-only policy, and the grant is explicit so + * the anon key can read it whatever the default privileges are. No `!`, `$` + * or backticks: the line is pasted inside double quotes in any shell. + */ +export const FIRST_TABLE_SQL = + "create table notes (id bigint generated always as identity primary key, body text not null); " + + "insert into notes (body) values ('hello from scribase'); " + + 'alter table notes enable row level security; ' + + 'create policy notes_read on notes for select using (true); ' + + 'grant select on notes to anon, authenticated'; +/** How long `--watch` waits for the first request by default (seconds). */ +const DEFAULT_WATCH_SECONDS = 600; + +export interface InitOptions { + yes: boolean; + json: boolean; + temp: boolean; + name?: string; + org?: string; + region?: string; + apiUrl?: string; + token?: string; + install: boolean; + /** Seconds to wait for the database to become ready. */ + waitSeconds: number; + /** With a device login: print the approval link and exit instead of waiting. */ + noWait: boolean; + /** Push the keys into the linked Vercel project (default: on; `--no-vercel`). */ + vercel: boolean; + /** Not signed in: approve an account in the browser instead of a temporary project. */ + account: boolean; + /** Wait for the app's first request after init (`--watch`). */ + watch: boolean; + /** Seconds `--watch` waits. */ + watchSeconds: number; + /** + * The monthly amount (cents) the person approved for a project that adds to + * the bill (`--confirm-billable`, from a `402 confirm_billable`; SB4). + * Never implied by `--yes`. + */ + confirmBillableCents?: number; +} + +/** What {@link InitIo.login} returns: a token approved in the browser. */ +export interface DeviceLoginOutcome { + status: 'approved' | 'pending'; + token?: string; + organizationId?: string; + userCode?: string; + verificationUriComplete?: string; +} + +export interface InitIo { + cwd: string; + env: Record; + fetch: typeof fetch; + readFile: (path: string) => string | null; + writeFile: (path: string, contents: string) => void; + exists: (path: string) => boolean; + run: (command: string, args: string[], cwd: string) => { ok: boolean; output: string }; + /** Runs a program without a shell, `input` on stdin (the signed-in `vercel` CLI). */ + spawn?: (command: string, args: string[], options: { cwd: string; input?: string }) => Promise; + sleep: (ms: number) => Promise; + log: (line: string) => void; + /** Stored CLI credentials (`scribase login`), if any. */ + credentials: () => { apiUrl?: string; token?: string }; + /** + * Signs in through the browser (RFC 8628 device login) asking for write + * access to `project`; absent in environments that cannot (then init asks + * for `scribase login` or `--temp`). + */ + login?: (apiUrl: string, request: { project: string; json: boolean; noWait: boolean }) => Promise; + /** Wall clock in milliseconds (for "Live in N s"); defaults to `Date.now`. */ + now?: () => number; + /** + * This machine's anonymous CLI install id (a random id stored next to the + * credentials), sent as `?ref=` on claim links; absent or null to send none. + */ + installId?: () => string | null; +} + +export interface InitResult { + ok: true; + framework: Framework; + temporary: boolean; + reused: boolean; + organization_id: string; + project_id: string; + environment_id: string; + api_url: string; + env_file: string; + env_vars: string[]; + client_file: string | null; + installed: boolean; + claim_url?: string; + expires_at?: number; + /** `expires_at` as "2026-11-15 10:00 UTC": when a temporary project is deleted. */ + deleted_at_utc?: string; + /** The one line to show a person: "Temporary project, deleted . Keep it: ". */ + keep?: string; + /** Measured seconds from the start of init until the backend answered ready. */ + live_in_seconds: number; + /** With `--watch`: when the app's first request was served (epoch seconds), or null if none came in time. */ + first_request_at?: number | null; + /** What happened with the linked Vercel project (never fails init). */ + vercel: { status: VercelStatus | 'disabled'; targets: VercelTarget[]; project_id?: string; error?: string }; + next_steps: string[]; +} + +export class InitError extends Error { + constructor( + readonly code: string, + message: string, + readonly next?: string, + readonly details?: Record, + ) { + super(message); + this.name = 'InitError'; + } +} + +interface Keys { + api_url: string | null; + anon_key: string; + service_role_key?: string | null; +} + +interface Provisioned { + organization_id: string; + project_id: string; + environment_id: string; + keys: Keys; + reused: boolean; + agentToken?: string; + claimUrl?: string; + expiresAt?: number; + temporaryId?: string; +} + +/** Parses `init` arguments. Unknown flags are an error, so typos never pass silently. */ +export function parseInitArgs(argv: string[]): InitOptions { + const options: InitOptions = { + yes: false, + json: false, + temp: false, + install: true, + waitSeconds: 300, + noWait: false, + vercel: true, + account: false, + watch: false, + watchSeconds: DEFAULT_WATCH_SECONDS, + }; + const valueFlags: Record void> = { + '--name': (value) => (options.name = value), + '--org': (value) => (options.org = value), + '--region': (value) => (options.region = value), + '--api-url': (value) => (options.apiUrl = value), + '--token': (value) => (options.token = value), + '--confirm-billable': (value) => { + const cents = Number(value); + if (!Number.isInteger(cents) || cents < 0 || cents > 10_000_000) { + throw new InitError( + 'invalid_argument', + '--confirm-billable takes the monthly_delta_cents the API named (a whole number of cents)', + ); + } + options.confirmBillableCents = cents; + }, + '--wait': (value) => { + const seconds = Number(value); + if (!Number.isInteger(seconds) || seconds < 0 || seconds > 3600) { + throw new InitError('invalid_argument', '--wait takes a number of seconds (0 to 3600)'); + } + options.waitSeconds = seconds; + }, + '--watch-seconds': (value) => { + const seconds = Number(value); + if (!Number.isInteger(seconds) || seconds < 1 || seconds > 3600) { + throw new InitError('invalid_argument', '--watch-seconds takes a number of seconds (1 to 3600)'); + } + options.watch = true; + options.watchSeconds = seconds; + }, + }; + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index] ?? ''; + const [flag, inline] = arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined]; + if (flag === '--yes' || flag === '-y') options.yes = true; + else if (flag === '--json') options.json = true; + else if (flag === '--temp' || flag === '--temporary') options.temp = true; + else if (flag === '--no-install') options.install = false; + else if (flag === '--no-wait') options.noWait = true; + else if (flag === '--no-vercel') options.vercel = false; + else if (flag === '--account' || flag === '--login') options.account = true; + else if (flag === '--watch') options.watch = true; + else if (flag !== undefined && flag in valueFlags) { + const value = inline ?? argv[++index]; + if (value === undefined || value.startsWith('--')) { + throw new InitError('invalid_argument', `${flag} needs a value`); + } + valueFlags[flag]?.(value); + } else { + throw new InitError('invalid_argument', `unknown option ${arg}`, 'run `npx scribase init --help`'); + } + } + if (options.temp && options.account) { + throw new InitError('invalid_argument', '--temp and --account exclude each other', 'pick one'); + } + return options; +} + +/** Lowercase letters, digits and hyphens, 3 to 40 characters, or `my-app`. */ +export function projectSlug(value: string | undefined): string { + const slug = (value ?? '') + .normalize('NFKD') + .replace(/[̀-ͯ]/g, '') + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, '') + .slice(0, 40) + .replace(/-+$/g, ''); + return slug.length >= 3 ? slug : 'my-app'; +} + +function join(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +class Api { + constructor( + private readonly io: InitIo, + readonly baseUrl: string, + private readonly token: string | undefined, + ) {} + + async call(method: string, path: string, body?: unknown, headers: Record = {}): Promise<{ status: number; body: T }> { + const init: RequestInit = { + method, + headers: { + accept: 'application/json', + 'user-agent': 'scribase-init', + ...(body === undefined ? {} : { 'content-type': 'application/json' }), + ...(this.token ? { authorization: `Bearer ${this.token}` } : {}), + ...headers, + }, + }; + if (body !== undefined) init.body = JSON.stringify(body); + let response: Response; + try { + response = await this.io.fetch(`${this.baseUrl}${path}`, init); + } catch (error) { + throw new InitError('network_error', `could not reach ${this.baseUrl}: ${(error as Error).message}`, 'check --api-url or SCRIBASE_API_URL'); + } + const text = await response.text(); + let parsed: unknown = null; + try { + parsed = text.length > 0 ? JSON.parse(text) : null; + } catch { + parsed = { detail: text.slice(0, 200) }; + } + return { status: response.status, body: parsed as T }; + } +} + +function problem(body: unknown): { code: string; detail: string } { + const value = (body ?? {}) as { code?: unknown; detail?: unknown }; + return { + code: typeof value.code === 'string' ? value.code : 'request_failed', + detail: typeof value.detail === 'string' ? value.detail : 'the request failed', + }; +} + +/** + * The next step for a `402` on project create: a card (the free trial ended, + * or was already used), or (SB4 and WP 3.6/3.8) the person's approval of what + * the project adds, a spend cap, a plan's project cap or the agent project + * limit. + */ +export function billingNextStep(problem: { code: string; detail: string }, consoleUrl: string): string { + switch (problem.code) { + case 'confirm_billable': { + const cents = /monthly_delta_cents (\d+)/.exec(problem.detail)?.[1]; + return cents + ? `this project adds $${(Number(cents) / 100).toFixed(Number(cents) % 100 === 0 ? 0 : 2)} a month; if the person approves, run this again with --confirm-billable ${cents}` + : 'ask the person to approve the charge, then run this again with --confirm-billable '; + } + case 'spend_cap_reached': + return `raise the monthly spend cap in Billing at ${consoleUrl}, or delete a project`; + case 'plan_project_cap': + return `switch plans in Billing at ${consoleUrl}, or delete a project`; + case 'agent_project_limit': + return `a person can raise the agent project limit in Billing at ${consoleUrl}`; + case 'email_verification_required': + return 'confirm your email address (the link we sent) to start the free trial, then run this again'; + default: + return problem.detail.toLowerCase().includes('trial') + ? `${problem.detail}: ${consoleUrl}/start, then run this again` + : `add a card at ${consoleUrl}/start, then run this again`; + } +} + +/** + * The console that belongs to an API origin: SCRIBASE_CONSOLE_URL when set, + * else `api.` -> `console.`, else hosted Scribase's console. + */ +export function consoleUrlFor(apiUrl: string, env: Record): string { + const explicit = env.SCRIBASE_CONSOLE_URL?.trim(); + if (explicit) return explicit.replace(/\/+$/, ''); + try { + const url = new URL(apiUrl); + if (url.hostname.startsWith('api.')) { + return `${url.protocol}//console.${url.hostname.slice('api.'.length)}`; + } + } catch { + // fall through to the hosted console + } + return 'https://console.scribase.com'; +} + +function fail(status: number, body: unknown, next?: string): never { + const { code, detail } = problem(body); + throw new InitError(code, `${detail} (HTTP ${status})`, next); +} + +function randomKey(prefix: string): string { + return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`; +} + +async function waitUntil(io: InitIo, seconds: number, probe: () => Promise, what: string): Promise { + const deadline = Date.now() + seconds * 1000; + let delay = 1000; + for (;;) { + const value = await probe(); + if (value !== null) return value; + if (Date.now() >= deadline) { + throw new InitError('timeout', `${what} is not ready yet`, 'run `npx scribase init` again in a minute; it picks up where it left off'); + } + await io.sleep(delay); + delay = Math.min(delay * 2, 5000); + } +} + +async function provisionTemporary(io: InitIo, api: Api, options: InitOptions): Promise { + const challenge = await api.call<{ challenge: string; bits: number }>('POST', '/v1/temporary-projects/challenge', {}); + if (challenge.status !== 200) { + fail(challenge.status, challenge.body, 'sign up and run `npx scribase init` without --temp'); + } + const bits = challenge.body.bits; + const payload: Record = { name: projectSlug(options.name ?? io.cwd.split('/').pop()) }; + if (bits > 0) { + payload.challenge = challenge.body.challenge; + payload.nonce = solveChallenge(challenge.body.challenge, bits); + } + const created = await api.call<{ + id: string; + organization_id: string; + project_id: string; + environment_id: string; + agent_token: string; + claim_url: string; + expires_at: number; + }>('POST', '/v1/temporary-projects', payload); + if (created.status !== 201) fail(created.status, created.body); + const project = created.body; + const agentApi = new Api(io, api.baseUrl, project.agent_token); + const keys = await waitUntil( + io, + options.waitSeconds, + async () => { + const status = await agentApi.call<{ status: string; keys: Keys | null }>('GET', `/v1/temporary-projects/${project.id}`); + if (status.status !== 200) fail(status.status, status.body); + if (status.body.status === 'failed') { + throw new InitError('provisioning_failed', 'the temporary database could not be created', 'try again, or sign up'); + } + return status.body.status === 'ready' && status.body.keys ? status.body.keys : null; + }, + 'the temporary database', + ); + return { + organization_id: project.organization_id, + project_id: project.project_id, + environment_id: project.environment_id, + keys, + reused: false, + agentToken: project.agent_token, + claimUrl: project.claim_url, + expiresAt: project.expires_at, + temporaryId: project.id, + }; +} + +/** + * The claim link with `?ref=` before the `#` + * fragment, so the claim page can credit where the project came from. An + * existing `ref` is kept; an invalid id is not added. + */ +/** `2026-11-15 10:00 UTC` from epoch seconds; the time a temporary project is deleted. */ +export function deletedAtUtc(expiresAt: number): string { + const iso = new Date(expiresAt * 1000).toISOString(); + return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`; +} + +/** + * The one line every surface prints for a temporary project, so the claim + * link is never only inside `.scribase/project.json`: + * "Temporary project, deleted 2026-11-15 10:00 UTC. Keep it: ". + * Found 2026-11-12: 69 temporary projects created, 0 claimed. + */ +export function temporaryNote(expiresAt: number | undefined, claimUrl: string): string { + const when = expiresAt ? deletedAtUtc(expiresAt) : 'when it expires'; + return `Temporary project, deleted ${when}. Keep it: ${claimUrl}`; +} + +export function claimUrlWithRef(claimUrl: string, ref: string | null | undefined): string { + if (!ref || !/^[A-Za-z0-9_-]{8,64}$/.test(ref)) return claimUrl; + const hash = claimUrl.indexOf('#'); + const base = hash < 0 ? claimUrl : claimUrl.slice(0, hash); + const fragment = hash < 0 ? '' : claimUrl.slice(hash); + if (/[?&]ref=/.test(base)) return claimUrl; + return `${base}${base.includes('?') ? '&' : '?'}ref=${ref}${fragment}`; +} + +/** + * `--watch`: polls the environment's first served request (the gateway log + * shipper records it) until it arrives or `seconds` pass. Never throws: a + * watch that cannot read the answer reports `null`. + */ +async function watchFirstRequest(io: InitIo, api: Api, provisioned: Provisioned, seconds: number): Promise { + const path = + `/v1/organizations/${encodeURIComponent(provisioned.organization_id)}` + + `/projects/${encodeURIComponent(provisioned.project_id)}` + + `/environments/${encodeURIComponent(provisioned.environment_id)}/first-request`; + const now = io.now ?? Date.now; + const deadline = now() + seconds * 1000; + io.log(`Watching for your app's first request (up to ${seconds} s). Run your app now.`); + for (;;) { + let answer: { status: number; body: { first_request_at?: number | null } }; + try { + answer = await api.call<{ first_request_at?: number | null }>('GET', path); + } catch { + return null; + } + if (answer.status !== 200) return null; + const at = answer.body?.first_request_at; + if (typeof at === 'number') return at; + if (now() >= deadline) return null; + await io.sleep(3000); + } +} + +async function environmentKeys(api: Api, organization: string, project: string, environment: string): Promise { + const path = `/v1/organizations/${encodeURIComponent(organization)}/projects/${encodeURIComponent(project)}/environments/${encodeURIComponent(environment)}`; + const env = await api.call<{ phase?: string }>('GET', path); + if (env.status === 404) return null; + if (env.status !== 200) fail(env.status, env.body); + if (env.body.phase === 'failed_recoverable') { + throw new InitError('provisioning_failed', 'the database failed to provision', 'open the console to see why'); + } + if (env.body.phase !== 'ready') return null; + const keys = await api.call('GET', `${path}/api-keys`); + if (keys.status !== 200) fail(keys.status, keys.body); + return keys.body; +} + +async function provisionWithAccount(io: InitIo, api: Api, options: InitOptions): Promise { + let organization = options.org; + if (!organization) { + const orgs = await api.call<{ items?: { organization_id: string }[] }>('GET', '/v1/organizations'); + if (orgs.status === 401) { + throw new InitError('unauthorized', 'the access token was refused', 'run `scribase login`, set SCRIBASE_ACCESS_TOKEN, or use --temp'); + } + if (orgs.status !== 200) fail(orgs.status, orgs.body); + organization = orgs.body.items?.[0]?.organization_id; + if (!organization) { + throw new InitError('no_organization', 'this account has no organization yet', 'finish sign-up in the console (it creates one), or use --temp'); + } + } + const project = projectSlug(options.name ?? io.cwd.split('/').pop()); + const region = options.region ?? DEFAULT_REGION; + const put = await api.call('PUT', `/v1/organizations/${encodeURIComponent(organization)}/projects/${encodeURIComponent(project)}`, { + region, + postgres_major: 17, + ...(options.confirmBillableCents === undefined ? {} : { confirm_billable_cents: options.confirmBillableCents }), + }); + if (put.status === 402) { + fail(put.status, put.body, billingNextStep(problem(put.body), consoleUrlFor(api.baseUrl, io.env))); + } + if (put.status !== 200 && put.status !== 201) fail(put.status, put.body); + const created = await api.call( + 'POST', + '/v1/environments', + { + organization_id: organization, + project_id: project, + environment_id: ENVIRONMENT_ID, + kind: 'production', + data_mode: 'schema_only', + region, + postgres_major: 17, + }, + { 'idempotency-key': randomKey('init-env') }, + ); + const reused = created.status === 409; + if (!reused && created.status !== 200 && created.status !== 201 && created.status !== 202) { + fail(created.status, created.body); + } + const keys = await waitUntil(io, options.waitSeconds, () => environmentKeys(api, organization, project, ENVIRONMENT_ID), 'the database'); + return { organization_id: organization, project_id: project, environment_id: ENVIRONMENT_ID, keys, reused }; +} + +interface SavedState { + organization_id: string; + project_id: string; + environment_id: string; + api_url: string; + temporary: boolean; + claim_url?: string; + expires_at?: number; + /** The temporary project's id (`tmp_...`), for its status and claim routes. */ + temporary_id?: string; +} + +function readState(io: InitIo): SavedState | null { + const text = io.readFile(join(io.cwd, STATE_FILE)); + if (!text) return null; + try { + const value = JSON.parse(text) as SavedState; + return value.organization_id && value.project_id && value.environment_id ? value : null; + } catch { + return null; + } +} + +function envValues(conventions: FrameworkConventions, provisioned: Provisioned, apiUrl: string): Record { + const projectUrl = provisioned.keys.api_url ?? ''; + const values: Record = { + [conventions.urlVar]: projectUrl, + [conventions.anonKeyVar]: provisioned.keys.anon_key, + }; + if (conventions.serviceRoleVar && provisioned.keys.service_role_key) { + values[conventions.serviceRoleVar] = provisioned.keys.service_role_key; + } + values.SCRIBASE_API_URL = apiUrl; + values.SCRIBASE_ORG = provisioned.organization_id; + values.SCRIBASE_PROJECT = provisioned.project_id; + values.SCRIBASE_ENV = provisioned.environment_id; + if (provisioned.agentToken) { + // The temporary project's own agent token (scoped to it, expires with it), + // so the agent can keep running migrations and SQL. + values.SCRIBASE_ACCESS_TOKEN = provisioned.agentToken; + } + return values; +} + +/** Writes the keys into the linked Vercel project; never throws. */ +async function pushToVercel(io: InitIo, provisioned: Provisioned, projectUrl: string): Promise { + const result = await syncVercel(io, { + organization: provisioned.organization_id, + project: provisioned.project_id, + environment: provisioned.environment_id, + apiUrl: projectUrl, + anonKey: provisioned.keys.anon_key, + serviceRoleKey: provisioned.keys.service_role_key ?? null, + }); + return { + status: result.status, + targets: result.targets, + ...(result.project_id ? { project_id: result.project_id } : {}), + ...(result.error ? { error: result.error } : {}), + }; +} + +/** Runs `scribase init`. Throws {@link InitError} with a code and a next step. */ +export async function runInit(initial: InitOptions, io: InitIo): Promise { + let options = initial; + const clock = io.now ?? Date.now; + const startedAt = clock(); + const exists = (relative: string) => io.exists(join(io.cwd, relative)); + const packageText = io.readFile(join(io.cwd, 'package.json')); + let packageJson: ProjectFacts['packageJson'] = null; + if (packageText) { + try { + packageJson = JSON.parse(packageText) as ProjectFacts['packageJson']; + } catch { + throw new InitError('invalid_package_json', 'package.json is not valid JSON'); + } + } + const facts = { packageJson, exists }; + const framework = detectFramework(facts); + // A Flutter, Swift, Android or Python project (PS2.4): the env file and + // the project, but no JavaScript client and no npm install. + const native = detectNative(facts); + const conventions = conventionsFor(framework, facts); + const stored = io.credentials(); + const apiUrl = (options.apiUrl ?? io.env.SCRIBASE_API_URL ?? stored.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''); + let token = options.token ?? io.env.SCRIBASE_ACCESS_TOKEN ?? stored.token; + const state = readState(io); + + const envPath = join(io.cwd, conventions.envFile); + const envContents = io.readFile(envPath) ?? ''; + + let provisioned: Provisioned | null = null; + if (state) { + // Re-running init reuses this directory's project. A temporary project is + // reached with its own agent token from the env file. + const reuseToken = state.temporary ? (readEnvValue(envContents, 'SCRIBASE_ACCESS_TOKEN') ?? token) : token; + if (reuseToken) { + try { + const api = new Api(io, apiUrl, reuseToken); + const keys = await waitUntil( + io, + options.waitSeconds, + () => environmentKeys(api, state.organization_id, state.project_id, state.environment_id), + 'the database', + ); + provisioned = { ...state, keys, reused: true }; + } catch (error) { + const gone = error instanceof InitError && ['unauthorized', 'forbidden', 'insufficient_scope', 'not_found'].includes(error.code); + if (!(state.temporary && gone)) throw error; + io.log('The temporary project of this directory expired: creating a new one.'); + } + } + } + if (!provisioned && options.account && !token) { + if (!io.login) { + throw new InitError('not_signed_in', 'not signed in to Scribase', 'run `npx scribase login`, or drop --account for a 72-hour temporary project'); + } + // Not signed in: ask the person to approve this app in the browser + // instead of asking them for a key. + const project = projectSlug(options.name ?? io.cwd.split('/').pop()); + const outcome = await io.login(apiUrl, { project, json: options.json, noWait: options.noWait }); + if (outcome.status === 'pending' || !outcome.token) { + throw new InitError( + 'authorization_pending', + `waiting for approval of code ${outcome.userCode ?? ''} at ${outcome.verificationUriComplete ?? 'the console'}`, + `ask the person to open ${outcome.verificationUriComplete ?? 'the link'} and approve code ${outcome.userCode ?? ''}, then run this command again`, + { user_code: outcome.userCode, verification_uri_complete: outcome.verificationUriComplete }, + ); + } + token = outcome.token; + if (!options.org && outcome.organizationId) options = { ...options, org: outcome.organizationId }; + } + if (!provisioned) { + if (options.temp || !token) { + // Temporary-first: no account needed to see it work. Claiming it later + // (sign up + card) keeps the same URL and keys. + if (!options.temp) io.log('Not signed in: creating a temporary project (72 hours; claim it to keep it, or use --account).'); + // Signed in and asking for --temp: the token makes the platform count + // this account's temporary projects, not the (office) address's. + provisioned = await provisionTemporary(io, new Api(io, apiUrl, token ?? undefined), options); + } else { + provisioned = await provisionWithAccount(io, new Api(io, apiUrl, token), options); + } + } + if (!provisioned.keys.api_url) { + throw new InitError('no_project_url', 'the deployment did not report a project URL', 'ask the operator to set SCRIBASE_GATEWAY_BASE_URL_TEMPLATE'); + } + const liveInSeconds = Math.max(0, Math.round((clock() - startedAt) / 100) / 10); + let installId: string | null = null; + try { + installId = io.installId?.() ?? null; + } catch { + installId = null; + } + const claimUrl = provisioned.claimUrl ? claimUrlWithRef(provisioned.claimUrl, installId) : undefined; + + const values = envValues(conventions, provisioned, apiUrl); + const temporary = Boolean(provisioned.agentToken) || Boolean(state?.temporary && provisioned.reused); + const noteClaimUrl = claimUrl ?? state?.claim_url; + const noteExpiresAt = provisioned.expiresAt ?? state?.expires_at; + // The env file is gitignored below and already holds the agent token, so + // the claim link (which is just as sensitive) belongs in the same place — + // next to the keys the person will actually open. + const notes = temporary && noteClaimUrl ? [temporaryNote(noteExpiresAt, noteClaimUrl)] : []; + io.writeFile(envPath, mergeEnv(envContents, values, notes)); + // Ignore the env file (keys, the agent token) and .scribase/ (a temporary + // project's claim link: whoever holds it can take the project over). + const gitignorePath = join(io.cwd, '.gitignore'); + const currentIgnore = io.readFile(gitignorePath) ?? ''; + const withEnv = ensureIgnored(currentIgnore, conventions.envFile) ?? currentIgnore; + const withState = ensureDirIgnored(withEnv, STATE_DIR) ?? withEnv; + if (withState !== currentIgnore) io.writeFile(gitignorePath, withState); + + const saved: SavedState = { + organization_id: provisioned.organization_id, + project_id: provisioned.project_id, + environment_id: provisioned.environment_id, + api_url: apiUrl, + temporary, + ...(claimUrl ? { claim_url: claimUrl } : state?.claim_url ? { claim_url: state.claim_url } : {}), + ...(provisioned.expiresAt ? { expires_at: provisioned.expiresAt } : state?.expires_at ? { expires_at: state.expires_at } : {}), + ...(provisioned.temporaryId ? { temporary_id: provisioned.temporaryId } : state?.temporary_id ? { temporary_id: state.temporary_id } : {}), + }; + io.writeFile(join(io.cwd, STATE_FILE), `${JSON.stringify(saved, null, 2)}\n`); + + // The backend is live and the env file is written: say so, with the claim + // link, before anything slow (the Vercel push, the dependency install). + // First-time visitors see a working URL within seconds (SG-D8). + io.log(`Backend ready in ${liveInSeconds} s: ${provisioned.keys.api_url} (keys written to ${conventions.envFile})`); + if (saved.claim_url && saved.temporary) { + io.log(temporaryNote(saved.expires_at, saved.claim_url)); + } + + const vercel = options.vercel ? await pushToVercel(io, provisioned, provisioned.keys.api_url) : { status: 'disabled' as const, targets: [] }; + + let clientFile: string | null = null; + if (!native && !exists(conventions.clientFile)) { + io.writeFile(join(io.cwd, conventions.clientFile), clientSource(conventions)); + clientFile = conventions.clientFile; + } + + let installed = false; + const alreadyInstalled = Boolean( + packageJson?.dependencies?.['@supabase/supabase-js'] ?? packageJson?.devDependencies?.['@supabase/supabase-js'], + ); + if (options.install && packageJson && !alreadyInstalled) { + const [command, args] = installCommand(packageManager(exists)); + io.log(`Installing @supabase/supabase-js with ${command} (your backend is already live)...`); + let outcome = io.run(command, args, io.cwd); + // npm refuses on peer-dependency conflicts (ERESOLVE) that don't affect + // supabase-js; retry once with npm's own escape hatch before giving up. + if (!outcome.ok && command === 'npm' && /ERESOLVE|legacy-peer-deps/.test(outcome.output)) { + outcome = io.run(command, [...args, '--legacy-peer-deps'], io.cwd); + } + if (!outcome.ok) { + throw new InitError('install_failed', `${command} ${args.join(' ')} failed: ${outcome.output.slice(-400)}`, `run \`${command} ${args.join(' ')}\` yourself`); + } + installed = true; + } else if (alreadyInstalled) { + installed = true; + } + + const importPath = `./${conventions.clientFile.replace(/\.(ts|js|mjs)$/, '')}`; + const nextSteps = [ + `create your first table (the database starts empty): npx scribase sql "${FIRST_TABLE_SQL}"`, + `import { supabase } from '${importPath}' and query it: await supabase.from('notes').select()`, + 'more tables: `npx scribase sql ""`, or tracked migrations with `npx scribase migrate new ` then `npx scribase migrate`, or the MCP server', + ]; + if (native) { + nextSteps.splice(1, 1, ...nativeNextSteps(native, provisioned)); + } else if (!packageJson) { + nextSteps.unshift('run `npm init -y && npm install @supabase/supabase-js` (no package.json here)'); + } + if (saved.claim_url) { + nextSteps.push( + `keep this project (deleted ${saved.expires_at ? deletedAtUtc(saved.expires_at) : 'when it expires'}): open ${saved.claim_url} — sign up, free for 14 days, no card; same URL and keys`, + ); + } + let firstRequestAt: number | null | undefined; + if (options.watch) { + const watchToken = provisioned.agentToken ?? (saved.temporary ? (readEnvValue(envContents, 'SCRIBASE_ACCESS_TOKEN') ?? token) : token); + firstRequestAt = await watchFirstRequest(io, new Api(io, apiUrl, watchToken), provisioned, options.watchSeconds); + if (firstRequestAt === null) { + nextSteps.push('no request reached the backend yet: run your app, then `npx scribase doctor` if it still cannot connect'); + } + } + return { + ok: true, + framework, + temporary: saved.temporary, + reused: provisioned.reused, + organization_id: provisioned.organization_id, + project_id: provisioned.project_id, + environment_id: provisioned.environment_id, + api_url: provisioned.keys.api_url, + env_file: conventions.envFile, + env_vars: Object.keys(values), + client_file: clientFile, + installed, + ...(saved.claim_url ? { claim_url: saved.claim_url } : {}), + ...(saved.expires_at ? { expires_at: saved.expires_at, deleted_at_utc: deletedAtUtc(saved.expires_at) } : {}), + ...(saved.claim_url && saved.temporary ? { keep: temporaryNote(saved.expires_at, saved.claim_url) } : {}), + live_in_seconds: liveInSeconds, + ...(firstRequestAt !== undefined ? { first_request_at: firstRequestAt } : {}), + vercel, + next_steps: nextSteps, + }; +} diff --git a/src/cli/login.ts b/src/cli/login.ts new file mode 100644 index 0000000..ee38f19 --- /dev/null +++ b/src/cli/login.ts @@ -0,0 +1,359 @@ +/** + * `npx scribase login` — sign in without pasting a key, through the OAuth 2.0 + * Device Authorization Grant (RFC 8628): + * + * 1. POST /v1/oauth/device/code → a user code (SCRB-7F3K-Q2MX) and a URL. + * 2. The person opens the URL, signs in, checks the code, picks the + * organization, project, access and lifetime, and approves. + * 3. This command polls POST /v1/oauth/token and receives a scoped, + * expiring agent token (`scb_agt_…`), stores it (OS keychain, else a + * 0600 file) and never prints it. + * + * For coding agents: `--json` prints `{"event":"device_authorization",...}` + * immediately, then one final JSON line. `--no-wait` prints the prompt and + * exits; running `login` again resumes the same request. The pending request + * is stored in the same format as the Rust CLI's, so either can finish it. + * + * All I/O goes through {@link LoginIo} so the flow is testable offline. + */ + +export const GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code'; +export const DEFAULT_SCOPE = 'project:write sql:write migrations:write functions:deploy branches:write'; + +export interface LoginOptions { + apiUrl?: string; + json: boolean; + noWait: boolean; + browser: boolean; + scopes: string[]; + name?: string; +} + +export interface LoginIo { + env: Record; + fetch: typeof fetch; + sleep: (ms: number) => Promise; + /** Unix milliseconds. */ + now: () => number; + /** A human-readable line (stderr in --json mode). */ + log: (line: string) => void; + /** One machine-readable JSON line on stdout. */ + emit: (value: unknown) => void; + openBrowser: (url: string) => void; + /** Whether a person is at the terminal (a TTY). */ + interactive: boolean; + /** Stores the token; returns where it went. Never prints the token. */ + store: (apiUrl: string, token: string) => string; + pending: { read: () => string | null; write: (text: string) => void; clear: () => void }; + /** The API URL stored by an earlier login, if any. */ + storedApiUrl?: () => string | undefined; +} + +export interface Pending { + api_url: string; + device_code: string; + user_code: string; + verification_uri: string; + verification_uri_complete: string; + /** Unix seconds. */ + expires_at: number; + interval: number; +} + +export interface Grant { + access_token: string; + expires_in?: number; + scope: string; + organization_id: string; + project_id: string; +} + +export interface LoginResult { + ok: true; + status: 'approved' | 'pending'; + user_code?: string; + verification_uri_complete?: string; + organization_id?: string; + project_id?: string; + scopes?: string[]; + expires_at?: number | null; + stored_in?: string; + next?: string; + /** Only returned to in-process callers (init), never printed. */ + token?: string; +} + +export class LoginError extends Error { + constructor( + readonly code: string, + message: string, + readonly details: Record = {}, + ) { + super(message); + this.name = 'LoginError'; + } +} + +export const DEFAULT_API_URL = 'https://api.scribase.com'; + +/** Parses `login` arguments. */ +export function parseLoginArgs(argv: string[]): LoginOptions { + const options: LoginOptions = { json: false, noWait: false, browser: true, scopes: [] }; + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index] ?? ''; + const [flag, inline] = arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined]; + const value = (): string => { + const next = inline ?? argv[++index]; + if (next === undefined || next.startsWith('--')) throw new LoginError('invalid_argument', `${flag} needs a value`); + return next; + }; + if (flag === '--json') options.json = true; + else if (flag === '--no-wait') options.noWait = true; + else if (flag === '--no-browser') options.browser = false; + else if (flag === '--api-url') options.apiUrl = value(); + else if (flag === '--name') options.name = value(); + else if (flag === '--scope') options.scopes.push(...value().split(/[\s,]+/).filter(Boolean)); + else if (flag === '--token' || flag === '--with-token') { + throw new LoginError('invalid_argument', 'the npm CLI signs in through the browser only; never paste a key', { + next: 'run `npx scribase login` and approve the code in the browser', + }); + } else throw new LoginError('invalid_argument', `unknown option ${arg}`); + } + return options; +} + +export function renderPending(pending: Pending): string { + return [ + `api_url=${pending.api_url}`, + `device_code=${pending.device_code}`, + `user_code=${pending.user_code}`, + `verification_uri=${pending.verification_uri}`, + `verification_uri_complete=${pending.verification_uri_complete}`, + `expires_at=${pending.expires_at}`, + `interval=${pending.interval}`, + '', + ].join('\n'); +} + +export function parsePending(text: string): Pending | null { + const values = new Map(); + for (const line of text.split('\n')) { + const at = line.indexOf('='); + if (at > 0) values.set(line.slice(0, at).trim(), line.slice(at + 1).trim()); + } + const get = (key: string) => values.get(key) || undefined; + const expires = Number(get('expires_at')); + const interval = Number(get('interval')); + const [api_url, device_code, user_code, verification_uri, verification_uri_complete] = [ + get('api_url'), + get('device_code'), + get('user_code'), + get('verification_uri'), + get('verification_uri_complete'), + ]; + if (!api_url || !device_code || !user_code || !verification_uri || !verification_uri_complete) return null; + if (!Number.isFinite(expires) || !Number.isFinite(interval)) return null; + return { api_url, device_code, user_code, verification_uri, verification_uri_complete, expires_at: expires, interval }; +} + +function form(fields: Record): string { + return new URLSearchParams(fields).toString(); +} + +async function post(io: LoginIo, url: string, fields: Record): Promise<{ status: number; body: Record }> { + let response: Response; + try { + response = await io.fetch(url, { + method: 'POST', + headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json', 'user-agent': 'scribase-login' }, + body: form(fields), + }); + } catch (error) { + throw new LoginError('network_error', `could not reach ${url}: ${(error as Error).message}`); + } + const text = await response.text(); + let body: Record = {}; + try { + const parsed: unknown = text ? JSON.parse(text) : {}; + if (parsed && typeof parsed === 'object') body = parsed as Record; + } catch { + body = { error_description: text.slice(0, 200) }; + } + return { status: response.status, body }; +} + +const text = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined); +const integer = (value: unknown): number | undefined => (typeof value === 'number' && Number.isInteger(value) ? value : undefined); + +function defaultClientName(env: Record): string { + if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) return 'Claude Code (npx scribase)'; + if (env.CURSOR_TRACE_ID) return 'Cursor (npx scribase)'; + if (env.CODEX_SANDBOX || env.CODEX_HOME) return 'Codex (npx scribase)'; + return 'Scribase CLI (npx scribase)'; +} + +/** Starts a device login, or resumes the stored one for this API URL. */ +export async function startDeviceLogin(apiUrl: string, options: LoginOptions, io: LoginIo): Promise { + const nowSeconds = Math.floor(io.now() / 1000); + const stored = io.pending.read(); + const resumed = stored ? parsePending(stored) : null; + if (resumed && resumed.api_url === apiUrl && resumed.expires_at > nowSeconds + 5) return resumed; + const scope = options.scopes.length > 0 ? options.scopes.join(' ') : DEFAULT_SCOPE; + const name = (options.name ?? defaultClientName(io.env)).replace(/[\u0000-\u001f]/g, '').slice(0, 80); + const answer = await post(io, `${apiUrl}/v1/oauth/device/code`, { client_id: 'scribase-cli', client_name: name, scope }); + const b = answer.body; + const [device_code, user_code, verification_uri, verification_uri_complete] = [ + text(b.device_code), + text(b.user_code), + text(b.verification_uri), + text(b.verification_uri_complete), + ]; + if (answer.status !== 200 || !device_code || !user_code || !verification_uri || !verification_uri_complete) { + throw new LoginError( + text(b.error) ?? text(b.code) ?? 'device_code_failed', + `could not start the login: ${text(b.error_description) ?? text(b.detail) ?? `HTTP ${answer.status}`}`, + ); + } + const pending: Pending = { + api_url: apiUrl, + device_code, + user_code, + verification_uri, + verification_uri_complete, + expires_at: nowSeconds + (integer(b.expires_in) ?? 600), + interval: integer(b.interval) ?? 5, + }; + io.pending.write(renderPending(pending)); + return pending; +} + +const FINAL_MESSAGES: Record = { + access_denied: 'the login was denied in the console', + expired_token: 'the code expired before it was approved; run `npx scribase login` again', + invalid_grant: 'this login was already used or is unknown; run `npx scribase login` again', +}; + +type PollAnswer = { grant: Grant } | { wait: number | null }; + +/** One token request: the grant, or how long to wait (`slow_down` may name a new interval). */ +async function pollOnce(pending: Pending, io: LoginIo): Promise { + const answer = await post(io, `${pending.api_url}/v1/oauth/token`, { grant_type: GRANT_TYPE, device_code: pending.device_code }); + const b = answer.body; + const token = text(b.access_token); + if (answer.status === 200 && token) { + const grant: Grant = { + access_token: token, + scope: text(b.scope) ?? '', + organization_id: text(b.organization_id) ?? '', + project_id: text(b.project_id) ?? '', + }; + const expiresIn = integer(b.expires_in); + if (expiresIn !== undefined) grant.expires_in = expiresIn; + return { grant }; + } + const code = text(b.error) ?? text(b.code) ?? `http_${answer.status}`; + if (code === 'authorization_pending') return { wait: null }; + if (code === 'slow_down') return { wait: integer(b.interval) ?? -1 }; + throw new LoginError(code, FINAL_MESSAGES[code] ?? text(b.error_description) ?? text(b.detail) ?? `the token endpoint answered HTTP ${answer.status}`); +} + +/** Polls until the person decides. Honors `slow_down` (the new interval, else +5 s). */ +export async function pollDeviceLogin(pending: Pending, io: LoginIo): Promise { + let interval = Math.min(Math.max(pending.interval, 1), 60); + for (;;) { + if (io.now() / 1000 >= pending.expires_at) { + throw new LoginError('expired_token', FINAL_MESSAGES.expired_token ?? 'expired'); + } + await io.sleep(interval * 1000); + const answer = await pollOnce(pending, io); + if ('grant' in answer) return answer.grant; + if (answer.wait !== null) interval = Math.min(Math.max(answer.wait < 0 ? interval + 5 : answer.wait, 1), 60); + } +} + +function promptEvent(pending: Pending, nowMs: number): Record { + return { + event: 'device_authorization', + verification_uri: pending.verification_uri, + verification_uri_complete: pending.verification_uri_complete, + user_code: pending.user_code, + expires_in: Math.max(0, pending.expires_at - Math.floor(nowMs / 1000)), + message: `Ask the person to open ${pending.verification_uri_complete} and approve code ${pending.user_code}. Never ask them for a key.`, + }; +} + +/** + * Runs `login`. Resolves with the outcome (the token itself only in + * `result.token`, for in-process callers); throws {@link LoginError}. + */ +export async function runLogin(options: LoginOptions, io: LoginIo): Promise { + const apiUrl = (options.apiUrl ?? io.env.SCRIBASE_API_URL ?? io.storedApiUrl?.() ?? DEFAULT_API_URL).replace(/\/+$/, ''); + if (!/^https:\/\/[^\s"\\?#]+$|^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/[^\s"\\?#]*)?$/.test(apiUrl)) { + throw new LoginError('invalid_argument', `${apiUrl} is not an https URL (http only for localhost)`); + } + const stored = io.pending.read(); + const pending = await startDeviceLogin(apiUrl, options, io); + const resumed = stored !== null && parsePending(stored)?.device_code === pending.device_code; + if (options.noWait && resumed) { + // "Run the same command again": ask once whether the person approved in + // the meantime, so a --no-wait rerun finishes instead of re-printing the link. + let answer: PollAnswer; + try { + answer = await pollOnce(pending, io); + } catch (error) { + if (!(error instanceof LoginError && error.code === 'network_error')) io.pending.clear(); + throw error; + } + if ('grant' in answer) return finish(apiUrl, answer.grant, io); + } + if (options.json) { + io.emit(promptEvent(pending, io.now())); + } else { + io.log('To sign in, open this page and approve the code:'); + io.log(''); + io.log(` ${pending.verification_uri_complete}`); + io.log(` code: ${pending.user_code}`); + io.log(''); + if (options.browser && io.interactive) io.openBrowser(pending.verification_uri_complete); + } + if (options.noWait) { + return { + ok: true, + status: 'pending', + user_code: pending.user_code, + verification_uri_complete: pending.verification_uri_complete, + next: 'after the person approves, run the same command again to finish', + }; + } + if (!options.json) io.log('Waiting for approval...'); + let grant: Grant; + try { + grant = await pollDeviceLogin(pending, io); + } catch (error) { + if (!(error instanceof LoginError && error.code === 'network_error')) io.pending.clear(); + throw error; + } + return finish(apiUrl, grant, io); +} + +/** Stores an approved grant and forgets the pending request. */ +function finish(apiUrl: string, grant: Grant, io: LoginIo): LoginResult { + io.pending.clear(); + const storedIn = io.store(apiUrl, grant.access_token); + return { + ok: true, + status: 'approved', + organization_id: grant.organization_id, + project_id: grant.project_id, + scopes: grant.scope.split(' ').filter(Boolean), + expires_at: grant.expires_in === undefined ? null : Math.floor(io.now() / 1000) + grant.expires_in, + stored_in: storedIn, + token: grant.access_token, + }; +} + +/** The result as printed: never the token. */ +export function publicResult(result: LoginResult): Omit { + const { token: _token, ...rest } = result; + return rest; +} diff --git a/src/cli/migrate.ts b/src/cli/migrate.ts new file mode 100644 index 0000000..6867526 --- /dev/null +++ b/src/cli/migrate.ts @@ -0,0 +1,312 @@ +/** + * `npx scribase migrate`: real SQL migration files for the project this + * folder is connected to (after `init`), tracked on disk in `supabase/ + * migrations/*.sql` and run through the control plane's own plan/lint/apply + * route — the same route the generated SDK's `client.migrations` resource + * wraps (`POST .../migrations`), finally wired to this binary. + * + * npx scribase migrate new scaffold a timestamped migration file + * npx scribase migrate plan, lint and apply every migration + * not yet in this environment's ledger + * npx scribase migrate --dry-run plan and lint only; nothing runs + * + * This replaces the old next-step dead end ("SQL migrations ... with + * `scribase db push` from the full CLI") with something that works from this + * same npm package: every local `.sql` file under `supabase/migrations/` is + * sent, oldest first, every time; the server skips versions already applied + * (and refuses if an applied file's SQL changed underneath it — checksum + * drift), so this is always safe to re-run. A table in the `public` schema + * with no RLS policy is blocked before anything executes (`missing_rls`), + * same as it would be for a hand-written `scribase sql` script. + */ + +import { readEnvValue } from './envfile.js'; +import { InitError, STATE_FILE } from './init.js'; +import type { MigrationInput, MigrationLintFinding, RunMigrationsResult } from '../types.gen.js'; + +const DEFAULT_API_URL = 'https://api.scribase.com'; +/** Env files init may have written, most specific first. */ +const ENV_FILES = ['.env.local', '.env'] as const; +/** Where migration files live, relative to the project root. */ +export const MIGRATIONS_DIR = 'supabase/migrations'; +/** `_.sql`: version sorts and parses as the server's i64. */ +const FILE_PATTERN = /^(\d+)_(.+)\.sql$/; +/** Splits a file into its up and (optional) down SQL. */ +const DOWN_MARKER = /^[ \t]*--[ \t]*down[ \t]*$/im; + +export interface MigrateOptions { + action: 'new' | 'run'; + /** `new` only: the name given on the command line. */ + name?: string; + dryRun: boolean; + json: boolean; +} + +export interface MigrateIo { + cwd: string; + env: Record; + fetch: typeof fetch; + readFile: (path: string) => string | null; + writeFile: (path: string, contents: string) => void; + /** Filenames directly inside {@link MIGRATIONS_DIR}; empty if it does not exist. */ + listMigrationFiles: () => string[]; + credentials: () => { apiUrl?: string; token?: string }; + now: () => Date; +} + +export type MigrateResult = + | { ok: true; action: 'new'; version: string; name: string; path: string } + | { + ok: true; + action: 'run'; + dryRun: boolean; + /** How many local `.sql` files were sent (0 when the folder has none yet). */ + files: number; + plan: RunMigrationsResult['plan']; + lintFindings: MigrationLintFinding[]; + applied: number[]; + /** True when a `BLOCK` finding stopped every pending migration from applying. */ + blocked: boolean; + }; + +interface ProjectState { + organization_id: string; + project_id: string; + environment_id: string; + api_url?: string; +} + +/** Parses `migrate` arguments: `new `, or the default run, plus `--dry-run`/`--json`. */ +export function parseMigrateArgs(argv: string[]): MigrateOptions { + const flags = new Set(argv.filter((arg) => arg.startsWith('--'))); + const positional = argv.filter((arg) => !arg.startsWith('--')); + const unknown = [...flags].find((flag) => flag !== '--dry-run' && flag !== '--json'); + if (unknown) throw new InitError('invalid_argument', `unknown option ${unknown}`, 'run `npx scribase migrate --help`'); + const json = flags.has('--json'); + const dryRun = flags.has('--dry-run'); + if (positional[0] === 'new') { + const name = positional[1]; + if (!name) throw new InitError('invalid_argument', 'no migration name given', 'run `npx scribase migrate new `, e.g. `npx scribase migrate new add_notes`'); + return { action: 'new', name, dryRun: false, json }; + } + if (positional.length > 0 && positional[0] !== 'up') { + throw new InitError('invalid_argument', `unknown argument ${positional[0]}`, 'run `npx scribase migrate --help`'); + } + return { action: 'run', dryRun, json }; +} + +/** A filename-safe, lowercase slug; never empty. */ +function slugify(name: string): string { + const slug = name + .trim() + .toLowerCase() + .replace(/[^a-z0-9]+/g, '_') + .replace(/^_+|_+$/g, ''); + return slug || 'migration'; +} + +/** `YYYYMMDDHHMMSS` in UTC: sorts lexically, parses as the server's i64 version. */ +function versionFor(now: Date): string { + const pad = (value: number, length = 2): string => String(value).padStart(length, '0'); + return ( + `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}` + + `${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}` + ); +} + +function join(root: string, relative: string): string { + return `${root.replace(/\/+$/, '')}/${relative}`; +} + +/** The scaffold `npx scribase migrate new ` writes. Both the up and down + * examples are commented out, so an unedited file applies as a real, valid, + * no-op migration (it reserves the version; it changes nothing) rather than + * creating a table the caller never asked for. */ +function scaffold(name: string, slug: string): string { + return [ + `-- ${name}`, + '--', + '-- Edit the SQL below, then run `npx scribase migrate` (or `--dry-run` to', + '-- preview first). Every local file in this folder is sent in version', + '-- order every time; already-applied ones are skipped, so re-running is', + '-- always safe.', + '--', + '-- Scribase blocks a migration before anything runs if it leaves a', + '-- `public`-schema table with no RLS policy (rule `missing_rls`) -- an', + '-- exposed table with RLS off is readable and writable by anyone through', + '-- the REST API. Uncomment and adapt this example, or write your own:', + '--', + `-- create table public.${slug} (`, + '-- id uuid primary key default gen_random_uuid(),', + '-- created_at timestamptz not null default now()', + '-- );', + '--', + `-- alter table public.${slug} enable row level security;`, + '--', + `-- create policy "${slug}_select_own" on public.${slug}`, + '-- for select', + '-- using (auth.uid() is not null);', + '', + '-- down', + '-- SQL here undoes the migration above. Optional: only a future rollback', + '-- command reads it; `npx scribase migrate` never runs it. Example for the', + '-- table above:', + '--', + `-- drop table if exists public.${slug};`, + '', + ].join('\n'); +} + +/** `new`: writes the scaffold and returns where it went. Pure filesystem, no network. */ +function runNew(name: string, io: MigrateIo): MigrateResult { + const slug = slugify(name); + const version = versionFor(io.now()); + const filename = `${version}_${slug}.sql`; + const path = join(join(io.cwd, MIGRATIONS_DIR), filename); + io.writeFile(path, scaffold(name, slug)); + return { ok: true, action: 'new', version, name: slug, path }; +} + +function readProject(io: MigrateIo): ProjectState { + const text = io.readFile(join(io.cwd, STATE_FILE)); + let state: Partial | null = null; + try { + state = text ? (JSON.parse(text) as Partial) : null; + } catch { + state = null; + } + if (!state?.organization_id || !state.project_id || !state.environment_id) { + throw new InitError('not_initialized', 'this folder is not connected to a Scribase project', 'run `npx scribase init` here first'); + } + return state as ProjectState; +} + +function findToken(io: MigrateIo): string | undefined { + const fromEnv = io.env.SCRIBASE_ACCESS_TOKEN?.trim(); + if (fromEnv) return fromEnv; + for (const file of ENV_FILES) { + const contents = io.readFile(join(io.cwd, file)); + const value = contents ? readEnvValue(contents, 'SCRIBASE_ACCESS_TOKEN')?.trim() : undefined; + if (value) return value; + } + return io.credentials().token; +} + +function failure(status: number, body: unknown): InitError { + const value = (body ?? {}) as { code?: unknown; detail?: unknown }; + const code = typeof value.code === 'string' ? value.code : 'request_failed'; + const detail = typeof value.detail === 'string' ? value.detail : 'the request failed'; + const next = + status === 401 || status === 403 + ? 'run `npx scribase login`, or `npx scribase init` again if the temporary project expired' + : undefined; + return new InitError(code, `${detail} (HTTP ${status})`, next); +} + +/** Reads every `_.sql` file, oldest version first, splitting each on the `-- down` marker. */ +function readLocalMigrations(io: MigrateIo): MigrationInput[] { + const files = io.listMigrationFiles().filter((name) => FILE_PATTERN.test(name)); + const parsed = files + .map((filename) => { + const match = FILE_PATTERN.exec(filename); + const version = match?.[1]; + const name = match?.[2]; + if (version === undefined || name === undefined) return null; + const contents = io.readFile(join(join(io.cwd, MIGRATIONS_DIR), filename)) ?? ''; + const splitAt = contents.search(DOWN_MARKER); + const up = (splitAt === -1 ? contents : contents.slice(0, splitAt)).trim(); + const downText = splitAt === -1 ? '' : contents.slice(splitAt).replace(DOWN_MARKER, '').trim(); + // exactOptionalPropertyTypes: omit `down` entirely rather than setting it to undefined. + return { version, name, up, ...(downText.length > 0 ? { down: downText } : {}) } satisfies MigrationInput; + }) + .filter((migration): migration is MigrationInput => migration !== null); + return parsed.sort((left, right) => (BigInt(left.version) < BigInt(right.version) ? -1 : BigInt(left.version) > BigInt(right.version) ? 1 : 0)); +} + +/** `run`: sends every local migration file to this folder's project; the server plans, lints and (unless `--dry-run`) applies. */ +async function runRun(options: MigrateOptions, io: MigrateIo): Promise { + const migrations = readLocalMigrations(io); + if (migrations.length === 0) { + return { ok: true, action: 'run', dryRun: options.dryRun, files: 0, plan: { steps: [] }, lintFindings: [], applied: [], blocked: false }; + } + const project = readProject(io); + const token = findToken(io); + if (!token) { + throw new InitError('not_signed_in', 'no Scribase token for this folder', 'run `npx scribase login`, or `npx scribase init` here'); + } + const apiUrl = (io.env.SCRIBASE_API_URL ?? project.api_url ?? io.credentials().apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''); + const path = + `/v1/organizations/${encodeURIComponent(project.organization_id)}` + + `/projects/${encodeURIComponent(project.project_id)}` + + `/environments/${encodeURIComponent(project.environment_id)}/migrations`; + let response: Response; + try { + response = await io.fetch(`${apiUrl}${path}`, { + method: 'POST', + headers: { + accept: 'application/json', + 'content-type': 'application/json', + 'user-agent': 'scribase-migrate', + authorization: `Bearer ${token}`, + }, + body: JSON.stringify({ migrations, apply: !options.dryRun }), + }); + } catch (error) { + throw new InitError('network_error', `could not reach ${apiUrl}: ${(error as Error).message}`, 'check your connection or SCRIBASE_API_URL'); + } + const text = await response.text(); + let body: unknown = null; + try { + body = text ? JSON.parse(text) : null; + } catch { + body = { detail: text.slice(0, 200) }; + } + if (response.status !== 200) throw failure(response.status, body); + const value = (body ?? {}) as Partial; + const plan = value.plan && Array.isArray(value.plan.steps) ? value.plan : { steps: [] }; + const lintFindings = Array.isArray(value.lintFindings) ? value.lintFindings : []; + const applied = Array.isArray(value.applied) ? value.applied : []; + const blocking = lintFindings.some((finding) => finding.severity === 'BLOCK'); + const blocked = !options.dryRun && plan.steps.length > 0 && applied.length === 0 && blocking; + return { ok: true, action: 'run', dryRun: options.dryRun, files: migrations.length, plan, lintFindings, applied, blocked }; +} + +/** Runs `new` (pure filesystem) or `run` (plan/lint/apply against the control plane). */ +export async function runMigrate(options: MigrateOptions, io: MigrateIo): Promise { + if (options.action === 'new') return runNew(options.name as string, io); + return runRun(options, io); +} + +/** The human-readable output of {@link runMigrate}. */ +export function formatMigrate(result: MigrateResult): string { + if (result.action === 'new') { + return [`Created ${MIGRATIONS_DIR}/${result.version}_${result.name}.sql`, 'Edit it, then run `npx scribase migrate` (or `--dry-run` to preview first).', ''].join('\n'); + } + if (result.files === 0) { + return [`No migration files in ${MIGRATIONS_DIR}/. Run \`npx scribase migrate new \` to create one.`, ''].join('\n'); + } + const lines: string[] = []; + const direction = result.dryRun ? 'would run' : 'ran'; + const pending = result.plan.steps.filter((step) => step.direction === 'up'); + if (pending.length === 0) { + lines.push(`Up to date: all ${result.files} local migration(s) are already applied.`); + } else { + lines.push(`${pending.length} migration(s) ${result.dryRun ? 'pending' : result.blocked ? 'blocked' : direction}:`); + for (const step of pending) { + const state = result.dryRun ? 'planned' : result.applied.includes(step.version) ? 'applied' : 'not applied'; + lines.push(` ${step.version}_${step.name} (${state})`); + } + } + for (const finding of result.lintFindings) { + lines.push(` [${finding.severity}] ${finding.rule}: ${finding.message} (${finding.subject}:${finding.line})`); + } + if (result.blocked) { + lines.push('Nothing applied: a BLOCK finding above stops every pending migration until it is fixed.'); + } else if (result.dryRun && pending.length > 0) { + lines.push('Dry run: nothing applied. Run the same command without --dry-run to apply it.'); + } else if (pending.length > 0 && !result.blocked) { + lines.push('The REST API reloads its schema right after; if a query still says the table is not found, retry in a few seconds.'); + } + lines.push(''); + return lines.join('\n'); +} diff --git a/src/cli/pow.ts b/src/cli/pow.ts new file mode 100644 index 0000000..acd9876 --- /dev/null +++ b/src/cli/pow.ts @@ -0,0 +1,31 @@ +/** + * Solves the proof-of-work challenge a Scribase deployment may ask for before + * it creates an anonymous temporary project: find a nonce so that + * `sha256(":")` starts with `bits` zero bits. + */ + +import { createHash } from 'node:crypto'; + +export function leadingZeroBits(digest: Uint8Array): number { + let bits = 0; + for (const byte of digest) { + if (byte === 0) { + bits += 8; + continue; + } + bits += Math.clz32(byte) - 24; + break; + } + return bits; +} + +/** Returns a nonce solving the challenge (digits only), or throws after `maxAttempts`. */ +export function solveChallenge(challenge: string, bits: number, maxAttempts = 1 << 28): string { + if (bits <= 0) return '0'; + for (let attempt = 0; attempt < maxAttempts; attempt += 1) { + const nonce = attempt.toString(36); + const digest = createHash('sha256').update(`${challenge}:${nonce}`).digest(); + if (leadingZeroBits(digest) >= bits) return nonce; + } + throw new Error(`no proof-of-work solution within ${maxAttempts} attempts`); +} diff --git a/src/cli/sql.ts b/src/cli/sql.ts new file mode 100644 index 0000000..bd880fe --- /dev/null +++ b/src/cli/sql.ts @@ -0,0 +1,204 @@ +/** + * `npx scribase sql "