import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { dedent } from "alchemy/Util/dedent";
import { exec } from "alchemy/Util/exec";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import * as ChildProcess from "effect/process/ChildProcess";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import { effectiveGitHubBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
import { Credentials } from "./Credentials.ts";
import type * as GitHub from "./Providers.ts";
export interface WikiPageProps {
/**
* Repository owner (user or organization).
*/
owner: string;
/**
* Repository name.
*/
repository: string;
/**
* Page title (e.g. `Home`, `Getting Started`). Whitespace becomes hyphens
* in the page name. Changing that name replaces the page (creates a new
* page and deletes the old one if opted in via `allowDelete`).
*/
title: string;
/**
* Page content (supports GitHub Markdown, AsciiDoc, MediaWiki, and more
* depending on the file extension derived from `format`).
*
* The content is automatically dedented, so you can use indented template
* literals without worrying about leading whitespace. Accepts
* `Output<string>` at the call site via `Output.interpolate` to embed
* resource attributes that are not yet resolved.
*/
content: string;
/**
* Commit message for creating or updating the page.
* @default "Update {title}"
*/
message?: string;
/**
* Page format/markup language. The format is appended to the page name as
* an extension (e.g. `markdown` → `Page.md`, `asciidoc` → `Page.asciidoc`).
* @default "markdown"
*/
format?: "markdown" | "asciidoc" | "mediawiki" | "org" | "pod" | "rdoc" | "rest" | "textile";
/**
* Whether to allow deletion of the page when the resource is destroyed.
* By default, wiki pages are never deleted to preserve documentation history.
* @default false
*/
allowDelete?: boolean;
/**
* Override the GitHub host or API base URL for this resource only (e.g.
* `github.example.com` for GitHub Enterprise). Falls back to
* `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
* provider. Changing it replaces the resource — the same name on a
* different GitHub instance is a different physical resource. Authenticated
* wiki Git operations require HTTPS.
*/
baseUrl?: string;
}
export interface WikiPage extends Resource<
"GitHub.WikiPage",
WikiPageProps,
{
/**
* The page title.
*/
title: string;
/**
* The page name in URL form (e.g. `Home`, `Getting-Started`).
*/
pageName: string;
/**
* URL to view the page in a browser.
*/
htmlUrl: string;
/**
* SHA hash of the current page revision.
*/
sha: string;
},
never,
GitHub.Providers
> {}
/**
* A GitHub wiki page.
*
* `WikiPage` manages the lifecycle of a page in a repository's wiki. Wiki
* pages are created on first deploy and updated in place on subsequent
* deploys when the `content` changes. By default, pages are never deleted to
* preserve documentation history — set `allowDelete: true` to opt in.
*
* The repository's wiki must be enabled (`hasWiki: true` on the Repository
* resource) and initialized by creating its first page in the GitHub web UI.
* Enabling the wiki or setting `autoInit` on the repository does not initialize
* the separate wiki Git repository. An inaccessible or uninitialized wiki
* produces `WikiRepositoryUnavailable` with setup instructions.
*
* Git must be installed on the deployment machine. Pages are managed through
* the wiki's Git repository, not the GitHub REST API. Each content or format
* change creates a commit; unchanged pages do not. Concurrent pushes are
* retried against a fresh checkout without force-pushing. Deletion removes the
* current page file, not its Git history. Authentication uses a transient
* process-environment header; tokens are not stored in clone URLs or Git config.
*
* Authentication is resolved via the GitHub `Credentials` service supplied by
* `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token needs
* `repo` scope for private repositories or `public_repo` for public ones.
* ### Creating Wiki Pages
* **Example:** Basic Wiki Page
* ```typescript
* const home = yield* GitHub.WikiPage("home", {
* owner: "my-org",
* repository: "my-repo",
* title: "Home",
* content: "Welcome to the wiki!",
* });
* ```
*
* **Example:** Formatted Wiki Page
* ```typescript
* yield* GitHub.WikiPage("getting-started", {
* owner: "my-org",
* repository: "my-repo",
* title: "Getting Started",
* content: `
* # Getting Started
*
* Install the package:
*
* \`\`\`bash
* npm install my-package
* \`\`\`
* `,
* format: "markdown",
* message: "Add getting started guide",
* });
* ```
*
* ### Updating Wiki Pages
* Deploy with the same logical ID and a different `content` to update the
* existing page in place rather than creating a new one.
*
* **Example:** Update Page Content
* ```typescript
* yield* GitHub.WikiPage("api-docs", {
* owner: "my-org",
* repository: "my-repo",
* title: "API Documentation",
* content: "Updated API documentation content",
* });
* ```
*
* ### Alternative Formats
* **Example:** AsciiDoc Page
* ```typescript
* yield* GitHub.WikiPage("architecture", {
* owner: "my-org",
* repository: "my-repo",
* title: "Architecture",
* content: `
* = System Architecture
*
* == Overview
*
* The system is built with...
* `,
* format: "asciidoc",
* });
* ```
*
* ### Deleting Wiki Pages
* **Example:** Allow Page Deletion
* ```typescript
* const temp = yield* GitHub.WikiPage("temp-page", {
* owner: "my-org",
* repository: "my-repo",
* title: "Temporary Page",
* content: "This page can be deleted",
* allowDelete: true,
* });
* ```
*
* ### Wiring with Other Resources
* **Example:** Create Wiki Pages for a Repository
* Deploy the repository first and create its first wiki page in the GitHub
* web UI before adding `WikiPage` to the stack.
* ```typescript
* import * as Output from "alchemy/Output";
*
* const repo = yield* GitHub.Repository("docs", {
* owner: "my-org",
* name: "docs",
* hasWiki: true,
* autoInit: true,
* });
*
* yield* GitHub.WikiPage("home", {
* owner: repo.owner!,
* repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
* title: "Home",
* content: "Welcome to the documentation wiki!",
* });
* ```
*
* @resource
* @product Repository
*/
export const WikiPage = Resource<WikiPage>("GitHub.WikiPage");
export class WikiRepositoryUnavailable extends Data.TaggedError("WikiRepositoryUnavailable")<{
readonly message: string;
}> {}
export class WikiGitError extends Data.TaggedError("WikiGitError")<{
readonly operation: string;
readonly reason: "missing" | "conflict" | "command";
readonly message: string;
}> {}
export class InvalidWikiPage extends Data.TaggedError("InvalidWikiPage")<{
readonly message: string;
}> {}
const extensions = {
markdown: ["md", "markdown", "mdown", "mkdn", "mkd"],
asciidoc: ["asciidoc", "adoc", "asc"],
mediawiki: ["mediawiki", "wiki"],
org: ["org"],
pod: ["pod"],
rdoc: ["rdoc"],
rest: ["rst", "rest"],
textile: ["textile"],
} as const;
export interface WikiRepository {
readonly remote: string;
readonly htmlUrl: string;
readonly token: Redacted.Redacted<string>;
}
const pageNameFor = (title: string) =>
Effect.gen(function* () {
if (
title.trim() !== title ||
title.length === 0 ||
// oxlint-disable-next-line no-control-regex -- rejects control characters on purpose
/[\x00-\x1f\x7f/\\]/.test(title) ||
title === "." ||
title === ".."
) {
return yield* new InvalidWikiPage({
message:
"Wiki page titles must be nonempty, trimmed names without path separators or control characters.",
});
}
return title.replace(/\s+/g, "-");
});
export const wikiRepository = Effect.fn(function* (props: WikiPageProps) {
yield* pageNameFor(props.title);
if (
![props.owner, props.repository].every(
(part) => /^[A-Za-z0-9_.-]+$/.test(part) && part !== "." && part !== "..",
)
) {
return yield* new InvalidWikiPage({
message: "Wiki owner and repository must be GitHub names, not paths or URLs.",
});
}
const baseUrl = yield* effectiveGitHubBaseUrl(props.baseUrl);
const origin = yield* Effect.sync(() => {
const url = new URL(baseUrl);
// The API host's Git host: api.github.com → github.com, and
// api.<tenant>.ghe.com → <tenant>.ghe.com (data residency).
if (
url.hostname === "api.github.com" ||
(url.hostname.startsWith("api.") && url.hostname.endsWith(".ghe.com"))
) {
url.hostname = url.hostname.slice(4);
}
return url.origin;
});
if (!origin.startsWith("https://")) {
return yield* new InvalidWikiPage({
message: "Wiki Git authentication requires an HTTPS GitHub host.",
});
}
const credentials = yield* yield* Credentials;
const repositoryUrl = `${origin}/${props.owner}/${props.repository}`;
return {
remote: `${repositoryUrl}.wiki.git`,
htmlUrl: `${repositoryUrl}/wiki`,
token: credentials.token,
} satisfies WikiRepository;
});
// Only the transient process environment contains the authorization header.
const gitEnvironment = Effect.fn(function* (repository: WikiRepository, directory: string) {
const path = yield* Path.Path;
const fs = yield* FileSystem.FileSystem;
const config = path.join(directory, "gitconfig");
yield* fs.writeFileString(config, "");
return yield* Effect.sync(() => ({
PATH: process.env.PATH,
SystemRoot: process.env.SystemRoot,
HOME: directory,
LC_ALL: "C",
GIT_TERMINAL_PROMPT: "0",
GIT_CONFIG_NOSYSTEM: "1",
GIT_CONFIG_GLOBAL: config,
GIT_CONFIG_COUNT: "1",
GIT_CONFIG_KEY_0: `http.${repository.remote}.extraHeader`,
GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`x-access-token:${Redacted.value(repository.token)}`).toString("base64")}`,
GIT_AUTHOR_NAME: "Alchemy",
GIT_AUTHOR_EMAIL: "alchemy@users.noreply.github.com",
GIT_COMMITTER_NAME: "Alchemy",
GIT_COMMITTER_EMAIL: "alchemy@users.noreply.github.com",
}));
});
const git = Effect.fn(
function* (directory: string, env: Record<string, string | undefined>, ...args: string[]) {
const operation = args[0]!;
const result = yield* exec(
ChildProcess.make(
"git",
[
"--literal-pathspecs",
"-c",
"credential.helper=",
"-c",
"commit.gpgSign=false",
"-c",
"http.followRedirects=false",
...args,
],
{ cwd: directory, env, extendEnv: false },
),
).pipe(
Effect.mapError(
() =>
new WikiGitError({
operation,
reason: "command",
message: `Unable to run git ${operation}. Ensure Git is installed and executable.`,
}),
),
);
if (result.exitCode !== 0) {
const reason =
/Repository not found|repository '.+' (?:not found|does not exist)|does not appear to be a git repository/i.test(
result.stderr,
)
? "missing"
: operation === "push" &&
/\[rejected\]|cannot lock ref|failed to update ref/i.test(result.stderr)
? "conflict"
: "command";
// Git diagnostics can include server-controlled text or credentials.
return yield* new WikiGitError({
operation,
reason,
message: `git ${operation} failed (exit ${result.exitCode}). Check repository access and GitHub token permissions.`,
});
}
return result.stdout;
},
Effect.scoped,
Effect.timeout("20 seconds"),
);
const checkout = Effect.fn(function* (repository: WikiRepository) {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const directory = yield* fs.makeTempDirectoryScoped({
prefix: "alchemy-wiki-",
});
const env = yield* gitEnvironment(repository, directory);
yield* git(directory, env, "clone", "--quiet", "--", repository.remote, "wiki").pipe(
Effect.catchTag("WikiGitError", (error) =>
Effect.fail(
error.reason === "missing"
? new WikiRepositoryUnavailable({
message: `Cannot access ${repository.htmlUrl}. Enable the repository wiki and create its first page in the GitHub web UI before deploying WikiPage. Git cannot initialize a GitHub wiki that has never had a page. If it is already initialized, verify the repository name and token's repository access.`,
})
: error,
),
),
);
const cwd = path.join(directory, "wiki");
const run = (...args: string[]) => git(cwd, env, ...args);
const files = (yield* run("ls-files", "-z")).split("\0").filter(Boolean);
return { cwd, run, files };
});
type Checkout = Effect.Success<ReturnType<typeof checkout>>;
const pageFiles = (files: string[], pageName: string) =>
Object.values(extensions)
.flatMap((formats) => formats.map((extension) => `${pageName}.${extension}`))
.filter((file) => files.includes(file));
const attributes = Effect.fn(function* (
repository: WikiRepository,
props: WikiPageProps,
wiki: Checkout,
file: string,
) {
return {
title: props.title,
pageName: props.title.replace(/\s+/g, "-"),
htmlUrl: `${repository.htmlUrl}/${encodeURIComponent(props.title.replace(/\s+/g, "-"))}`,
sha: (yield* wiki.run("log", "-1", "--format=%H", "--", file)).trim(),
} satisfies WikiPage["Attributes"];
});
export const readWikiPage = Effect.fn(
function* (repository: WikiRepository, props: WikiPageProps) {
const pageName = yield* pageNameFor(props.title);
const wiki = yield* checkout(repository);
const files = pageFiles(wiki.files, pageName);
const desired = `${pageName}.${extensions[props.format ?? "markdown"][0]}`;
const file = files.includes(desired) ? desired : files[0];
return file === undefined ? undefined : yield* attributes(repository, props, wiki, file);
},
Effect.scoped,
(effect) => effect.pipe(Effect.catchTag("WikiRepositoryUnavailable", () => Effect.undefined)),
);
const retryConcurrentPush = <A, E, R>(effect: Effect.Effect<A, E | WikiGitError, R>) =>
effect.pipe(
Effect.retry({
while: (error) => error instanceof WikiGitError && error.reason === "conflict",
schedule: Schedule.spaced("200 millis"),
times: 3,
}),
Effect.timeout("60 seconds"),
);
export const syncWikiPage = Effect.fn(
function* (repository: WikiRepository, props: WikiPageProps) {
const pageName = yield* pageNameFor(props.title);
const wiki = yield* checkout(repository);
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const files = pageFiles(wiki.files, pageName);
const file = `${pageName}.${extensions[props.format ?? "markdown"][0]}`;
const content = dedent(props.content);
const observed = wiki.files.includes(file)
? yield* wiki.run("show", `HEAD:${file}`)
: undefined;
const mode = wiki.files.includes(file)
? yield* wiki.run("ls-files", "--stage", "--", file)
: "";
if (
observed !== content ||
files.some((existing) => existing !== file) ||
mode.startsWith("120000")
) {
if (files.length > 0) yield* wiki.run("rm", "--", ...files);
yield* fs.writeFileString(path.join(wiki.cwd, file), content);
yield* wiki.run("add", "--", file);
yield* wiki.run("commit", "--quiet", "-m", props.message ?? `Update ${props.title}`);
yield* wiki.run("push", "--quiet", "origin", "HEAD");
}
return yield* attributes(repository, props, wiki, file);
},
Effect.scoped,
retryConcurrentPush,
);
export const deleteWikiPage = Effect.fn(
function* (repository: WikiRepository, props: WikiPageProps) {
if (!props.allowDelete) return;
const pageName = yield* pageNameFor(props.title);
const wiki = yield* checkout(repository);
const files = pageFiles(wiki.files, pageName);
if (files.length === 0) return;
yield* wiki.run("rm", "--", ...files);
yield* wiki.run("commit", "--quiet", "-m", `Delete ${props.title}`);
yield* wiki.run("push", "--quiet", "origin", "HEAD");
},
Effect.scoped,
retryConcurrentPush,
(effect) => effect.pipe(Effect.catchTag("WikiRepositoryUnavailable", () => Effect.void)),
);
export const WikiPageProvider = () =>
Provider.succeed(WikiPage, {
stables: ["pageName"],
// Wiki pages have no account-wide enumeration API.
list: () => Effect.succeed([]),
// Replacement must not delete the successor when titles normalize identically.
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
if (
news.owner !== olds.owner ||
news.repository !== olds.repository ||
news.title.replace(/\s+/g, "-") !== olds.title.replace(/\s+/g, "-") ||
(yield* gitHubBaseUrlChanged(olds, news))
) {
return { action: "replace" };
}
}),
read: Effect.fn(function* ({ olds }) {
return yield* readWikiPage(yield* wikiRepository(olds), olds);
}),
reconcile: Effect.fn(function* ({ news }) {
return yield* syncWikiPage(yield* wikiRepository(news), news);
}),
delete: Effect.fn(function* ({ olds }) {
if (!olds.allowDelete) return;
yield* deleteWikiPage(yield* wikiRepository(olds), olds);
}),
});