diff --git a/apps/cli/docs/README.md b/apps/cli/docs/README.md index 29d875b400..186bacb02f 100644 --- a/apps/cli/docs/README.md +++ b/apps/cli/docs/README.md @@ -1,17 +1,45 @@ -# CLI reference +# CLI Reference Source content for the [CLI reference](https://supabase.com/docs/reference/cli) published on the Supabase docs site. - `supabase/` — long-form command descriptions, one file per command path - `templates/examples.yaml` — per-command usage examples, keyed by doc id -## Build +## Local Preview -```bash -bun scripts/generate-docs-spec.ts > cli_v1_commands.yaml -``` +For CLI contributors, preview reference changes in the real website before publishing: + +1. Clone [supabase/supabase](https://github.com/supabase/supabase) into a separate directory. + Follow the docs app's [local setup instructions](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md#local-setup) + to install its dependencies and configure the development environment. +2. In this CLI repository, install dependencies with `pnpm install --frozen-lockfile`, then run + `pnpm exec turbo run @supabase/config#build` from the repository root. +3. From this repository's `apps/cli` directory, generate and write the preview: + + ```bash + set -o pipefail + bun scripts/generate-docs-spec.ts 0.0.0 | bun scripts/publish-docs-spec.ts --version 0.0.0 --local /absolute/path/to/supabase + ``` + + Replace the path with the root of your `supabase/supabase` checkout. A relative path resolves + from the current directory. Both version arguments must match; `0.0.0` is a preview value. + +4. Start that checkout's docs app using its linked local setup instructions, then visit + `/docs/reference/cli/supabase-init` on the local server to inspect a rendered command page. + Rerun the pipe after changing CLI documentation. -## Release +`--local` overwrites `apps/docs/spec/cli_v1_commands.yaml` in the supplied checkout using the +same formatting as release publishing. Save any edits to that file first. If formatting fails, +the file contains the unformatted generated spec; fix the error and rerun the pipe. The target +directory must already exist. Local mode does not clone, commit, push, or open a PR, and needs no GitHub +credentials. Add `--dry-run` to validate the input and print the destination without writing. + +This preview writes only the command-reference spec, not sidebar entries or JSON Schemas. +New commands still need an entry in the website's +[common-cli-sections.json](https://github.com/supabase/supabase/blob/master/apps/docs/spec/common-cli-sections.json) +to appear in the reference. + +## Release Publishing The `docs` job in `.github/workflows/release.yml` publishes the reference on every stable release: it pipes the generator into `scripts/publish-docs-spec.ts`, which formats the spec, @@ -21,11 +49,6 @@ or not needed, the run is a no-op. Later releases add commits on top of an open `cli/ref-doc` PR instead of rewriting it, so fixes committed onto the branch survive. -New commands also need an entry in -[common-cli-sections.json](https://github.com/supabase/supabase/blob/master/apps/docs/spec/common-cli-sections.json) -— the sidebar decides which pages exist, and a command without an entry is silently -dropped from the docs site. - To publish by hand, run the same pipe the job runs: ```bash diff --git a/apps/cli/scripts/publish-docs-spec.e2e.test.ts b/apps/cli/scripts/publish-docs-spec.e2e.test.ts index f13b0a7340..021e58bd6c 100644 --- a/apps/cli/scripts/publish-docs-spec.e2e.test.ts +++ b/apps/cli/scripts/publish-docs-spec.e2e.test.ts @@ -1,17 +1,27 @@ import { fileURLToPath } from "node:url"; -import { describe, expect, it } from "vitest"; -import { stringify } from "yaml"; +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { Effect, FileSystem, Path } from "effect"; +import { parse, stringify } from "yaml"; const cliRoot = fileURLToPath(new URL("..", import.meta.url)); function runScript( args: ReadonlyArray, stdin: string, + prependPath?: string, ): { exitCode: number; stdout: string; stderr: string } { const { FORCE_COLOR: _forceColor, NO_COLOR: _noColor, ...environment } = process.env; const result = Bun.spawnSync(["bun", "scripts/publish-docs-spec.ts", ...args], { cwd: cliRoot, - env: environment, + env: { + ...environment, + ...(prependPath === undefined + ? {} + : { + PATH: `${prependPath}${process.platform === "win32" ? ";" : ":"}${environment["PATH"] ?? ""}`, + }), + }, stdin: Buffer.from(stdin), }); return { @@ -29,6 +39,119 @@ function validSpec(version: string): string { }); } +const localCheckout = Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const root = yield* fs.makeTempDirectoryScoped({ prefix: "docs-preview-" }); + const checkout = path.join(root, "local checkout"); + const directory = path.join(checkout, "apps/docs/spec"); + yield* fs.makeDirectory(directory, { recursive: true }); + const target = path.join(directory, "cli_v1_commands.yaml"); + yield* fs.writeFileString(target, "original spec\n"); + return { root, checkout, target }; +}); + +describe("local reference preview", () => { + it.effect("writes formatted YAML without Git or GitHub operations", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const { root, checkout, target } = yield* localCheckout; + const bin = path.join(root, "bin"); + yield* fs.makeDirectory(bin); + // Fail closed if preview accidentally reaches the remote publishing workflow. + for (const command of ["git", "gh"]) { + const executable = path.join(bin, command); + yield* fs.writeFileString( + executable, + "#!/bin/sh\necho 'Unexpected publishing operation' >&2\nexit 99\n", + ); + yield* fs.chmod(executable, 0o755); + } + const spec = validSpec("1.0.0"); + const { exitCode, stdout, stderr } = yield* Effect.sync(() => + runScript( + ["--version", "v1.0.0", "--local", path.relative(cliRoot, checkout)], + spec.replace("clispec:", "clispec: "), + bin, + ), + ); + + expect(exitCode, stderr).toBe(0); + const written = yield* fs.readFileString(target); + expect(parse(written)).toEqual(parse(spec)); + expect(written).toContain("clispec: '001'\n"); + expect(written.endsWith("\n")).toBe(true); + expect(stdout).toContain("Wrote CLI reference to "); + expect(yield* fs.exists(path.join(checkout, ".git"))).toBe(false); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.effect("leaves the local spec unchanged during a dry run", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const { checkout, target } = yield* localCheckout; + const { exitCode, stdout, stderr } = yield* Effect.sync(() => + runScript(["--version", "1.0.0", "--local", checkout, "--dry-run"], validSpec("1.0.0")), + ); + + expect(exitCode, stderr).toBe(0); + expect(stdout).toContain(`Would write ${validSpec("1.0.0").length} bytes to `); + expect(yield* fs.readFileString(target)).toBe("original spec\n"); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.effect("refuses invalid input before overwriting the local spec", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const { checkout, target } = yield* localCheckout; + const { exitCode, stderr } = yield* Effect.sync(() => + runScript(["--version", "1.0.0", "--local", checkout], validSpec("2.0.0")), + ); + + expect(exitCode).toBe(1); + expect(stderr).toContain("does not match --version 1.0.0"); + expect(yield* fs.readFileString(target)).toBe("original spec\n"); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.effect("refuses a spec path outside the checkout without overwriting it", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const { root, checkout } = yield* localCheckout; + const outside = path.join(root, "outside.yaml"); + yield* fs.writeFileString(outside, "keep this file\n"); + const { exitCode, stderr } = yield* Effect.sync(() => + runScript( + ["--version", "1.0.0", "--local", checkout, "--spec-path", "../outside.yaml"], + validSpec("1.0.0"), + ), + ); + + expect(exitCode).toBe(1); + expect(stderr).toContain("a --spec-path inside it"); + expect(yield* fs.readFileString(outside)).toBe("keep this file\n"); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.effect("refuses a missing checkout without creating it", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const { root } = yield* localCheckout; + const missing = path.join(root, "missing"); + const { exitCode, stderr } = yield* Effect.sync(() => + runScript(["--version", "1.0.0", "--local", missing], validSpec("1.0.0")), + ); + + expect(exitCode).toBe(1); + expect(stderr).toContain("Point --local at an existing supabase/supabase checkout"); + expect(yield* fs.exists(missing)).toBe(false); + }).pipe(Effect.provide(BunServices.layer)), + ); +}); + describe("publish-docs-spec.ts entrypoint", () => { it("prints usage and fails without --version", () => { const { exitCode, stderr } = runScript(["--dry-run"], validSpec("1.0.0")); diff --git a/apps/cli/scripts/publish-docs-spec.ts b/apps/cli/scripts/publish-docs-spec.ts index b937b64c9e..f0474328cf 100644 --- a/apps/cli/scripts/publish-docs-spec.ts +++ b/apps/cli/scripts/publish-docs-spec.ts @@ -1,6 +1,6 @@ /** * Publishes the generated CLI reference to the docs site by opening a PR against - * supabase/supabase. Reads the spec on stdin: + * supabase/supabase, or writes it to a local checkout with --local. Reads the spec on stdin: * * bun scripts/generate-docs-spec.ts | bun scripts/publish-docs-spec.ts --version * @@ -26,6 +26,7 @@ function jsonText(value: unknown): string { const { values } = parseArgs({ options: { version: { type: "string" }, + local: { type: "string" }, repo: { type: "string", default: "supabase/supabase" }, "spec-path": { type: "string", default: "apps/docs/spec/cli_v1_commands.yaml" }, branch: { type: "string", default: "cli/ref-doc" }, @@ -41,17 +42,40 @@ const main = Effect.gen(function* () { const versionArgument = values.version; if (!versionArgument) { yield* Console.error( - "Usage: bun scripts/generate-docs-spec.ts | bun scripts/publish-docs-spec.ts --version [--repo ] [--spec-path ] [--branch ] [--base ] [--dry-run]", + "Usage: bun scripts/generate-docs-spec.ts | bun scripts/publish-docs-spec.ts --version [--repo ] [--spec-path ] [--branch ] [--base ] [--local ] [--dry-run]", ); return yield* Effect.sync(() => process.exit(1)); } const version = versionArgument.startsWith("v") ? versionArgument.slice(1) : versionArgument; - const repo = values.repo!; - const specPath = values["spec-path"]!; - const branch = values.branch!; - const base = values.base!; - const dryRun = values["dry-run"]!; + const repo = values.repo ?? "supabase/supabase"; + const specPath = values["spec-path"] ?? "apps/docs/spec/cli_v1_commands.yaml"; + const branch = values.branch ?? "cli/ref-doc"; + const base = values.base ?? "master"; + const dryRun = values["dry-run"] ?? false; + const localDir = values.local === undefined ? undefined : path.resolve(values.local); + + if (localDir !== undefined) { + const relativeTarget = path.relative(localDir, path.resolve(localDir, specPath)); + if ( + values.local === "" || + path.isAbsolute(specPath) || + relativeTarget === ".." || + relativeTarget.startsWith(`..${path.sep}`) || + path.isAbsolute(relativeTarget) + ) { + yield* Console.error( + "Refusing local preview: provide a checkout path and a --spec-path inside it.", + ); + return yield* Effect.sync(() => process.exit(1)); + } + if (!(yield* fs.exists(path.join(localDir, path.dirname(specPath))))) { + yield* Console.error( + "Refusing local preview: the spec directory does not exist. Point --local at an existing supabase/supabase checkout.", + ); + return yield* Effect.sync(() => process.exit(1)); + } + } const spec = yield* Effect.tryPromise({ try: () => Bun.stdin.text(), @@ -95,27 +119,37 @@ const main = Effect.gen(function* () { if (dryRun) { yield* Console.log( - `Would publish ${spec.length} bytes to ${repo}:${specPath} on branch ${branch}`, + localDir === undefined + ? `Would publish ${spec.length} bytes to ${repo}:${specPath} on branch ${branch}` + : `Would write ${spec.length} bytes to ${path.join(localDir, specPath)}`, ); return yield* Effect.sync(() => process.exit(0)); } const prettier = path.resolve(import.meta.dir, "../node_modules/.bin/prettier"); + const writeSpec = Effect.fn("Docs.writeSpec")(function* (checkoutDir: string) { + const target = path.join(checkoutDir, specPath); + yield* fs.writeFileString(target, spec); + yield* shell( + () => + $`${prettier} --no-config --single-quote --print-width 100 --log-level warn --write ${target}`, + ); + yield* Effect.annotateCurrentSpan("docs.commands.count", commands.length); + }); + + if (localDir !== undefined) { + yield* writeSpec(localDir); + yield* Console.log(`Wrote CLI reference to ${path.join(localDir, specPath)}`); + return; + } + const message = "chore: update cli reference doc"; yield* publishPullRequest({ repo, base, branch, stagedPath: specPath, - write: (checkoutDir) => - Effect.gen(function* () { - const target = path.join(checkoutDir, specPath); - yield* fs.writeFileString(target, spec); - yield* shell( - () => - $`${prettier} --no-config --single-quote --print-width 100 --log-level warn --write ${target}`, - ); - }), + write: writeSpec, commitMessage: message, pullRequestTitle: message, pullRequestBody: [